179 lines
5.2 KiB
Plaintext
179 lines
5.2 KiB
Plaintext
= Including Third Party Library
|
|
|
|
:toc:
|
|
:toc-placement!:
|
|
|
|
toc::[]
|
|
|
|
|
|
[[intro]]
|
|
Introduction
|
|
------------
|
|
|
|
Nearly all non-trivial projects will have a requirement for including third party
|
|
libraries, headers, or programs. CMake has support for finding the path to these tools using
|
|
the `find_package()` function. This will search for CMake modules in the format
|
|
"FindXXX.cmake" from the list of folders in `CMAKE_MODULE_PATH`. On linux the
|
|
default search path will include `/usr/share/cmake/Modules`. On my system this
|
|
includes support for approximately 142 common third party libraries.
|
|
|
|
|
|
The files in this tutorial are below:
|
|
|
|
```
|
|
$ tree
|
|
.
|
|
├── CMakeLists.txt
|
|
├── main.cpp
|
|
```
|
|
|
|
* CMakeLists.txt - Contains the CMake commands you wish to run
|
|
* main.cpp - The source file with main
|
|
|
|
[[requirements]]
|
|
Requirements
|
|
~~~~~~~~~~~~
|
|
|
|
This example requires the boost libraries to be installed in a default system
|
|
location.
|
|
|
|
[[concepts]]
|
|
Concepts
|
|
~~~~~~~~
|
|
|
|
[[find_package]]
|
|
Finding a Package
|
|
^^^^^^^^^^^^^^^^^
|
|
|
|
As mentioned above the `find_package()` function will search for CMake modules in the formant
|
|
"FindXXX.cmake" from the list of folders in `CMAKE_MODULE_PATH`. The exact
|
|
format of the arguments to `find_package` will depend on the module you are looking
|
|
for. This is typically documented at the top of the `FindXXX.cmake` file.
|
|
|
|
A basic example of finding boost is below:
|
|
|
|
[source,cmake]
|
|
----
|
|
find_package(Boost 1.54.0 REQUIRED COMPONENTS filesystem system)
|
|
----
|
|
|
|
The arguments are:
|
|
|
|
* Boost - Name of the library. This is part of used to find the module file FindBoost.cmake
|
|
* 1.54.0 - The minimum version of boost to find
|
|
* REQUIRED - Tells the module that this is required and to fail it it cannot be found
|
|
* COMPONENTS - The list of libraries to find.
|
|
|
|
Boost includes can take more arguments and also make use of other variables.
|
|
More complex setups are provided in later examples.
|
|
|
|
|
|
[[include-found]]
|
|
Checking if the package is found
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Most included packages will set a variable `XXX_FOUND`, which can used to check
|
|
if the package is available on the system.
|
|
|
|
In this example the variable is `Boost_FOUND`:
|
|
|
|
[source,cmake]
|
|
----
|
|
if(Boost_FOUND)
|
|
message ("boost found")
|
|
include_directories(${Boost_INCLUDE_DIRS})
|
|
else()
|
|
message (FATAL_ERROR "Cannot find Boost")
|
|
endif()
|
|
----
|
|
|
|
[[exported_variables]]
|
|
Exported Variables
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
After a package is found it will often export variables which can inform the user
|
|
where to find the library, header, or executable files. Similar to the `XXX_FOUND`
|
|
variable, these are package specific and are typically documented at the top of the
|
|
`FindXXX.cmake` file.
|
|
|
|
The variables exported in this example include:
|
|
|
|
* `Boost_INCLUDE_DIRS` - The path to the boost header files.
|
|
* `Boost_SYSTEM_LIBRARY` - The path to the boost system library.
|
|
* `Boost_FILESYSTEM_LIBRARY` - The path to the boost filesystem library.
|
|
|
|
In some cases you can also check these variables by examining the cache using
|
|
ccmake or cmake-gui.
|
|
|
|
[[building-the-example]]
|
|
Building the Example
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
[source,bash]
|
|
----
|
|
$ mkdir build
|
|
|
|
$ cd build/
|
|
|
|
$ cmake ..
|
|
-- The C compiler identification is GNU 4.8.4
|
|
-- The CXX compiler identification is GNU 4.8.4
|
|
-- Check for working C compiler: /usr/bin/cc
|
|
-- Check for working C compiler: /usr/bin/cc -- 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
|
|
-- Boost version: 1.54.0
|
|
-- Found the following Boost libraries:
|
|
-- filesystem
|
|
-- system
|
|
boost found
|
|
-- Configuring done
|
|
-- Generating done
|
|
-- Build files have been written to: /home/matrim/workspace/cmake-examples/01-basic/H-third-party-library/build
|
|
|
|
$ make
|
|
Scanning dependencies of target third_party_include
|
|
[100%] Building CXX object CMakeFiles/third_party_include.dir/main.cpp.o
|
|
Linking CXX executable third_party_include
|
|
[100%] Built target third_party_include
|
|
matrim@freyr:~/workspace/cmake-examples/01-basic/H-third-party-library/build$ ./
|
|
CMakeFiles/ third_party_include
|
|
matrim@freyr:~/workspace/cmake-examples/01-basic/H-third-party-library/build$ ./third_party_include
|
|
Hello Third Party Include!
|
|
Path is not relative
|
|
$ cmake ..
|
|
-- The C compiler identification is GNU 4.8.4
|
|
-- The CXX compiler identification is GNU 4.8.4
|
|
-- Check for working C compiler: /usr/bin/cc
|
|
-- Check for working C compiler: /usr/bin/cc -- 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
|
|
-- Boost version: 1.54.0
|
|
-- Found the following Boost libraries:
|
|
-- filesystem
|
|
-- system
|
|
boost found
|
|
-- Configuring done
|
|
-- Generating done
|
|
-- Build files have been written to: /home/matrim/workspace/cmake-examples/01-basic/H-third-party-library/build
|
|
|
|
$ make
|
|
Scanning dependencies of target third_party_include
|
|
[100%] Building CXX object CMakeFiles/third_party_include.dir/main.cpp.o
|
|
Linking CXX executable third_party_include
|
|
[100%] Built target third_party_include
|
|
|
|
$ ./third_party_include
|
|
Hello Third Party Include!
|
|
Path is not relative
|
|
|
|
----
|