Installation for MacOSX¶
Prerequisites for MacOSX users¶
If not already installed:
- Install Xcode
- Install git
- Install CMake. The minimal version required is 3.7 if you want to compile with precompiled headers (build twice faster, enabled by default). Otherwise you can use a 3.1 version.
- Install Ninja : to use instead of make.
For an easy install, you can use the Hombrew project to install missing packages.
$ brew install git
$ brew install cmake
$ brew install ninja
For Openni dependency, you need libusb
$ brew install libusb-compat
If you are building the dependencies with the fw4spl-ext-deps additional dependencies, the VLC application is also needed.
$ brew cask install vlc
FW4SPL installation¶
Good practices in FW4SPL 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.
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.
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 librairies. We will now fetch the scripts that allow to build them and then launch the compilation.
Clone the following repository in the (BinPkgs/Src) source folder:
$ cd Dev/BinPkgs/Src
$ git clone https://github.com/fw4spl-org/fw4spl-deps.git
Note
Optional: You can also clone this extension repository: fw4spl-ext-deps
You’ll need it if you want to add extension to fw4spl (like fw4spl-ar).
- Ensure that all the cloned repositories are on the same branch.
- Update the cloned repositories to the lastest stable tag.
- Go into your Build directory (Debug or Release) : here is an example if you want to compile in DEBUG
$ cd Dev/BinPkgs/Build/Debug
Dependencies 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.
Note
All the generation options are specified in ‘Dependencies generation’
1. Command-line¶
In this case, you give all the necessary variables on the command-line in one shot :
$ cd Dev/BinPkgs/Build/Debug
$ cmake ../../Src/fw4spl-deps -DCMAKE_INSTALL_PREFIX=Dev/BinPkgs/Install/Debug -DCMAKE_BUILD_TYPE=Debug
Or, if you cloned the fw4spl-ext-deps :
$ cd Dev/BinPkgs/Build/Debug
$ cmake ../../Src/fw4spl-deps -DCMAKE_INSTALL_PREFIX=Dev/BinPkgs/Install/Debug -DCMAKE_BUILD_TYPE=Debug -DADDITIONAL_DEPS=Dev/Src/fw4spl-ext-deps
2. NCurses based editor¶
This editor allows to set the required each variable in a more interactive way :
$ cd Dev/BinPkgs/Build/Debug
$ ccmake ../../Src/fw4spl-deps
Then change the following CMake variables:
CMAKE_INSTALL_PREFIX
: set the install location, hereDeps/BinPkgs/Install/Debug
CMAKE_BUILD_TYPE
: set the build type ‘Debug’ or ‘Release’ADDITIONAL_DEPS
: you can leave it empty, it is only needed if you have an extra source location like fw4spl-ext-deps or a custom repository.
Press “c” to configure.
3. Qt based gui¶
$ cd ~/Dev/BinPkgs/Build/Debug
$ cmake-gui ../../Src/fw4spl-deps
Like ccmake, change the following CMake variables:
CMAKE_INSTALL_PREFIX
: set the install location, here~/Deps/Install/Debug
CMAKE_BUILD_TYPE
: set the build type ‘Debug’ or ‘Release’ADDITIONAL_DEPS
: you can leave it empty, it is only needed if you have an extra source location like fw4spl-ext-deps or a custom repository.
Click on “configure”.
Dependencies generation¶
Warning
ENABLE_PCL
, ENABLE_LIBSGM
and ENABLE_OPENCV_CUDA
require the Cuda library, if you intend to use one of these, you should install it before.
Set the following options (some of the options will be needed for the optional source):
ENABLE_EXPERIMENTAL_DEPS
: set to ON to build experimentals libraries (You shouldn’t use it).ENABLE_INFINITAM
: set to ON to build infinitam.ENABLE_LIBSGM
: set to ON to build libSGM dependencies.ENABLE_ODIL
: set to ON to build Odil dependencies.ENABLE_OGRE
: set to ON to build ogre.ENABLE_OPENCV_CONTRIB
: set to ON to build OpenCV contrib extra modules.ENABLE_OPENCV_CUDA
: set to ON to build OpenCV with CUDA support.ENABLE_OPEN_MP
: set to ON to enable OpenMP.ENABLE_BUILD_ORB_SLAM2
: set to ON to build ORB Slam 2.ENABLE_PCL
: set to ON to build PCL.ENABLE_PCL_CUDA
: set to ON to build PCL with CUDA support.ENABLE_REALSENSE
: set to ON to build librealsense.ENABLE_SOFA
: set to ON to build sofa.
Generate the code by pressing “g” on NCurses based editor or click on “generate” on gui.
Warning
Do not compile debug and release with the same Build and Install folders. If you followed the recommended folder layout, this should be fine.
Compilation¶
Now you can compile the FW4SPL dependencies with make in the console, it will automaticaly download, build and install each dependency.
$ make install
$ make install_tool
Warning
Do NOT use ninja to compile the dependencies, it causes conflict with qt compilation.
If you get compilation errors at this step, please ensure you installed all the requirements, especially those for Qt.
Source¶
$ cd Dev/Src
$ git clone https://github.com/fw4spl-org/fw4spl.git
Note
- Optional: You can also clone these extension repositories:
- fw4spl-ar contains functionalities for augmented reality (video tracking for instance).
- fw4spl-ext contains experimental code.
- fw4spl-ogre contains a 3D backend using Ogre3D.
- Ensure that all the cloned repositories are on the same branch.
- Update the cloned repositories to the same tag.
- Go into your Build directory (Debug or Release) : here is an example if you want to compile in debug:
$ cd Dev/Build/Debug
- Open the cmake-gui.
Now you have to configure the project. You can use one of the three tools explained above.
Also, for FW4SPL, we recommend to use the Ninja generator. It builds faster, and is much better for everyday use because of how fast it is at figuring out which files need to be built. In other words, with Ninja the compilation starts instantly whereas Make spends a dozen of seconds to check what should be compiled before actually compiling something. So if you plan to develop with FW4SPL, go with Ninja. If you only want to give a single try, you can live with the standard “Unix Makefiles” generator.
Source configuration¶
1. NCurses based editor¶
To use make, here with ccmake
:
$ cd Dev/Build/Debug
$ ccmake ../../Src/fw4spl
To use ninja :
$ cd Dev/Build/Debug
$ ccmake -G Ninja ../../Src/fw4spl
- Change the following cmake arguments
CMAKE_INSTALL_PREFIX
: set the install location (~/Dev/Install/Debug or Release)CMAKE_BUILD_TYPE
: set to Debug or ReleaseEXTERNAL_LIBRARIES
: set the install path of the third party libraries you compiled earlier.(ex : ~/Dev/Install/Debug)PROJECTS_TO_BUILD
: set the list of the projects you want to build (ex: VRRender, Tuto01Basic …), each project should be separated by “;”PROJECTS_TO_INSTALL
: set the name of the application to install
- Press “c” to configure and then “g” to generate the makefiles.
2. Qt based gui¶
$ cd Dev/Build/Debug
$ cmake-gui ../../Src/fw4spl-deps
- Change the following CMake variables:
CMAKE_INSTALL_PREFIX
: set the install location, here~/Dev/Install/Debug
CMAKE_BUILD_TYPE
: set the build type ‘Debug’ or ‘Release’ADDITIONAL_DEPS
: you can leave it empty, it is only needed if you have an extra source location like fw4spl-ext-deps or a custom repository.
- Click on “configure”.
- Change the following cmake arguments
CMAKE_INSTALL_PREFIX
: set the install location (~/Dev/Install/Debug or Release)CMAKE_BUILD_TYPE
: set to Debug or ReleaseEXTERNAL_LIBRARIES
: set the install path of the third party libraries you compiled earlier.(ex : ~/Deps/Install/Debug)PROJECTS_TO_BUILD
: set the list of the projects you want to build (ex: VRRender, Tuto01Basic …), each project should be separated by “;”PROJECTS_TO_INSTALL
: set the name of the application to install
Note
- If
PROJECTS_TO_BUILD
is empty, all application will be compiled - If
PROJECTS_TO_INSTALL
is empty, no application will be installed
Click on “generate”.
Note
To generate the projects in release mode, change CMake argument CMAKE_BUILD_TYPE
to Release
both for fw4spl and fw4spl-deps
Source Build¶
Then, according to the generator you chose, build FW4SPL with make :
$ cd Dev/Build/Debug
# Adjust the number of cores depending of the CPU cores and the RAM available on your computer
$ make -j4
Or with ninja:
$ cd Dev/Build/Debug
$ ninja
If you didn’t specify anything in PROJECTS_TO_BUILD
you may also build specific targets, for instance:
$ ninja Tuto01Basic VRRender
Launch an application¶
After a successful compilation the application can be launched with the fwlauncher program from FW4SPL. The profile.xml of the application in the build folder has to be passed as argument to the fwlauncher call in the console.
> cd Dev/Build/Debug
> ./bin/fwlauncher share/MyApplication/profile.xml
Example:
$ cd /Dev/Build/Debug
$ ./bin/fwlauncher share/VRRender_0-9/profile.xml
Recommended software¶
The following programs may be helpful for your developments:
- IDE:
- Versioning tools: