Installation for MacOSX

Prerequisites

If not already installed:

  1. Install Xcode
  2. Install git
  3. 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.
  4. 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 plan to build extra dependencies, the VLC application is also needed.

$ brew cask install vlc

Source tree layout

Good practices in FW4SPL 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.
../../_images/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 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 may also clone extension repositories like fw4spl-ext-deps. Additional dependency repositories must be cloned in the same directory as fw4spl-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.
  • 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

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 :

$ cd Dev/BinPkgs/Build/Debug
$ cmake ../../Src/fw4spl-deps -DCMAKE_INSTALL_PREFIX=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 :

$ cd Dev/BinPkgs/Build/Debug
$ ccmake ../../Src/fw4spl-deps
../../_images/cmake_binpkgs.png

Then change the following CMake variables:

  • CMAKE_INSTALL_PREFIX: set the install location, here Deps/BinPkgs/Install/Debug
  • CMAKE_BUILD_TYPE: set the build type ‘Debug’ or ‘Release’
  • ENABLE_SSE_SUPPORT: enable SSE support. We need that to ensure coherency of the SSE support accross all dependencies. This option will also be forwarded to FW4SPL when building it.
  • BUILD_FW4SPL-EXT-DEPS: allows to enable/disable the fw4spl-ext-deps if you cloned it.

Press “c” to configure.

The following options are also available (some of the options will be needed for the optional source repositories):

  • ENABLE_AR: Build fw4spl-ar dependencies (OpenCV, PCL, OpenIGTLink…).
  • ENABLE_OGRE: Build Ogre3D and its dependencies (necessary for fw4spl-ogre).
  • ENABLE_CUDA: Enable CUDA support in some libraries (OpenCV, PCL, libSGM). This requires Cuda library to be installed on the system.
  • ENABLE_SOFA: Build sofa.
  • ENABLE_EXTRAS : Build dependencies that are not used currently in the open-source repositories (Odil, Bullet, realsense, libSGM,…).
  • ENABLE_EXPERIMENTAL_DEPS: Build experimental libraries (you shouldn’t use it, moreover this option is only available with fw4spl-ext-deps).

When you’re done, 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.

3. Qt based gui

$ cd ~/Dev/BinPkgs/Build/Debug
$ cmake-gui ../../Src/fw4spl-deps

You can then edit the same options than with ccmake.

Build

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

  • Clone the following repositories in the (Dev/Src) source folder:
$ cd Dev/Src
$ git clone https://github.com/fw4spl-org/fw4spl.git

Note

  • Optional: You can also clone these extension repositories:
  • Ensure that all the cloned repositories are in the same folder as fw4spl. They will be automatically discovered and then can be enabled via CMake.
  • 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

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.

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
../../_images/cmake_fw4spl.png
  • Change the following cmake arguments
    • BUILD_FW4SPL-AR: allow to enable/disable the fw4spl-ar repository if you cloned it.
    • BUILD_FW4SPL-EXT: allow to enable/disable the fw4spl-ext repository if you cloned it.
    • BUILD_FW4SPL-OGRE: allow to enable/disable the fw4spl-ogre repository if you cloned it.
    • CMAKE_INSTALL_PREFIX: set the install location, here ~/Dev/Install/Debug
    • CMAKE_BUILD_TYPE: set the build type ‘Debug’, ‘Release’, ‘RelWithDebInfo’ or ‘MinSizeRel’
    • EXTERNAL_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.

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

2. Qt based gui

$ cd Dev/Build/Debug
$ cmake-gui ../../Src/fw4spl

You can then edit the same options than with ccmake.

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