.. _using_pcl_pcl_config:

Using PCL in your own project

This tutorial explains how to use PCL in your own projects.

Prerequisites

We assume you have downloaded, compiled and installed PCL on your machine.

Project settings

Let us say the project is placed under /PATH/TO/MY/GRAND/PROJECT that contains a lonely cpp file name pcd_write.cpp (copy it from the :ref:writing_pcd tutorial). In the same folder, create a file named CMakeLists.txt that contains:

.. code-block:: cmake

cmake_minimum_required(VERSION 3.10 FATAL_ERROR) project(MY_GRAND_PROJECT) find_package(PCL 1.3 REQUIRED) add_executable(pcd_write_test pcd_write.cpp) target_link_libraries(pcd_write_test ${PCL_LIBRARIES})

The explanation

Now, let's see what we did.

.. code-block:: cmake

cmake_minimum_required(VERSION 3.10 FATAL_ERROR)

This is mandatory for cmake, and since we are making a very basic project we don't need features from cmake 2.8 or higher.

.. code-block:: cmake

project(MY_GRAND_PROJECT)

This line names your project and sets some useful cmake variables such as those to refer to the source directory (MY_GRAND_PROJECT_SOURCE_DIR) and the directory from which you are invoking cmake (MY_GRAND_PROJECT_BINARY_DIR).

.. code-block:: cmake

find_package(PCL 1.3 REQUIRED)

We are requesting to find the PCL package at minimum version 1.3. We also say that it is REQUIRED meaning that cmake will fail gracefully if it can't be found. As PCL is modular one can request:

only one component: find_package(PCL 1.3 REQUIRED COMPONENTS io)
several: find_package(PCL 1.3 REQUIRED COMPONENTS io common)
all existing: find_package(PCL 1.3 REQUIRED)

.. code-block:: cmake

add_executable(pcd_write_test pcd_write.cpp)

Here, we tell cmake that we are trying to make an executable file named pcd_write_test from one single source file pcd_write.cpp. CMake will take care of the suffix (.exe on Windows platform and blank on UNIX) and the permissions.

.. code-block:: cmake

target_link_libraries(pcd_write_test ${PCL_LIBRARIES})

The executable we are building makes calls to PCL functions. So far, we have only included the PCL headers so the compiler knows about the methods we are calling. We need also to make the linker know about the libraries we are linking against. As said before, the PCL found libraries are referred to using PCL_LIBRARIES variable, all that remains is to trigger the link operation which we do calling target_link_libraries() macro. PCLConfig.cmake uses a CMake special feature named EXPORT which allows for using others' projects targets as if you built them yourself. When you are using such targets they are called imported targets and act just like any other target.

CMake variables defined after finding PCL

When PCL is found, several related variables are set:

PCL_FOUND: set to 1 if PCL is found, otherwise unset
PCL_INCLUDE_DIRS: set to the paths to PCL installed headers and the dependency headers
PCL_LIBRARIES: set to the file names of the built and installed PCL libraries
PCL_LIBRARY_DIRS: set to the paths to where PCL libraries and 3rd party dependencies reside
PCL_VERSION: the version of the found PCL
PCL_COMPONENTS: lists all available components
PCL_DEFINITIONS: lists the needed preprocessor definitions and compiler flags

In older PCL versions, it was necessary to explicitly tell CMake about PCL_INCLUDE_DIRS, PCL_LIBRARY_DIRS, and PCL_DEFINITIONS, but in newer PCL versions, the target_link_libraries call handles that automatically.

Compiling and running the project

Using command line CMake

Make a directory called build, in which the compilation will be done. Do::

$ cd /PATH/TO/MY/GRAND/PROJECT $ mkdir build $ cd build $ cmake ..

You will see something similar to::

-- The C compiler identification is GNU -- The CXX compiler identification is GNU -- Check for working C compiler: /usr/bin/gcc -- Check for working C compiler: /usr/bin/gcc -- works -- Detecting C compiler ABI info -- Detecting C compiler ABI info - done -- Check for working CXX compiler: /usr/bin/c++ -- Check for working CXX compiler: /usr/bin/c++ -- works -- Detecting CXX compiler ABI info -- Detecting CXX compiler ABI info - done -- Found PCL_IO: /usr/local/lib/libpcl_io.so -- Found PCL: /usr/local/lib/libpcl_io.so (Required is at least version "1.0") -- Configuring done -- Generating done -- Build files have been written to: /PATH/TO/MY/GRAND/PROJECT/build

If you want to see what is written on the CMake cache::

CMAKE_BUILD_TYPE CMAKE_INSTALL_PREFIX /usr/local PCL_DIR /usr/local/share/pcl

Now, we can build up our project, simply typing::

$ make

The result should be as follow::

Scanning dependencies of target pcd_write_test [100%] Building CXX object CMakeFiles/pcd_write_test.dir/pcd_write.cpp.o Linking CXX executable pcd_write_test [100%] Built target pcd_write_test

The project is now compiled, linked and ready to test::

$ ./pcd_write_test

Which leads to this::

Saved 5 data points to test_pcd.pcd. 0.352222 -0.151883 -0.106395 -0.397406 -0.473106 0.292602 -0.731898 0.667105 0.441304 -0.734766 0.854581 -0.0361733 -0.4607 -0.277468 -0.916762

Using CMake gui (e.g. Windows)

Run CMake GUI, and fill these fields :

Where is the source code : this is the folder containing the CMakeLists.txt file and the sources.
Where to build the binaries : this is where the Visual Studio project files will be generated

Then, click Configure. You will be prompted for a generator/compiler. Then click the Generate button. If there are no errors, the project files will be generated into the Where to build the binaries folder.

Open the sln file, and build your project!

Weird installations

CMake has a list of default searchable paths where it seeks for FindXXX.cmake or XXXConfig.cmake. If you happen to install in some non-obvious repository (let us say in Documents for evils) then you can help cmake find PCLConfig.cmake adding this line:

.. code-block:: cmake

set(PCL_DIR "/path/to/PCLConfig.cmake")

before this one:

.. code-block:: cmake

find_package(PCL 1.3 REQUIRED)