Customizing the PCL build process

This tutorial explains how to modify the PCL cmake options and tweak your building process to better fit the needs of your project and/or your system’s requirements.

Audience

This tutorial targets users with a basic knowledge of CMake, C++ compilers, linkers, flags and make.

Prerequisites

We assume you have checked out the last available revision of PCL.

PCL basic settings

Let’s say PCL is placed under /PATH/TO/PCL, which we will refer to as PCL_ROOT:

$ cd $PCL_ROOT
$ mkdir build && cd build
$ cmake ..

This will cause cmake to create a file called CMakeCache.txt in the build directory with the default options.

Let’s have a look at what cmake options got enabled:

$ ccmake ..

You should see something like the following on screen:

BUILD_common                     ON
BUILD_features                   ON
BUILD_filters                    ON
BUILD_global_tests               OFF
BUILD_io                         ON
BUILD_kdtree                     ON
BUILD_keypoints                  ON
BUILD_octree                     ON
BUILD_range_image                ON
BUILD_registration               ON
BUILD_sample_consensus           ON
BUILD_segmentation               ON
BUILD_surface                    ON
BUILD_visualization              ON
CMAKE_BUILD_TYPE
CMAKE_INSTALL_PREFIX             /usr/local
PCL_SHARED_LIBS                  ON
PCL_VERSION                      1.0.0
VTK_DIR                          /usr/local/lib/vtk-5.6

The explanation

  • BUILD_common: option to enable/disable building of common library

  • BUILD_features: option to enable/disable building of features library

  • BUILD_filters: option to enable/disable building of filters library

  • BUILD_global_tests: option to enable/disable building of global unit tests

  • BUILD_io: option to enable/disable building of io library

  • BUILD_kdtree: option to enable/disable building of kdtree library

  • BUILD_keypoints: option to enable/disable building of keypoints library

  • BUILD_octree: option to enable/disable building of octree library

  • BUILD_range_image: option to enable/disable building of range_image library

  • BUILD_registration: option to enable/disable building of registration library

  • BUILD_sample_consensus: option to enable/disable building of sample_consensus library

  • BUILD_segmentation: option to enable/disable building of segmentation library

  • BUILD_surface: option to enable/disable building of surface library

  • BUILD_visualization: option to enable/disable building of visualization library

  • CMAKE_BUILD_TYPE: here you specify the build type. In CMake, a CMAKE_BUILD_TYPE corresponds to a set of options and flags passed to the compiler to activate/deactivate a functionality and to constrain the building process.

  • CMAKE_INSTALL_PREFIX: where the headers and the built libraries will be installed

  • PCL_SHARED_LIBS: option to enable building of shared libraries. Default is yes.

  • PCL_VERSION: this is the PCL library version. It affects the built libraries names.

  • VTK_DIR: directory of VTK library if found

The above are called cmake cached variables. At this level we only looked at the basic ones.

Tweaking basic settings

Depending on your project/system, you might want to enable/disable certain options. For example, you can prevent the building of:

  • tests: setting BUILD_global_tests to OFF

  • a library: setting BUILD_LIBRARY_NAME to OFF

Note that if you disable a XXX library that is required for building YYY then XXX will be built but won’t appear in the cache.

You can also change the build type:

  • Debug: means that no optimization is done and all the debugging symbols are embedded into the libraries file. This is platform and compiler dependent. On Linux with gcc this is equivalent to running gcc with -O0 -g -ggdb -Wall

  • Release: the compiled code is optimized and no debug information will be printed out. This will lead to -O3 for gcc and -O5 for clang

  • RelWithDebInfo: the compiled code is optimized but debugging data is also embedded in the libraries. This is a tradeoff between the two former ones.

  • MinSizeRel: this, normally, results in the smallest libraries you can build. This is interesting when building for Android or a restricted memory/space system.

A list of available CMAKE_BUILD_TYPEs can be found typing:

$ cmake --help-variable CMAKE_BUILD_TYPE

Tweaking advanced settings

Now we are done with all the basic stuff. To turn on advanced cache options hit t while in ccmake. Advanced options become especially useful when you have dependencies installed in unusual locations and thus cmake hangs with XXX_NOT_FOUND this can even prevent you from building PCL although you have all the dependencies installed. In this section we will discuss each dependency entry so that you can configure/build or update/build PCL according to your system.

Building unit tests

If you want to contribute to PCL, or are modifying the code, you need to turn on building of unit tests. This is accomplished by setting the BUILD_global_tests option to ON, with a few caveats. If you’re using ccmake and you find that BUILD_global_tests is reverting to OFF when you configure, you can move the cursor up to the BUILD_global_tests line to see the error message.

Two options which will need to be turned ON before BUILD_global_tests are BUILD_outofcore and BUILD_people. Your mileage may vary.

Also required for unit tests is the source code for the Google C++ Testing Framework. That is usually as simple as downloading the source, extracting it, and pointing the GTEST_SRC_DIR and GTEST_INCLUDE_DIR options to the applicable source locations. On Ubuntu, you can simply run apt-get install libgtest-dev.

These steps enable the tests make target, so you can use make tests to run tests.

General remarks

Under ${PCL_ROOT}/cmake/Modules there is a list of FindXXX.cmake files used to locate dependencies and set their related variables. They have a list of default searchable paths where to look for them. In addition, if pkg-config is available then it is triggered to get hints on their locations. If all of them fail, then we look for a CMake entry or environment variable named XXX_ROOT to find headers and libraries. We recommend setting an environment variable since it is independent from CMake and lasts over the changes you can make to your configuration.

The available ROOTs you can set are as follow:

  • BOOST_ROOT: for boost libraries with value C:/Program Files/boost-1.4.6 for instance

  • CMINPACK_ROOT: for cminpack with value C:/Program Files/CMINPACK 1.1.13 for instance

  • QHULL_ROOT: for qhull with value C:/Program Files/qhull 6.2.0.1373 for instance

  • FLANN_ROOT: for flann with value C:/Program Files/flann 1.6.8 for instance

To ensure that all the dependencies were correctly found, beside the message you get from CMake, you can check or edit each dependency specific variables and give it the value that best fits your needs.

UNIX users generally don’t have to bother with debug vs release versions they are fully compliant. You would just loose debug symbols if you use release libraries version instead of debug while you will end up with much more verbose output and slower execution. This said, Windows MSVC users and Apple iCode ones can build debug/release from the same project, thus it will be safer and more coherent to fill them accordingly.

Detailed description

Below, each dependency variable is listed, its meaning is explained then a sample value is given for reference.

  • Boost

cache variable

meaning

sample value

Boost_SERIALIZATION_LIBRARY

full path to boost_serialization.[so,lib,a]

/usr/local/lib/libboost_serialization.so

Boost_SERIALIZATION_LIBRARY_DEBUG

full path to boost_serialization.[so,lib,a] (debug version)

/usr/local/lib/libboost_serialization-gd.so

Boost_SERIALIZATION_LIBRARY_RELEASE

full path to boost_serialization.[so,lib,a] (release version)

/usr/local/lib/libboost_serialization.so

Boost_FILESYSTEM_LIBRARY

full path to boost_filesystem.[so,lib,a]

/usr/local/lib/libboost_filesystem.so

Boost_FILESYSTEM_LIBRARY_DEBUG

full path to boost_filesystem.[so,lib,a] (debug version)

/usr/local/lib/libboost_filesystem-gd.so

Boost_FILESYSTEM_LIBRARY_RELEASE

full path to boost_filesystem.[so,lib,a] (release version)

/usr/local/lib/libboost_filesystem.so

Boost_INCLUDE_DIR

path to boost headers directory

/usr/local/include

Boost_LIBRARY_DIRS

path to boost libraries directory

/usr/local/lib

Boost_SYSTEM_LIBRARY

full path to boost_system.[so,lib,a]

/usr/local/lib/libboost_system.so

Boost_SYSTEM_LIBRARY_DEBUG

full path to boost_system.[so,lib,a] (debug version)

/usr/local/lib/libboost_system-gd.so

Boost_SYSTEM_LIBRARY_RELEASE

full path to boost_system.[so,lib,a] (release version)

/usr/local/lib/libboost_system.so

  • CMinpack

cache variable

meaning

sample value

CMINPACK_INCLUDE_DIR

path to cminpack headers directory

/usr/local/include/cminpack-1

CMINPACK_LIBRARY

full path to cminpack.[so,lib,a] (release version)

/usr/local/lib/libcminpack.so

CMINPACK_LIBRARY_DEBUG

full path to cminpack.[so,lib,a] (debug version)

/usr/local/lib/libcminpack-gd.so

  • FLANN

cache variable

meaning

sample value

FLANN_INCLUDE_DIR

path to flann headers directory

/usr/local/include

FLANN_LIBRARY

full path to libflann_cpp.[so,lib,a] (release version)

/usr/local/lib/libflann_cpp.so

FLANN_LIBRARY_DEBUG

full path to libflann_cpp.[so,lib,a] (debug version)

/usr/local/lib/libflann_cpp-gd.so

  • Eigen

cache variable

meaning

sample value

Eigen3_DIR

path to eigen cmake directory

/usr/local/share/eigen3/cmake