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.


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().

v1.1.0

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.

v1.0.3

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).

v1.0.2

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.

v1.0.1

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.

v1.0.0

10th July 2018

First public release.