1.. _using:
2
3===============================================================================
4CMake
5===============================================================================
6
7:Author: Bradley Chambers
8:Contact: brad.chambers@gmail.com
9:Date: 01/21/2015
10
11This tutorial will explain how to use PDAL in your own projects using CMake. A
12more complete, working example can be found :ref:`here <writing>`.
13
14.. note::
15
16   We assume you have either :ref:`built or installed<building>` PDAL.
17
18Basic CMake configuration
19-------------------------------------------------------------------------------
20
21Begin by creating a file named CMakeLists.txt that contains:
22
23.. code-block:: cmake
24
25  cmake_minimum_required(VERSION 2.8)
26  project(MY_PDAL_PROJECT)
27  find_package(PDAL 1.0.0 REQUIRED CONFIG)
28  include_directories(${PDAL_INCLUDE_DIRS})
29  link_directories(${PDAL_LIBRARY_DIRS})
30  add_definitions(${PDAL_DEFINITIONS})
31  set(CMAKE_CXX_FLAGS "-std=c++11")
32  add_executable(tutorial tutorial.cpp)
33  target_link_libraries(tutorial PRIVATE ${PDAL_LIBRARIES})
34
35CMakeLists explained
36-------------------------------------------------------------------------------
37
38.. code-block:: cmake
39
40  cmake_minimum_required(VERSION 2.8.12)
41
42The `cmake_minimum_required` command specifies the minimum required version of
43CMake. We use some recent additions to CMake in PDAL that require version
442.8.12.
45
46.. code-block:: cmake
47
48  project(MY_PDAL_PROJECT)
49
50The CMake `project` command names your project and sets a number of useful
51CMake variables.
52
53.. code-block:: cmake
54
55  find_package(PDAL 1.0.0 REQUIRED CONFIG)
56
57We next ask CMake to locate the PDAL package, requiring version 1.0.0 or higher.
58
59.. code-block:: cmake
60
61  include_directories(${PDAL_INCLUDE_DIRS})
62  link_directories(${PDAL_LIBRARY_DIRS})
63  add_definitions(${PDAL_DEFINITIONS})
64
65If PDAL is found, the following variables will be set:
66
67* *PDAL_FOUND*: set to 1 if PDAL is found, otherwise unset
68* *PDAL_INCLUDE_DIRS*: set to the paths to PDAL installed headers and the dependency headers
69* *PDAL_LIBRARIES*: set to the file names of the built and installed PDAL libraries
70* *PDAL_LIBRARY_DIRS*: set to the paths where PDAL libraries and 3rd party dependencies reside
71* *PDAL_VERSION*: the detected version of PDAL
72* *PDAL_DEFINITIONS*: list the needed preprocessor definitions and compiler flags
73
74.. code-block:: cmake
75
76  set(CMAKE_CXX_FLAGS "-std=c++11")
77
78We haven't quite implemented the setting of *PDAL_DEFINITIONS* within the
79`PDALConfig.cmake` file, so for now you should specify the c++11 compiler flag,
80as we use it extensively throughout PDAL.
81
82.. code-block:: cmake
83
84  add_executable(tutorial tutorial.cpp)
85
86We use the `add_executable` command to tell CMake to create an executable named
87`tutorial` from the source file `tutorial.cpp`.
88
89.. code-block:: cmake
90
91  target_link_libraries(tutorial PRIVATE ${PDAL_LIBRARIES})
92
93We assume that the tutorial executable makes calls to PDAL functions. To make
94the linker aware of the PDAL libraries, we use `target_link_libraries` to link
95`tutorial` against the *PDAL_LIBRARIES*.
96
97Compiling the project
98-------------------------------------------------------------------------------
99
100Make a `build` directory, where compilation will occur:
101
102.. code-block:: bash
103
104  $ cd /PATH/TO/MY/PDAL/PROJECT
105  $ mkdir build
106
107Run cmake from within the build directory:
108
109.. code-block:: bash
110
111  $ cd build
112  $ cmake ..
113
114Now, build the project:
115
116.. code-block:: bash
117
118  $ make
119
120The project is now built and ready to run:
121
122.. code-block:: bash
123
124  $ ./tutorial
125