Commit b0f678d7 authored by Genial-O's avatar Genial-O
Browse files

merge(dev): release 19.0.0

parents 580e11d6 8d1771af
......@@ -12,8 +12,14 @@ syntax: glob
.*~
*.autosave
# qtcreator cmake preferences
*.txt.user
*.txt.user*
# reject and backup file
*.rej
*.orig
_build/
\ No newline at end of file
# macos
.DS_Store
# vs cmake project files
\.vs*
CMakeSettings\.json
......@@ -5,7 +5,7 @@ stages:
- deploy
sheldon-mr:
image: ${DOCKER_ENVDEV_CLANG6}
image: ${DOCKER_ENVDEV_MINT19}
stage: sheldon
script:
- export ORIG_BRANCH_COMMIT_SHA=$(git merge-base dev origin/${CI_COMMIT_REF_NAME})
......@@ -14,7 +14,7 @@ sheldon-mr:
- sight-git/hooks/sheldon ${ORIG_BRANCH_COMMIT_SHA}..${CI_COMMIT_SHA}
sheldon:
image: ${DOCKER_ENVDEV_CLANG6}
image: ${DOCKER_ENVDEV_MINT19}
stage: sheldon
script:
- git -c http.sslVerify=false clone --depth 1 https://gitlab-ci-token:${CI_JOB_TOKEN}@git.ircad.fr/Sight/sight-git.git
......@@ -38,7 +38,7 @@ markdown-lint:
- echo {\"MD013\":{\"line_length\":120}} > .markdownlint.json
- markdownlint --config .markdownlint.json .
doxygen:
build-doc:
image: python:3
stage: build
script:
......@@ -53,7 +53,7 @@ doxygen:
pages:
stage: deploy
dependencies:
- doxygen
- build-doc
script:
- mv _build/html/ public/
artifacts:
......
......@@ -25,6 +25,8 @@
- Issues
- Fixes repo#number
- [ ] depends on repo#number
- Merge requests
- repo!number
- See also repo!number
- [ ] depends on repo!number
.. _qtcreatorsetup:
Setting up QtCreator on windows
================================
***************************************
How to configure QtCreator on Windows ?
***************************************
Sight contains a substantial amount of code, with numerous nested inclusions, type redefinitions and other advanced
architecture webbings. This makes finding the right IDE and configuring it correctly a bit of a hassle. Below you will
......@@ -16,7 +15,7 @@ We will be using 4.7.2, newer versions may work as well, but we recommend `this
Installation is pretty straight forward, you only need to make sure the ``CDB Debugger`` is checked (which is the case
by default)
.. image:: ../media/QtCreator/CDBDebugger.png
.. image:: media/QtCreator/CDBDebugger.png
Managing your kits
------------------
......@@ -32,7 +31,7 @@ right Visual Studio version.
Below you will find an example of two versions of compilers found by the same QtCreator instance.
.. image:: ../media/QtCreator/KitCompiler.png
.. image:: media/QtCreator/KitCompiler.png
Opening your sight project
......@@ -41,7 +40,7 @@ Opening your sight project
You'll need to select the ``CMakeLists.txt`` of your ``Sight`` sources from the ``File>Open File or Project`` menu in
QtCreator
.. image:: ../media/QtCreator/OpenProject.png
.. image:: media/QtCreator/OpenProject.png
Choosing kit and build location
-------------------------------
......@@ -49,11 +48,11 @@ Choosing kit and build location
You will be asked to chose a kit (Desktop by default) and what type of build you want to configure. You can choose
previously compiled and configured locations of your Sight builds.
.. image:: ../media/QtCreator/ConfigureProject.png
.. image:: media/QtCreator/ConfigureProject.png
You will see a similar view to ``cmake-gui`` output, and all the previously set options should be set correctly.
.. image:: ../media/QtCreator/CMake.png
.. image:: media/QtCreator/CMake.png
.. note::
You can actually perform the `Configuration <Configuration>`_ step directly in QtCreator!
......@@ -66,19 +65,19 @@ use the PATH variable modifications it generated in-order to be able to run buil
Select the Run tab.
.. image:: ../media/QtCreator/BuildAndRun.png
.. image:: media/QtCreator/BuildAndRun.png
In the Run configuration select fwlauncher, here you will find all of the generated tests.
Find the ``profile.xml`` of the application you want to run and fill the ``Command line argument`` with its full path.
Fill-in the ``Working Directory``. Your configuration should look something like this :
.. image:: ../media/QtCreator/RunLauncher.png
.. image:: media/QtCreator/RunLauncher.png
And finally, open your application script ``Dev/Sight/Build/bin/ApplicationName.bat`` and copy the whole line
``SET "PATH`` from the ``=`` symbol to the last ``;``. Find the ``Path`` variable and replace it with ``%{PATH};``
followed by the chunk you copied. This sets all Conan path location to your build environment.
.. image:: ../media/QtCreator/RunEnvironment.png
.. image:: media/QtCreator/RunEnvironment.png
You can ``Add>Clone Selected`` in order to save this configuration, and you are all set! Try to launch qtCreator
Debugger (F5) and see if it is working properly.
......
......@@ -11,3 +11,4 @@ How-Tos
HowTo-ApplicationCreation.rst
HowTo-DepsCreation.rst
HowTo-troubleshooting.rst
HowTo-QtCreatorSetup.rst
.. _Installation:
******************************************
Installation
******************************************
============
Introduction
------------
From `Conan documentation <https://docs.conan.io/en/latest/>`_ :
"Conan is a portable package manager, intended for C and C++ developers, but it is able to manage builds from source,
dependencies, and pre-compiled binaries for any language."
This means that by using Conan we are no longer required to build dependencies ourselves. By following these
instructions, you will be able to build sight with downloaded pre-compiled dependencies.
Note that all dependencies packages can be found in our very own
`Artifactory webpage <https://conan.ircad.fr/artifactory/webapp/#/home>`_
Prerequisites
-------------
.. tabs::
.. group-tab:: Linux
For now, only Linux Mint 18 and 19 distributions are supported, other distributions may work but have
not been tested.
.. group-tab:: Windows
For now, only `Visual Studio 2017` is supported, other versions may work but have not been tested.
.. group-tab:: Mac OSX
For now, only `Mojave 10.14` is supported, other versions may work but have not been tested.
If not already installed:
#. Install `git <https://git-scm.com/>`_
#. Install `Python 3.5 or greater <https://www.python.org/downloads/>`_
#. Install `CMake <http://www.cmake.org/download/>`_ Version 3.12 or later is required. You should use prebuilt binaries as it is safer.
#. Install `ninja <https://github.com/ninja-build/ninja/releases>`_
#. Install `Conan <https://docs.conan.io/en/latest/installation.html>`_ (you can use Python's ``pip``, but be sure to use python ``3`` -- you can check this by running ``pip --version``)
Install a c++ compiler and other development libraries.
.. tabs::
.. group-tab:: Linux
Install `gcc 7 <https://gcc.gnu.org/>`_ or `clang 6.0 <http://clang.llvm.org/>`_ (As pre-built packages are
only compiled with this versions).
Depending on which linux distribution you use,
for example on **Mint**, you can run the following command to download and install these tools:
.. code:: bash
$ sudo apt-get install build-essential ninja-build python3 git
And dependency development libraries :
.. code:: bash
$ sudo apt-get install libz3-dev libiconv-hook-dev libpng-dev libjpeg-turbo8-dev \
libtiff5-dev libfreetype6-dev libxml2-dev libexpat1-dev libicu-dev libfontconfig1-dev \
libx264-dev libx265-dev libusb-dev libusb-1.0-0-dev libxcb.*-dev libx11-xcb-dev \
libglu1-mesa-dev libglew-dev libvlc-dev libvlccore-dev vlc libxrender-dev libxi-dev \
libasound2-dev libgstreamer1.0-dev libssl-dev libxt-dev libgstreamer-plugins-*1.0-dev \
libudev-dev libxaw7-dev libxrandr-dev libavcodec-dev libavutil-dev libavformat-dev \
libswscale-dev libavresample-dev
.. group-tab:: Windows
Install `Visual Studio 2017 Community <https://visualstudio.microsoft.com/>`_
.. group-tab:: Mac OSX
Install `Xcode 10.1 <https://itunes.apple.com/fr/app/xcode/id497799835?mt=12>`_
For an easy install, you can use the `Homebrew project <http://brew.sh/>`_ to install missing packages.
Brewed python is python ``3`` and is required since default macOS python is ``2``
.. code:: bash
$ brew install git
& brew install python
$ brew install cmake
$ brew install ninja
Source tree layout
~~~~~~~~~~~~~~~~~~~
Good practices in Sight recommend to separate source files, build and install folders.
So to prepare the development environment:
* Create a development folder (Dev)
* Create a build folder (Dev/Build)
* Add a sub folder for Debug and Release.
* Create a source folder (Dev/Src)
* Create an install folder (Dev/Install)
* Add a sub folder for Debug and Release.
|directories|
Of course you can name the folders as you wish, or choose a different layout, but keep in mind to not build inside the
source directory. This is strongly discouraged by *CMake* authors.
.. |directories| image:: media/DirectoriesNoDeps.png
.. _settingUpEnv:
Setting up your environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. tabs::
.. group-tab:: Linux
Make sure all of your Prerequisites_ are loaded into your path correctly, for all installation made through
`apt-get` this is done automatically but for manually downloaded binaries (e.g. CMake) you'll need to use
this command :
.. code::
$ PATH=$HOME/<cmake-bin-path>:$PATH
.. tip::
Adding this line to a start-up script can save you time and effort!
.. group-tab:: Windows
Load into your active PATH environment variable the needed locations in-order to be able to build.
* Add Visual studio compilers.
You can use the 'VS2017 x64 Native Tools Command Prompt' or launch the `vcvarsall.bat` script with the parameter
`amd64` on your current console.
The location of that script will look something like this
``C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvarsall.bat``
* Add the Prerequisites_
If installed with default parameters ``git``, ``CMake`` and ``Python`` will be automatically loaded into your PATH
variable.
For static binaries like ``Ninja`` you will need to add them manually with a command similar to :
.. code:: bash
> PATH=%PATH%;C:\Bin
.. tip::
Writing a ``.bat`` script that loads all these previous locations to your path can save you time and effort!
.. group-tab:: Mac OSX
Make sure all of your Prerequisites_ are loaded into your path correctly, for all installation made through
`brew` this is done automatically but for manually downloaded binaries you'll need to do it yourself.
If you haven't done it, launch Xcode at least one time and install the ``Command Line Tools`` when prompted.
You can do this manually by using the following command:
.. code:: bash
$ xcode-select --install
If you already had installed the ``Command Line Tools``, it may be a good idea to check that the currently used ones are the default:
.. code:: bash
$ xcode-select --print-path
/Applications/Xcode.app/Contents/Developer
If the above command prints something different, you may reset to the default with:
.. code:: bash
$ sudo xcode-select --reset
Building your sources
----------------------
* `Clone <http://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository#Cloning-an-Existing-Repository>`_ the following repository in the (Dev/Src) source folder:
* `sight <https://git.ircad.fr/Sight/sight.git>`_
.. code:: bash
$ cd Dev/Src
$ git clone https://git.ircad.fr/Sight/sight.git
* Go into your Build directory (Debug or Release) : here is an example if you want to compile in debug:
.. code:: bash
$ cd Dev/Build/Debug
.. warning:: Make sure your environment is properly set : :ref:`settingUpEnv` .
* Call cmake-gui.
.. code:: bash
$ cmake-gui .
Configuration
~~~~~~~~~~~~~~~~
* Set the desired Build directory (e.g. Dev/Build/Debug or Release)
* Set the desired Source directory (e.g. Dev/Src/sight)
* Click on "configure".
* During configure step, choose the generator 'Ninja' to compile Sight sources.
Generation
~~~~~~~~~~~~~~
* Set the following arguments:
``CMAKE_INSTALL_PREFIX``:
Set the install location (e.g. Dev/Install/Debug).
``CMAKE_BUILD_TYPE``:
Set to Debug or Release.
``PROJECTS_TO_BUILD``:
Set the names of the applications to build (see Dev/Src/Apps or Dev/Src/Samples, ex: VRRender, Tuto01Basic ...),
each project should be separated by ";".
.. note::
- If ``PROJECTS_TO_BUILD`` is empty, all application will be compiled.
* Click on "generate".
If you want to launch the ``cmake`` through the command line with the appropriate parameters
.. code:: bash
$ cd Dev/Build/Debug
$ cmake <path_to_sources> -G "Ninja" -DCMAKE_INSTALL_PREFIX=<Path_to_install_dir> -DCMAKE_BUILD_TYPE=Debug
Build
~~~~~~~
* Compile the Sight source using ninja in the console:
* Go to the build directory (e.g. Dev/Build/Debug or Release)
* Use "ninja" if you want to compile all the applications set in CMake.
* Use "ninja name_of_application" to compile only one of the applications set in CMake.
.. code:: bash
$ cd Dev/Build/Debug
$ ninja
Launch an application
---------------------
After a successful compilation any previously built application can be launched with the appropriate script from Sight.
.. tabs::
.. group-tab:: Linux
You will find in the ``Build/bin`` directory an automatically generated script with the same name (on lowercase)
as the application you built.
.. code:: bash
$ cd Dev/Build/Debug
$ ./bin/myapplication
.. group-tab:: Windows
You will find in the ``Build\bin`` directory an automatically generated ``.bat`` with the same name (on
lowercase) as the application you built.
.. code:: bash
$ cd Dev/Build/Debug
$ ./bin/myapplication.bat
.. group-tab:: Mac OSX
You will find in the ``Build/bin`` directory an automatically generated script with the same name (on lowercase)
as the application you built.
.. code:: bash
$ cd Dev/Build/Debug
$ ./bin/myapplication
.. important::
This automatically generated script loads all the needed Conan packages locations and adds them temporarily to your
PATH variable. Feel free to take a look inside.
Generate an installer
---------------------
After setting the applications for which you want to generate installers in the ``PROJECTS_TO_BUILD`` CMake variable
and generating the code, follow these two steps:
* Run *ninja install application_to_install* in the Build directory
* Run *ninja package* in the Build directory
The installer will be generated in the Build directory.
.. note::
This functionality is only fully supported on Windows and Linux distributions.
For Mac OSX, ninja install will generate a ``.app`` and works only on some applications.
Recommended software
--------------------
The following programs may be helpful for your developments:
.. tabs::
Installation from source
------------------------
.. group-tab:: Linux
.. toctree::
:maxdepth: 1
* `QT Creator <https://download.qt.io/official_releases/qtcreator/>`_:
QT Creator is a multi-OS Integrated Development Environment (IDE) for computer programming.
You can find a setup tutorial here :ref:`qtcreatorsetup`.
src/WindowsInstall
src/LinuxInstall
src/MacOSXInstall
.. group-tab:: Windows
Installation With Conan (pre-built dependencies)
------------------------------------------------
* `QT Creator <https://download.qt.io/official_releases/qtcreator/>`_:
QT Creator is a multi-OS Integrated Development Environment (IDE) for computer programming.
You can find a setup tutorial here :ref:`qtcreatorsetup`.
* `Notepad++ <http://notepad-plus-plus.org/>`_:
Notepad++ is a free source code editor, which is designed with syntax highlighting functionality.
* `ConsoleZ <https://github.com/cbucher/console/wiki/Downloads>`_:
ConsoleZ is an alternative command prompt for Windows, adding more capabilities to the default Windows command
prompt. To compile Sight with the console the windows command prompt has to be set in the tab settings.
.. toctree::
:maxdepth: 1
.. group-tab:: Mac OSX
src/InstallationWithConan
* `QT Creator <https://download.qt.io/official_releases/qtcreator/>`_:
QT Creator is a multi-OS Integrated Development Environment (IDE) for computer programming.
You can find a setup tutorial here :ref:`qtcreatorsetup`.
Miscellaneous installations
---------------------------
.. toctree::
:maxdepth: 1
Need some help? Keep in touch!
-------------------------------
src/QtCreatorSetup
As any active community, we *sighters* are happy to help each other or beginners however we can. Feel free to join us
and share with us your questions or comments at our `Gitter <https://gitter.im/IRCAD-IHU/sight-support>`_ .
We provide support in French, English and Spanish.
Source tree layout
------------------
Good practices in Sight recommend to separate source files, build and install folders.
So to prepare the development environment, we propose to follow this layout:
* Create a development folder (Dev)
* Create a build folder (Dev/Build)
* Add a sub folder for Debug and Release.
* Create a source folder (Dev/Src)
* Create an install folder (Dev/Install)
* Add a sub folder for Debug and Release.
To prepare the third party environment:
* Create a third party folder (BinPkgs)
* Create a build folder (BinPkgs/Build)
* Add a sub folder for Debug and Release.
* Create a source folder (BinPkgs/Src)
* Create an install folder (BinPkgs/Install)
* Add a sub folder for Debug and Release.
.. image:: ../media/Directories.png
Of course you can name the folders as you wish, or choose a different layout,
but keep in mind to not build inside the source directory.
This is strongly discouraged by *CMake* authors.
Dependencies
~~~~~~~~~~~~
First, we need to build the third-party libraries.
We will now fetch the scripts that allow to build them and then launch the compilation.
* `Clone <http://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository#Cloning-an-Existing-Repository>`_ the following repository in the (BinPkgs/Src) source folder:
* `sight-deps <https://git.ircad.fr/Sight/sight-deps.git>`_
.. code:: bash
$ cd Dev/BinPkgs/Src
$ git clone https://git.ircad.fr/Sight/sight-deps.git
.. note:: *Optional*:
Additional dependency repositories must be cloned in the same directory as **sight-deps** and they will be automatically discovered and then can be enabled via CMake.
* Ensure that all the cloned repositories are on the same `branch <https://git-scm.com/docs/git-branch>`_.
* Update the cloned repositories to the lastest stable `tag <https://git-scm.com/book/en/v2/Git-Basics-Tagging>`_.
* Go into your Build directory (Debug or Release) : here is an example if you want to compile in DEBUG
.. code:: bash
$ cd Dev/BinPkgs/Build/Debug
Configuration
~~~~~~~~~~~~~
To build the dependencies, you must configure the project with CMake into the Build folder.
As any CMake based project, there are three different ways to perform that.
1. Command-line
***************
In this case, you give all the necessary variables on the command-line in one shot :
.. code:: bash
$ cd Dev/BinPkgs/Build/Debug
$ cmake ../../Src/sight-deps -DCMAKE_INSTALL_PREFIX=/home/login/Dev/BinPkgs/Install/Debug -DCMAKE_BUILD_TYPE=Debug
2. NCurses based editor
***********************
This editor allows to set the required each variable in a more interactive way :
.. code:: bash
$ cd Dev/BinPkgs/Build/Debug
$ ccmake ../../Src/sight-deps
.. image:: ../media/cmake_binpkgs.png
Then change the following CMake variables:
- ``CMAKE_INSTALL_PREFIX``: set the install location, here ``Deps/BinPkgs/Install/Debug``