The document provides an extensive overview of CMake and its functionalities related to handling libraries in C++. It covers key topics like library types, find_package, pkg-config, and custom find modules, detailing how to manage dependencies and link libraries in various contexts. Additionally, it emphasizes the importance of understanding target properties and build configurations for effective CMake usage.

1. Richard Thomson
Senior Software Engineer, NVIDIA
@LegalizeAdulthd
http://LegalizeAdulthood.wordpress.com
legalize@xmission.com

2. Outline
 Review of C++ Libraries
 find_package
 pkg-config
 Custom Find Module

3. C++ Library Review
 Source files include library headers
 Executable linked against libraries

4. Library Header Complications
 May include headers from other libraries
 May require specific preprocessor
definitions
 May have different names on different
platforms
 May have different names based on build
configuration

5. Library Link Complications
 May depend on other libraries
 May require specific runtime constraints, e.g.
Windows C/C++ runtime library variants
 May have different names on different platforms
 May have different names based on build
configuration
 Library location may depend on build configuration

6. CMake Requirements
 Build Requirements
 What is needed to build this target?
 Usage Requirements
 What is needed to use a target?
 Requirement examples:
○ Compilation flags
○ Preprocessor definitions
○ Include directories
○ Link directories
○ Link dependencies
 Requirements are propagated transitively by
CMake between targets

7. CMake Target Requirements
 PRIVATE
 Build requirements for the target
 Imposes no usage requirement
 INTERFACE
 Usage requirements for the target
 Imposes no build requirements
 PUBLIC
 Combination of PRIVATE and INTERFACE
 Imposes build and usage requirements

8. CMake Properties
 A property is a name/value pair
 CMake properties:
 Global properties
 Project properties
 Directory properties
 Target properties
 Source file properties
 Build requirements are properties
 Usage requirements are properties

9. CMake Modules
 A module is just a text file containing CMake
commands
 Typically a module defines functions and macros
 Usually named XXX.cmake
 include(XXX) loads the module XXX.cmake
 CMake has a module search path used to locate
module files

10. Imported Targets
 Imported targets supply usage
requirements
 A find module may create imported targets
for the found library
 Usage requirements are associated with the
imported target via target properties
 Prefer imported targets for found libraries

11. Library Flavors
 Header Only Library
 Static Library
 Dynamic Library
 Plug-In Library

12. Header Only Library
 Implementation exists only as headers
 Library dependencies are linked into the
executable
 Executable and library must use compatible
compilation flags
 Unused code may be detected by the linker

13. Header Only Library by Hand
cmake_minimum_required(VERSION 3.16)
project(hello VERSION 1.0 LANGUAGES CXX)
add_executable(hello hello.cpp)
target_compile_options(hello PRIVATE –Wall)
target_compile_definitions(hello PRIVATE HAVE_IOSTREAMS)
target_include_directories(hello PRIVATE greet/include)

14. Static Library
 Binds object code into the executable
 Library dependencies are linked into the
executable
 Executable and library must use compatible
compilation flags
 Unused code may be detected by the linker

15. Static Library by Hand
cmake_minimum_required(VERSION 3.16)
project(hello VERSION 1.0 LANGUAGES CXX)
add_executable(hello hello.cpp)
target_compile_options(hello PRIVATE –Wall)
target_compile_definitions(hello PRIVATE HAVE_IOSTREAMS)
target_include_directories(hello PRIVATE greet/include)
target_link_libraries(hello PRIVATE greet/lib/libgreet.a)

16. Dynamic Library
 Binds references into the executable
 Must be deployed with the executable
 Library may be versioned
 Executable and library must use compatible
compilation flags

17. Dynamic Library by Hand
cmake_minimum_required(VERSION 3.16)
project(hello VERSION 1.0 LANGUAGES CXX)
add_executable(hello hello.cpp)
target_compile_options(hello PRIVATE –Wall)
target_compile_definitions(hello PRIVATE HAVE_IOSTREAMS)
target_include_directories(hello PRIVATE greet/include)
target_link_libraries(hello
PRIVATE greet/lib/libgreet.so)

18. Plug-In Library
 Dynamic library that is accessed at runtime
 Executable does not directly bind to the
library
 Executable queries plug-in for function entry
points
 Executable and library must use compatible
compilation flags

19. Plug-In Library by Hand
cmake_minimum_required(VERSION 3.16)
project(hello VERSION 1.0 LANGUAGES CXX)
add_executable(hello hello.cpp)
target_compile_options(hello PRIVATE –Wall)
target_compile_definitions(hello PRIVATE HAVE_IOSTREAMS)
target_include_directories(hello PRIVATE greet/include)

20. Library by Hand Shortcomings
 Consuming executable littered with library
implementation details
 Compilation options are compiler specific
 Location of headers is assumed
 Location of library is assumed
 Doesn’t select debug or release library
 Name of library is assumed

21. find_package
find_package(<PackageName> [version]
[EXACT] [QUIET] [MODULE] [REQUIRED]
[[COMPONENTS] [components...]]
[OPTIONAL_COMPONENTS components...]
[NO_POLICY_SCOPE])
 Finds and loads settings from an external
project
 Sets <PackageName>_FOUND if found
 Sucess results in variables and imported
targets describing the found package
 Unifies header only, static and dynamic
libraries

22. Find Modules
 find_package looks for a Find Module for
the requested package
 The CMake module search path is used to
located the Find Module
 A Find Module is named FindXXX.cmake
 CMake ships with many find modules

23. find_package Example
cmake_minimum_required(VERSION 3.16)
project(hello VERSION 1.0 LANGUAGES CXX)
add_executable(hello hello.cpp)
find_package(Greeting 1.0 REQUIRED)
target_link_libraries(hello PRIVATE Greeting::greet)

24. pkg-config
 pkg-config originated in Unix, but is
available for Unix, macOS and Windows
 pkg-config describes usage requirements
for installed libraries
 CMake’s FindPkgConfig module can create
imported targets for pkg-config libraries

25. pkg-config Example
cmake_minimum_required(VERSION 3.16)
project(hello VERSION 1.0 LANGUAGES CXX)
find_package(PkgConfig REQUIRED)
add_executable(hello hello.cpp)
pkg_check_modules(Greeting REQUIRED IMPORTED_TARGET
greet=1.0)
target_link_libraries(hello PRIVATE PkgConfig::Greeting)

26. Custom Find Module
 Write your own find module when CMake
has no find module for the library
 Determines usage requirements:
 Compile options
 Compile definitions
 Include directories
 Link options
 Link directories
 Library filename
 Create imported target(s) for the library

27. Find Module Outline
1. Input data is described by find_package
2. Locate header files
3. Locate library files
4. Locate dependencies
5. Call find_package_handle_standard_args
to communicate results to find_package
6. If everything found:
1. Create imported target
2. Set target properties

28. Finding Things
 find_file
 find_program
 find_path
 find_library
 find_package

29. find_file
find_file(<var>
name | NAMES name1 [name2...]
[HINTS path1 [path2...ENV var]]
[PATHS path1 [path2...ENV var]]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[DOC "cache documentation string"]
[NO_DEFAULT_PATH])
 Locates a file according to name, location, suffix
 Stores the result in <var>
 Consult documentation for more options and
details on search behavior

30. find_program
find_program(<var>
name | NAMES name1 [name2...]
[HINTS path1 [path2...ENV var]]
[PATHS path1 [path2...ENV var]]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[DOC "cache documentation string"]
[NO_DEFAULT_PATH])
 Similar to find_file
 Locates an executable program
 Handles platform specific conventions, e.g.
foo.exe on Windows

31. find_path
find_path(<var>
name | NAMES name1 [name2...]
[HINTS path1 [path2...ENV var]]
[PATHS path1 [path2...ENV var]]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[DOC "cache documentation string"]
[NO_DEFAULT_PATH])
 Similar to find_file
 Locates a directory containing a file

32. find_library
find_library(<var>
name | NAMES name1 [name2...]
[HINTS path1 [path2...ENV var]]
[PATHS path1 [path2...ENV var]]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[DOC "cache documentation string"]
[NO_DEFAULT_PATH])
 Similar to find_file
 Handles platform specific library forms, e.g.
libfoo.a, foo.dll, foo.lib

33.  Use find_package to locate your
dependencies
find_package

34. find_package_handle_standard_ar
gs
find_package_handle_standard_args(<PackageName>
[FOUND_VAR <result-var>]
[REQUIRED_VARS <required-var>...]
[VERSION_VAR <version-var>]
[HANDLE_COMPONENTS]
[CONFIG_MODE]
[REASON_FAILURE_MESSAGE <message>]
[FAIL_MESSAGE <message>]
)
 find_package(PackageHandleStandardArgs)
 Use REQUIRED_VARS to list requirements:
found files, directories, libraries, etc.
 Combined result is in <result-var>

35. Creating Imported Targets
add_library(<name>
<SHARED|STATIC|MODULE|OBJECT|INTERFACE|UNKNOWN>
IMPORTED [GLOBAL])
 Typically specify the library type as
UNKNOWN
 Set target properties to specify usage
requirements

36.  IMPORTED_CONFIGURATIONS
 IMPORTED_IMPLIB
 IMPORTED_IMPLIB_<CONFIG>
 IMPORTED_LINK_DEPENDENT_LIBRARIES
 IMPORTED_LINK_DEPENDENT_LIBRARIES_<CONFIG>
 IMPORTED_LINK_INTERFACE_LANGUAGES
 IMPORTED_LINK_INTERFACE_LANGUAGES_<CONFIG>
 IMPORTED_LINK_INTERFACE_LIBRARIES
 IMPORTED_LINK_INTERFACE_LIBRARIES_<CONFIG>
 IMPORTED_LOCATION
 IMPORTED_LOCATION_<CONFIG>
 INTERFACE_COMPILE_DEFINITIONS
 INTERFACE_COMPILE_FEATURES
 INTERFACE_COMPILE_OPTIONS
 INTERFACE_INCLUDE_DIRECTORIES
 INTERFACE_LINK_DIRECTORIES
 INTERFACE_LINK_LIBRARIES
 INTERFACE_LINK_OPTIONS
Relevant Target Properties

37.  Prefer target_XXX commands over setting
the properties directly
 set_target_properties will replace target
property settings with new values (it does
not append)
 set_property(TARGET) can be used to
append values to properties
Setting Target Properties

38.  Header only library
 Look for catch.hpp
 Create imported target Catch2::Catch
Example: Catch2 Unit Testing
Library

39. find_package(PkgConfig)
pkg_check_modules(PC_Catch2 QUIET catch)
find_path(Catch2_INCLUDE_DIR
NAMES catch.hpp
PATHS ${PC_Catch2_INCLUDE_DIRS})
find_package(PackageHandleStandardArgs REQUIRED)
find_package_handle_standard_args(Catch2
FOUND_VAR Catch2_FOUND
REQUIRED_VARS Catch2_INCLUDE_DIR)
if(Catch2_FOUND AND NOT TARGET Catch2::Catch)
add_library(Catch2::Catch INTERFACE IMPORTED)
set_target_properties(Catch2::Catch PROPERTIES
INTERFACE_INCLUDE_DIRECTORIES
${Catch2_INCLUDE_DIR})
endif()
Example: Catch2 Unit Testing
Library

40. rd /s/q build
mkdir build
pushd build
cmake -G "Visual Studio 15 2017" ^
-DCMAKE_INCLUDE_PATH:PATH=C:/code/catch2/include ^
../source
popd
Example: Building with Catch2