Professional CMake:

A Practical Guide

Go beyond trivial examples and learn how to use CMake effectively with practical advice direct from a CMake co-maintainer


Release Notes

This is the change history for the book Professional CMake: A Practical Guide.

3rd Edition

15th March 2019

Updated for the CMake 3.14.0 release and also contains some other minor improvements. The following lists the main changes in this update.

Flow Control chapter:

  • New for CMake 3.14, the if() command can now check specifically whether a variable is a cache variable using if(CACHE{name}).

Modules chapter:

  • New for CMake 3.14, the try_compile() command now supports link options through the new CMAKE_REQUIRED_LINK_OPTIONS variable.
  • The new CheckFortranSourceRuns module added in CMake 3.14 is now mentioned and has been added to the existing examples for C and C++.

Target Types chapter:

  • Added comments about fixes in CMake 3.14 for transitive behavior of object libraries.
  • Added brief comment that the name of an exported target can be different to the original.

Working With Files chapter:

  • New NAME_WLE and LAST_EXT options added in CMake 3.14 for get_filename_component().
  • New file() subcommands READ_SYMLINK, CREATE_LINK and SIZE added in CMake 3.14.

Toolchains And Cross Compiling chapter:

  • Added comment regarding new support in CMake 3.14 for iOS, watchOS and tvOS as CMAKE_SYSTEM_NAME values.
  • Fixed an example where a generator expression was split across multiple lines.
  • Added notes highlighting that Android NDK r19 breaks CMake’s built-in Android support.

Apple chapter:

  • New for CMake 3.14, the target Apple platform can now be selected by setting CMAKE_SYSTEM_NAME to  iOS, watchOS and tvOS.
  • Corrected and expanded statements about how CMAKE_XCODE_ATTRIBUTE_XXX variables and XCODE_ATTRIBUTE_XXX target properties relate to each other and where the variable will and won’t have any effect.
  • Cleaned up discussion of provisioning and added material covering manual provisioning with the XCODE_ATTRIBUTE_PROVISIONING_PROFILE_SPECIFIER target property.
  • With CMake 3.14, code signing is no longer needed or used in try_compile() tests. Combined with the new CMAKE_SYSTEM_NAME support, toolchain files are no longer needed for iOS, watchOS or tvOS.
  • Clarified some comments in the Recommendations section around the use of the CMAKE_XCODE_ATTRIBUTE_ONLY_ACTIVE_ARCH and CMAKE_OSX_ARCHITECTURES variables.

Finding Things chapter:

  • Clarified the interaction of QUIET and REQUIRED options to find_package().

Testing chapter:

  • Added a brief mention of the ctest --progress option added in CMake 3.13.
  • New for CMake 3.14, the CTest module now supports a CTEST_SUBMIT_URL variable for more convenient dashboard URL definition.
  • New for CMake 3.14, dashboard submissions now support a new Done part.

Installing chapter:

  • New for CMake 3.14, A number of install() commands now support a default destination based on GNUInstallDirs.
  • CMake 3.14 added a new BUILD_RPATH_USE_ORIGIN target property and an associated CMAKE_BUILD_RPATH_USE_ORIGIN variable.
  • Added discussion of the EXPORT_NAME target property to allow the exported target name to be different from the original target.
  • The order in which install() commands are used during an install has been made much clearer with CMake 3.14. Changes in behavior are noted with an example to illustrate.
  • CMake 3.14 added support for generator expressions within custom code or a custom script file name given to install().
  • A new ARCH_INDEPENDENT option was added to write_basic_package_version_file() in CMake 3.14.

External Content chapter:

  • CMake 3.14 added a new FetchContent_MakeAvailable() command for bringing in dependencies much more concisely.
  • CMake 3.14 added new LOG_DIR and LOG_MERGED_STDOUTERR options to ExternalProject_Add().
  • Added a brief note mentioning a drawback to the BUILD_ALWAYS option of ExternalProject_Add().

Project Organization chapter:

  • Updated discussion and examples to account for the new FetchContent_MakeAvailable() command added in CMake 3.14.
  • Updated examples to show how to use the EXPORT_NAME target property.

2nd Edition

12th December 2018

Previous releases used version numbers of the form x.y.z, but in order to conform to the needs of systems expecting a more conventional ISBN-related arrangement, releases are now made as new editions (i.e. a single numerical edition number). For the purpose of change history, all 1.0.z releases should be considered “1st Edition”. The 1.1.0 release is identical to this 2nd Edition with the exception of one trivial typo correction, described below.

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.


12th August 2018

This release contains fixes for a number of trivial typos, grammar and formatting improvements. Two diagrams were also corrected as mentioned below.

Apple chapter:

  • The macOS framework directory structure example diagrams incorrectly showed the Resources, Headers and PrivateHeaders subdirectories parented under Versions instead of Versions/A. The text correctly described the locations of these subdirectories, but the diagrams have been updated in this release to reflect their correct locations (two diagrams, both in section 22.3).


29th July 2018

This release contains a small number of minor typo/readability changes and corrects an erroneous statement about policy and function interaction.

Using Subdirectories chapter:

  • Fix typo in example output: /somewhere/.../foo –> /somewhere/.../subdir

Functions And Macros chapter:

  • Fix incorrect statement that functions introduce a new policy scope.

Policies chapter:

  • Add a paragraph to clarify and advise how to control policy settings for functions.
  • Remove stray CMAKE_POLICY_WARNING_CMP<NNNN> text introduced during indexing.

Libraries chapter:

  • Minor grammatical fix in Recommended Practices section.


15th July 2018

This release contains a small number of minor changes only.

Build Type chapter:

  • Fix typo: MinRizeRel –> MinSizeRel

Language Requirements chapter:

  • Minor readability improvement of Recommended Practices section.
  • Mention that language requirements are preserved when targets are exported and installed.


10th July 2018

First public release.