Professional CMake:

A Practical Guide

Learn to use CMake effectively with practical advice from a CMake co-maintainer. You can also have the author work directly with your team!

Professional CMake: A Practical Guide 2nd Edition

This is part of the change history for the book Professional CMake: A Practical Guide. The book was initially released with a X.Y.Z versioning scheme, but this was found to be incompatible with some book-tracking systems. The 2nd Edition is the transition from the original versioning to the more traditional edition-based numbering. For the purpose of change history, all 1.0.z releases should be considered “1st Edition”.

2nd Edition

12th December 2018

The 1.1.0 release is identical to this 2nd Edition with the exception of one trivial typo correction, described below. The 2nd Edition is the first to have an ISBN.

Build Types chapter:

  • Fixed typo in the last example at the end of section 13.3 where the PROPERTY and APPEND keywords were reversed in a call to set_property().


21st November 2018

Updated for the CMake 3.13.0 release and also contains improvements in response to reader feedback. The following lists the main changes in this update.

Simple Targets chapter:

  • The target_link_libraries() command can be called on targets defined in different directory scopes when using CMake 3.13.0 or later.

Variables chapter:

  • The --warn-uninitialized option of the cmake command is now mentioned briefly.
  • Added a new section “Potentially Surprising Behavior Of Variables”. This expands on how non-cache variables can be removed when setting cache variables and includes a discussion of the change in the behavior of the option() command in CMake 3.13.0. The effect of various ways of clearing non-cache variables is also explicitly addressed.
  • An example was modified to show how to output multi-line messages.
  • The usefulness of bracket syntax when defining regular expressions has been highlighted.
  • New options added to list(SORT) in CMake 3.13.0 are discussed.
  • The new OUTPUT_FORMAT option added to the math() command in CMake 3.13.0 is discussed.

Properties chapter:

  • Added mention of the Xcode generator’s inability to handle configuration-specific source file properties.

Generator Expressions chapter:

  • Separated out discussion of $<BOOL:...> and expanded its discussion.
  • Added a new section “Utility Expressions” containing more of the expressions that modify or substitute contents. The new $<GENEX_EVAL:...> and $<TARGET_GENEX_EVAL:...> generator expressions added in CMake 3.13.0 are also discussed.

Build Types chapter:

  • Updated examples to query the GENERATOR_IS_MULTI_CONFIG property to check if the current generator is multi-configuration or not.

Compiler And Linker Essentials chapter:
Fairly substantial updates to account for new features added in CMake 3.13.0 relating to linker flag handling:

  • Added discussion of the new LINK_OPTIONS, INTERFACE_LINK_OPTIONS and STATIC_LIBRARY_OPTIONS target properties and the new LINK_OPTIONS directory property.
  • Added explanation of the new target_link_options() and add_link_options() commands and how they affect various properties.
  • Added explanation of the new LINKER: prefix which can be used to handle differences in the way compiler front-ends pass through linker options.
  • Expanded discussion of the link_directories() command to cover the new BEFORE and AFTER options and the change in behavior of how relative paths are handled.
  • The new target_link_directories() command is mentioned briefly, but its use is discouraged.
  • Updated the “Recommended Practices” section to account for the change where the target_link_libraries() command can now be called on targets defined in different directory scopes.

The following other changes were also made to this chapter:

  • The interaction between $<BUILD_INTERFACE:...> and conversion of relative paths to absolute in calls to target_include_directories() is now explained.
  • A new section “Language-specific Compiler Flags” was added to explain different ways of handling this particular area, including limitations and trade-offs.

Toolchains And Cross Compiling chapter:

  • Updated Android section for changes associated with NDK r18 and upcoming releases (mostly affecting toolchain and STL selection).
  • Added mention of LLVM STL choices when using Nvidia Nsight Tegra Visual Studio Edition.

Apple chapter:

  • Added note that xcodebuild supports the -allowProvisioningUpdates option with Xcode 9 or later.

Finding Things chapter:

  • Added mention of GLOBAL keyword added in CMake 3.13.0 when creating imported targets with the FindPkgConfig module’s functions.
  • Updated the list of supported operators for module specs used with the FindPkgConfig module. CMake 3.13.0 expanded the set of supported operators.
  • Clarified when CMAKE_MODULE_PATH is used (“Recommended Practices” section).

Testing chapter:

  • Clarified and expanded the advice in the “Recommended Practices” section around integrating a project’s tests into a larger project hierarchy.

Installing chapter:

  • Updated to mention that CMake 3.13.0 removed the constraint that previously prohibited install(TARGETS) from being called on targets that were defined in a different directory scope.

Packaging chapter:

  • Added section for new CPack External generator type added in CMake 3.13.0.
  • Added a note that the DEB generator now supports creating debuginfo packages as of CMake 3.13.0.
  • Minor wording changes to account for CPack documentation being restructured with CMake 3.13.0.

Project Organization chapter:

  • Updated the “Target Sources” section to fix inconsistent advice from the text and one of the examples. Also updated the discussion to account for the change in behavior of the target_sources() command in CMake 3.13.0 for relative paths and also the relaxation of the constraint for target_link_libraries() already mentioned above.
  • Lifted the “Windows-specific Issues” sub-section up one level and expanded it to cover the new VS_DEBUGGER_... target properties added in CMake 3.12 and 3.13.
  • Updated “Miscellaneous Project Features” section to mention that the clean target of Makefile generators also remove byproducts as of CMake 3.13.0.