Customizing the PCL build process — Point Cloud Library 0.0 documentation (original) (raw)
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:
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 withXXX_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_testsoption to ON, with a few caveats. If you’re using ccmake and you find that BUILD_global_testsis 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 andBUILD_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_DIRoptions 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.
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 |