Contact

Release Notes

This is the change history for the book Professional CMake: A Practical Guide. The table below summarizes the set of published editions and their release date. Click through for a detailed list of changes for each release.

22nd Edition – 21st January 2026

The 22nd Edition has been updated for the CMake 4.1 and CMake 4.2 releases, mostly with minor updates and incremental additions. A new AppImage CPack generator is the main new feature.

Setting Up A Project chapter:

  • Added the new Visual Studio 18 2026 generator to the table of commonly used generators. This generator was added in CMake 4.2.

Variables chapter:

  • Added the new set(CACHE{varName}) and unset(CACHE{varName}) command forms, new in CMake 4.2.

Generator Expressions chapter:

  • Briefly mention the new POSTFIX keyword now supported by some target-dependent generator expressions as of CMake 4.2.

Policies chapter:

  • Updated the advice in the Recommended Practices section to prefer using cmake_policy(VERSION) over cmake_minimum_required(VERSION) in Find modules to avoid leaking changes to the CMAKE_MINIMUM_REQUIRED_VERSION variable.

Build Type chapter:

  • Fixed two examples that were missing the VERSION keyword in a call to cmake_minimum_required().
  • Added a paragraph to the Custom Build Types section, explaining why the CMAKE_STATIC_LINKER_FLAGS_<CONFIG> variable is set to an empty string when defining the custom <CONFIG> configuration.

Compiler And Linker Essentials chapter:

  • Added some discussion to the De-duplicating Options section to highlight that the way de-duplication is done is not documented, and that it might not keep the occurrence one might expect.
  • Added a paragraph to the Recommended Practices section to advise appropriate use of the SHELL: prefix to avoid unwanted de-duplication, and avoid relying on de-duplication behaving a particular way when defining compiler and linker options.

Custom Tasks chapter:

  • Updated the Adding Build Steps To An Existing Target section to account for CMake 4.1 now accumulating content from the COMMENT keyword passed to add_custom_command(TARGET) instead of ignoring those comments. The Recommended Practices section was also updated for the same change.
  • Added a paragraph to the Platform Independent Commands section to highlight that forcing output at build time with cmake -E echo ... should be avoided now that COMMENT content is honored in add_custom_command(TARGET) output.

Working With Files chapter:

  • CMake 4.2 added support to cmake -E for copy_if_newer and copy_directory_if_newer subcommands.

Apple Features chapter:

  • CMake 4.1 officially documented as supported specifying a directory in MACOSX_PACKAGE_LOCATION and listing a directory as a source for a target so you could use that. This has worked unofficially for a long time, but it is now formally supported.

Build Performance chapter:

  • CMake 4.2 added support for a new UNITY_BUILD_FILENAME_PREFIX target property, which can be used to customize the build progress message when compiling unity sources for that target.
  • It is now possible to override the Ninja job pool for a specific source file using the new JOB_POOL_COMPILE source file property, as of CMake 4.2.

Test Frameworks chapter:

  • CMake 4.1 deprecated most variables for the FindGTest module. Projects should use only the module’s imported targets instead.

Static Code Analysis chapter:

  • CMake 4.2 added a new SKIP_LINTING target property and associated CMAKE_SKIP_LINTING CMake variable. These can be used to disable linting at the target level, whereas previously it had to be done on each source file individually.

Finding Things chapter:

  • Briefly mention that CMake 4.1 improved the information it records in the configure log for find_...() commands.

Package Generators chapter:

  • CMake 4.2 added a new AppImage generator.

ExternalProject chapter:

  • Added sub-section to the Miscellaneous Features section for improved navigation.
  • CMake 4.2 added support for modifying environment variables for the configure, build, test, and package steps, and for custom steps.

Dependency Providers chapter:

  • Modified examples and updated discussions to use cmake_policy(VERSION) rather than cmake_minimum_required(VERSION) when defining dependency providers. This is to avoid leaking changes to the CMAKE_MINIMUM_REQUIRED_VERSION variable into the main project.

Working With Qt chapter:

  • CMake 4.1 added support for a new AUTOMOC_INCLUDE_DIRECTORIES target property and associated CMAKE_AUTOMOC_INCLUDE_DIRECTORIES variable.
  • Qt 6.8 added a new target-based signature for qt_wrap_cpp(). The new form is discussed, and important limitations and bugs in the implementation of the function since Qt 6.8 are highlighted.
  • Qt 6.8 added a new qt_add_ui() command as a replacement for qt_wrap_ui(), which is still supported.

The 21st Edition has been updated for the CMake 4.0 release. A few new usability features were added to CMake, but the most significant change was the removal of all OLD policy behaviours up to CMP0065 (i.e. all policies from CMake 3.4 and earlier). The Policies chapter of the book has been updated to give increased visibility to the policy life cycle, now that OLD behaviours have been completely removed for the first time.

The other major update in this edition is a new Debugging Executables chapter. This contains previous material covering Windows only, but has now been expanded to cover corresponding features for Xcode and some IDE-independent improvements from CMake 4.0. The new chapter is structured to allow focusing on specific problems encountered when running and debugging executables in IDE tools.

In addition to the usual updates, the effort to review existing material, improve clarity, and add more examples continues in this edition. Chapters 19 to 21 have been reviewed and updated, as noted in the details below.

Basic Testing And Deployment chapter:

  • Corrected a Ninja Multi-Config packaging example which previously used --config instead of -C to specify the configuration to package (Release).
  • Added a paragraph to highlight the inconsistency between cmake, ctest, and cpack where they use different options to specify the configuration (--config or -C) .

Policies chapter:

  • Added a new Policy Removal section which covers CMake’s formal policy removal timeline. CMake 4.0 was the first release to completely remove a set of OLD policies and to formally document expectations around future removals.
  • Broke up the Policy Control section into subsections for improved navigation.
  • Moved and expanded content to a new Overriding Policy Defaults And Warnings section. CMake 4.0 added a new CMAKE_POLICY_VERSION_MINIMUM variable to assist with the migration of older projects that still have not been updated to NEW policy settings where the OLD behavior is no longer available.

Debugging And Diagnostics chapter:

  • Added a note at the beginning of the chapter directing attention to the new Debugging Executables chapter for debugging code rather than CMake scripts.

Compiler And Linker Essentials chapter:

  • CMake 4.0 added support for a new ARCHIVER: prefix, which can be used with the STATIC_LIBRARY_OPTIONS target property. CMake 4.0 also extended support for the LINKER: prefix to the LINK_LIBRARIES and INTERFACE_LINK_LIBRARIES target properties. The Linker Flags and De-duplicating Options sections were updated accordingly.
  • CMake 4.0 added a new LINK_WARNING_AS_ERROR target property, an associated CMAKE_LINK_WARNING_AS_ERROR variable, and a --link-no-warning-as-error command line option. These are now covered in the Warnings As Errors section.
  • A new Runtime Checks Selection subsection was added to the Compiler Option Abstractions section. This discusses a new feature in CMake 4.0 which abstracts the /RTC... set of compiler flags when using the Visual Studio compilers.
  • Fixed an error in the example within the Debug Information Format Selection section. The PROPERTIES keyword was missing from the set_target_properties() call in earlier editions.

Language Requirements chapter:

  • This chapter was reviewed and wording improved in various places. Most changes were relatively minor grammatical improvements, with a few paragraphs being merged or reworked more substantially.
  • A new example was added to the Requirements For C++20 Modules section, showing how to set source file properties to disable scanning specific files for C++20 modules.

Advanced Linking chapter:

  • This chapter was reviewed, but no significant changes were made.

Target Types chapter:

  • This chapter was reviewed, and some minor improvements were made to readability. A few paragraphs in the Imported Libraries section were moved to the end of that section for improved logical flow.

Custom Tasks chapter:

  • A new INSTALL_JOB_SERVER_AWARE keyword was added to ExternalProject_Add() in CMake 4.0, and this is now mentioned very briefly with the JOB_SERVER_AWARE keyword in the Custom Targets section.
  • CMake 4.0 added a new CMAKE_EXECUTE_PROCESS_COMMAND_ERROR_IS_FATAL variable, which affects the default behavior of execute_process() when a command fails.

Package Generators chapter:

  • CMake 4.0 added support for a TAR package format with no compression.

Project Structure chapter:

  • Updated a paragraph in the Target Output Locations section to mention PROJECT_BINARY_DIR as another alternative to CMAKE_CURRENT_BINARY_DIR as preferred relative base directories over CMAKE_BINARY_DIR.
  • Move the Windows-specific Issues section content out to the new Debugging Executables chapter. The associated comments in the Recommended Practices section were also moved to that chapter.

Debugging Executables chapter:

  • This is a new chapter focused on the task of running executables in IDEs. Some of the content is moved from the Windows-specific Issues section of the Project Structure chapter. That content has been expanded to also cover equivalent features for Xcode.
  • The new DEBUGGER_WORKING_DIRECTORY target property added in CMake 4.0 is discussed prominently, including its relationship to the existing VS_DEBUGGER_WORKING_DIRECTORY and XCODE_SCHEME_WORKING_DIRECTORY target properties.

The 20th Edition has been updated for the CMake 3.31 release, which was a relatively minor update. This edition focuses mainly on correcting errata throughout the book.

Building Simple Targets chapter:

  • The third-last paragraph in the Linking Targets section contained a cross-reference that linked to the wrong content. The link to the Libraries chapter has been replaced with links to the Linking Libraries and Linking Static Libraries sections.

Basic Testing And Deployment chapter:

  • The Installing section contained an error in one of its examples. An install(DIRECTORY headers/ ...) example specified the wrong DESTINATION by including an extra trailing myproj. This has been fixed.
  • The Packaging section had a typo, specifying the incorrect variable name CPACK_GENERATORS instead of the correct CPACK_GENERATOR variable name. This has also been fixed.

Variables chapter:

  • In the CMake GUI Tools section, it incorrectly stated that a change in the value of a cache variable would result in that variable being highlighted at the end of the configure step. This is incorrect, only new variables are highlighted in red. The inaccurate text has been updated to make the behavior clear.

Using Subdirectories chapter:

  • The valid scopes from which project variables like <projectName>_SOURCE_DIR can be safely read has a complicated history in CMake. The wording in this chapter has been updated to make clear that such variables should only be read for a project defined in the same or a parent scope. The previous wording implied that they could be read from anywhere in the project, but this isn’t always safe. The wording now also no longer claims that these are cache variables (they might not be in all cases).

Modules chapter:

  • CMake 3.31 added a new CMAKE_REQUIRED_LINK_DIRECTORIES variable, which influences the various compilation test commands like the check_<lang>_source_compiles() family of commands.
  • The Checking Existence And Support chapter claimed that the check_<lang>_source_compiles() commands could return an error message in some situations. This is not the case, and the offending sentence has been removed.
  • The check_symbol_exists() and check_cxx_symbol_exists() commands historically required that the symbol names must always be a valid preprocessor symbol. That restriction was removed in CMake 3.16, but the book had not been updated accordingly. It has now been updated to account for this change.
  • The last example in the Checking Existence And Support chapter (pushing and popping check state) contained a typo. It set a variable named CMAKE_REQUIRED_DEFINES instead of the correct name CMAKE_REQUIRED_DEFINITIONS. This has been fixed.

Compiler And Linker Essentials chapter:

  • The Directory Properties And Commands section inaccurately described how flags that did not look like compile definitions are handled by the add_definitions() and remove_definitions() commands. The text wrongly stated that such flags are added to the COMPILE_OPTIONS directory property, but they are actually handled via an internal mechanism not exposed to the project. The offending text has been corrected.
  • In the example for the add_compile_options() command, the comment mentioned the wrong subdirectory in the first comment. It erroneously mentioned the "second" subdirectory, but it should have been "first". This has been corrected.

Advanced Linking chapter:

  • A new section Library Ordering And De-duplication was added. It discusses how CMake may reorder and de-duplicate the libraries on the linker command line, and it mentions the new LINK_LIBRARIES_STRATEGY target property added in CMake 3.31.

Custom Tasks chapter:

  • In CMake 3.31, the add_custom_command() command gained a new CODEGEN keyword. The Commands That Generate Files section was expanded and updated to account for this new keyword.

Working With Files chapter:

  • CMake 3.31 changed the default behavior when the CMAKE_TLS_VERIFY cache and environment variables are not defined, and it also changed the default minimum TLS version to 1.2. The text was updated to mention both changes.

Libraries chapter:

  • A brief paragraph was added to the end of the Linking Static Libraries section to mention that CMake may change the order and de-duplicate libraries on the linker command line.

Toolchains And Cross Compiling chapter:

  • The text and examples in the Using The NDK section have been updated to account for the Android NDK r27 release adding support for a larger 16KiB page size, and r28 changing the default to that new page size.

Apple Features chapter:

  • The Deployment Target section contained an error, mentioning an OSX_DEPLOYMENT_TARGET target property which doesn’t exist. Only the CMAKE_OSX_DEPLOYMENT_TARGET variable exists, and the wording was updated to more correctly explain its use. A similar error in the Recommended Practices section was also fixed.
  • The text of the Creating And Exporting Archives section contained a typo. It mentioned MyApp.archive instead of the MyApp.xcarchive name used in all the examples. This typo has been fixed.
  • An example in the Embedding Frameworks And Other Things section contained an error where it was meant to set the CMAKE_BUILD_WITH_INSTALL_RPATH variable to YES, but the value was erroneously omitted. This example has been updated to set the value as originally intended.

Build Performance chapter:

  • The Unity Builds section was updated to account for CMake 3.31 adding unity build support for CUDA.

Test Resources And Constraints chapter:

  • The Parallel Execution and Recommended Practices sections erroneously claimed that ctest supports a -l command line option, but the option name is actually --test-load. The Parallel Execution section has been reorganised to improve the logical flow, and this error has been corrected as part of that reorganisation. The discussion of the effectiveness of --test-load has also been updated to more accurately describe the problems with using it.
  • It was also previously claimed that parallel execution had to be enabled for the load limit (--test-load) to be honoured, but this is not the case. Even for serial execution, the load limit will be considered if the system is already busy with other processes. The offending claim has been removed.

Test Frameworks chapter:

  • The gtest_discover_tests() command gained a new DISCOVERY_EXTRA_ARGS keyword in CMake 3.31. The signature of that command has been updated in the GoogleTest section, but the new option is not discussed further.

Static Code Analysis chapter:

  • In the Settings subsection of the clang-tidy section, the small example showing how to override clang-tidy options in a subdirectory contained a typo. In the Checks line, it should have excluded the clang-analyzer-* checks, but it was missing a leading hyphen and was therefore adding them instead. This has been fixed.

Finding Things chapter:

  • The Finding Libraries section discusses how to prefer static libraries over shared during the search. The text and example used to highlight robustness problems with using NAMES to implement this was wrong, being based around the behavior when the NAMES_PER_DIR keyword is present, but not actually using that keyword in the example. The text and examples have been reworked and expanded to remove the error and to demonstrate the originally intended problem involving NAMES_PER_DIR.

Installing chapter:

  • The Whole Directories subsection of the Installing Files section contained an error in one of its examples. An install(DIRECTORY) command contained both the FILES_MATCHING and EXCLUDE keywords, but that would result in no files being installed. The FILES_MATCHING keyword should not have been there and has been removed.

Packaging chapter:

  • The Multiple Build Directories section contained some typos. It specified the wrong variable names CMAKE_COMPONENTS_ALL, CMAKE_COMPONENTS_XXX, and CMAKE_COMPONENTS_RUNTIME instead of the correct names CPACK_COMPONENTS_ALL, CPACK_COMPONENTS_XXX, and CPACK_COMPONENTS_RUNTIME. These have all been corrected.
  • The Multiple Build Directories section discusses the CPACK_INSTALL_CMAKE_PROJECTS variable. The “project name” part was previously described as “…only important for multi-configuration generators”. While that may have once been true, it is now only used exclusively for log output. The text has been updated accordingly.
  • The explanation of the third field of a CPACK_INSTALL_CMAKE_PROJECTS quadruple was both incomplete and lacking clarity. That field can be either a component name, or the name of a set of components, but the previous text conflated the two. The text and examples in Multiple Build Directories have been updated to clearly explain both ways of using this field.

Package Generators chapter:

  • CMake 3.31 brought back the change to make perMachine the default install scope for the WIX package generator (set by the CPACK_WIX_INSTALL_SCOPE variable), but this time subject to a new policy.
  • CMake 3.31 added a new CPACK_IFW_PACKAGE_PRODUCT_IMAGE_URLS variable.
  • Added a recommendation to the Inno Setup section to disable the licensing page during installation, preferring to show it when the installed application is run instead so that the installer can support scripted, unattended installs.

Presets chapter:

  • CMake 3.31 added presets schema version 10. This has been added to the corresponding version table in the High Level Structure section.
  • Presets schema 10 supports a new $comment field. A new Comments subsection was added to the Configure Presets section to show how to use it, along with workarounds for adding comments with earlier schema versions.
  • CMake 3.31 supports a slightly simpler command line for executing a workflow. The --preset option can be omitted, allowing the simpler and more intuitive command line: cmake --workflow presetName

Project Structure chapter:

  • The VS_DEBUGGER_ENVIRONMENT example in the Windows-specific Issues section was updated to use %PATH% instead of $ENV{PATH}. This is more consistent with the recommendation to use ENVIRONMENT_MODIFICATION for the non-Windows cases. It will modify the PATH environment variable at test time rather than completely replacing it with whatever the environment held during CMake configuration.

Working With Qt chapter:

  • A paragraph was added to the Recommended Practices section, highlighting that the I18N_TRANSLATED_LANGUAGES keyword should always be given in the call to qt_standard_project_setup() if the project supports translations.

The 19th Edition has been updated for the CMake 3.30 release and for Qt 6.7. The main new CMake feature covered in this edition is the new FetchContent behavior that avoids a sub-build. This is a potential big performance gain for large projects with many dependencies. The new translations APIs added in Qt 6.7 are another significant update for this edition.

The book has grown in size, and some parts are fairly verbose. In addition, the number one piece of reader feedback is for more examples. The main focus of this edition has been to begin addressing these two things. The first 18 chapters (parts 1 and 2 of the book) have been reviewed and reworked in this edition, and this work will continue in future editions for the remaining chapters.

Setup Project chapter:

  • Updated examples to use cmake -B build ... instead of manually making and changing to the build directory first.

Building Simple Targets chapter:

  • Added an example to the Executables section for add_executable() showing the effect of the EXCLUDE_FROM_ALL keyword and a motivating case for why you might want to use it.
  • Updated the wording and advice in the Linking Non-targets section. Policy CMP0060 is no longer mentioned, advice for plain library names now cross-references the chapter that talks about requiring target names for linking, and the link flags item advises against using them and to use the dedicated support for adding such flags instead (with cross-references to the relevant sections).
  • The Old-style CMake section now mentions policy CMP0023 when discussing what happens when mixing the keyword and non-keyword forms of target_link_libraries().
  • Updated examples to use cmake -B build ... instead of manually making and changing to the build directory first.

Basic Testing And Deployment chapter:

  • Added a brief mention of the CMAKE_TEST_ARGUMENTS variable when discussing how to run ctest via the test build target.
  • Updated examples to use cmake -B build ... instead of manually making and changing to the build directory first.

Variables chapter:

  • The String Handling and Lists sections were reworked to have less text, and to use more examples instead of formal command syntax for string() and list(). Related examples were also combined to reduce verbosity, and these sections now avoid repeating a lot of the command details that are already clearly explained in the official CMake reference documentation for these two commands.

Flow Control chapter:

  • Added an example demonstrating a common trap with how the if() command can treat an unquoted value as a string or a variable name, depending on whether a variable by that name exists. Guidelines were also added to help avoid running into problems related to this behavior.
  • Added a brief discussion and example for how the if(COMMAND) form can be useful for checking the availability of a command provided by a third party as a technology preview. Simple examples were also added for if(POLICY)and if(TARGET).
  • Mention that if(TEST) can only be used if policy CMP0064 is set to NEW.
  • Updated the example for if(IN_LIST) to also show the older, more verbose logic based on list(FIND) for when policy CMP0057 cannot be assumed to be NEW.
  • Updated the example in the Interrupting Loops subsection to use set(s "") instead of unset(s). This is more robust, since it doesn’t rely on there not being a cache variable named s.
  • The Recommended Practices section was updated to explicitly mention ensuring policy CMP0054 is set to NEW as part of setting the minimum CMake version.

Functions And Macros chapter:

  • Updated examples involving cmake_parse_arguments() to use lowercase arg as the variable prefix instead of other uppercase values like ARG. This makes it easier to visually spot any use of the resultant variables instead of them looking like cache variables or keywords.
  • Discussion and examples of tracking deferred commands using cmake_language(DEFER) via their ID have been removed. This is a very advanced topic that few projects need, and it made the rest of the material related to cmake_language(DEFER) seem more complicated. That part of the Other Ways Of Invoking CMake Code section now focuses on the more common uses of cmake_language(DEFER).
  • Added a paragraph to the Recommended Practices section warning against implementing overly complex keyword and argument parsing with cmake_parse_arguments(). The advice highlights that this is often a sign of a function or macro having too many responsibilities.

Properties chapter:

  • Added examples to the General Property Commands section showing calls to set_property() and get_property() for the various property types. Examples were also added showing how the inheriting behavior of get_property() works for target and directory properties, including how it interacts with set_property().
  • Added an example to the Global Properties section for get_cmake_property().
  • Added an example to the Directory Properties section to demonstrate the pros and cons of set_property(DIRECTORY) versus set_directory_properties(). An example was also added for get_directory_property().
  • Added examples to the Target Properties section for set_target_properties() and get_target_property(). An explanation was also added for an important difference in behavior between get_property(TARGET) and get_target_property() for an unset property.
  • Added an example to the Source Properties section for set_source_files_properties(), showing how to handle calls in a different directory scope. This section also now highlights behavior differences between get_property(SOURCE) and get_source_file_property() for an unset property.
  • Added an example to the Cache Variable Properties section showing all cache variable properties being set by their more typical commands.
  • Added an example to the Test Properties section, showing how to manipulate test properties across different directories.

Generator Expressions chapter:

  • Mention that $<CONFIG:...> is a case-insensitive comparison.
  • Added examples for $<TARGET_PROPERTY:...> and $<TARGET_FILE_NAME:...> to the Target Details section.
  • Added an example to the List Expressions section showing a few commonly used sub-expressions for $<LIST:...>.
  • Added an example to the Utility Expressions section for $<COMMA>. The section was also updated for the new $<QUOTE> generator expression added in CMake 3.30.

Policies chapter:

  • Added an example to the Policy Control section showing how to use CMAKE_POLICY_DEFAULT_CMPxxxx variables to enable the new FetchContent direct population behavior globally.

Debugging And Diagnostics chapter:

  • Added an example to the Tracing Variable Access section showing how to define a command to receive variable_watch() events.
  • Added mention of Perfetto to the list of tools for viewing profiling information mentioned in the Recommended Practices section.

Build Type chapter:

  • Updated an example in the Common Errors section that shows wrong use of CMAKE_BUILD_TYPE to set a compiler definition, and added a second example showing how to do it correctly using a $<CONFIG:...> generator expression.
  • Updated the examples and text in the Custom Build Types section to no longer show enforcing the configuration to be one of a predefined set of values. Developers should be free to add their own new build types.
  • Updated examples to use cmake -B build ... instead of manually making and changing to the build directory first.

Compiler And Linker Essentials chapter:

  • Updated an example in the Linker Flags section to use set_property(TARGET) instead of set_target_properties() so that it can use the APPEND keyword to add to the existing linker options, not replace them.
  • Added a discussion and example to the Linking Libraries subsection explaining the behavior of PRIVATE with static and object libraries.
  • Slightly reordered parts of the Linker Options subsection to improve the flow.
  • Added an example and additional discussion to the Header Search Paths subsection for the interaction between generator expressions and the use of relative paths with target_include_directories().
  • Added a target_compile_definitions() example to the Compiler Defines subsection.
  • Added an example to the Compiler Options section to highlight how some things can safely be set conditionally using if() logic, but others must use generator expressions.
  • Added a number of examples to the Directory Properties And Command section to highlight the different behavior of properties and commands regarding their effect depending on where they are set or called (before or after a target is created). An example was also added to show the usefulness of generator expressions for setting language-specific options with add_compile_options().
  • The discussion of the debug, optimized, and general keywords for link_libraries() in the Directory Properties And Command section was significantly reduced, and the DEBUG_CONFIGURATIONS global property is no longer mentioned. These are very old features that projects should no longer need or use.
  • The System Header Search Paths subsection contains an example that uses FetchContent. Previous versions had a call to FetchContent_MakeAvailable() with no argument. This has now been corrected to include the missing anotherdep argument.
  • A paragraph was added to the Runtime Library Selection subsection for the new VS_USE_DEBUG_LIBRARIES target property and CMAKE_VS_USE_DEBUG_LIBRARIES variable added in CMake 3.30.

Language Requirements chapter:

  • The <LANG>_STANDARD part of the Setting The Language Standard Directly section was rewritten to use tables to show which CMake versions support which language versions. The previous editions had become hard to read as more standards and versions were added, and the new tables are much easier to digest at a glance. Details for the HIP language are now also included in the tables.
  • The Requirements For C++20 Modules section was updated to make clear that an error is generated in the consuming project rather than the exporting project if a cxx_std_20 compile feature or higher isn’t set on an exported target.

Advanced Linking chapter:

  • CMake 3.30 added some improvements around combinations of link features. A brief note was added about this to the Custom Features subsection.

Custom Tasks chapter:

  • Added a brief paragraph to the end of the Commands That Generate Files section, mentioning the relevance of the CMP0118 and CMP0163 policies for generated files.

Working With Files chapter:

  • CMake 3.30 added support for a TLS_VERSION keyword for file(UPLOAD) and file(DOWNLOAD), and an associated CMAKE_TLS_VERIFY environment variable and CMake variable. The Downloading And Uploading section has been updated accordingly.

Libraries chapter:

  • The last paragraph in the Additional Complications With C++20 Modules subsection was updated to highlight that any files a module interface file depends on must also be installed, such as the algo_export.h header of the preceding example.

Toolchains And Cross Compiling chapter:

  • Updated the Compiler Checks section to make clear that the CMAKE_TRY_COMPILE_TARGET_TYPE variable should only be set in a toolchain file, not by a project.

Build And Test Mode chapter:

  • Updated examples to use cmake -B build ... instead of manually making and changing to the build directory first.

Installing chapter:

  • In the Runtime Dependency Sets subsection, the install(RUNTIME_DEPENDENCY_SET) example for Windows contained a robustness issue. The POST_EXCLUDE_REGEXES regular expression assumed paths only contained forward slashes (/). But CMake doesn’t guarantee this, and in fact sometimes it produces paths with mixed path separators. The example has been updated to handle both forward or backslashes as path separators. A paragraph was also added after the example to highlight this behavior.

Package Generators chapter:

  • The default behavior of the CPACK_WIX_INSTALL_SCOPE variable was reverted late in the CMake 3.29 release series (3.29.5). The default was changed again in CMake 3.30, but only for the newly supported WIX 4 version. Issues were also found when updating packages installed with an older cpack version if the install scope was changed, requiring projects to manually alert their users to the problem. These things are now discussed at the end of the WIX section.

FetchContent chapter:

  • In the opening paragraph, added 3.30 as one of the CMake versions with significant improvements for FetchContent.
  • The note at the end of the Basic Usage section was updated to highlight that the old manual population pattern is now officially deprecated as of CMake 3.30.
  • A new Avoiding Sub-builds For Population section has been added. CMake 3.30 gained the ability to avoid using a separate sub-build to fetch each dependency. It can now use a much more efficient method that directly executes as part of the main project. Performance gains for large projects with many dependencies can be substantial for Windows and Xcode builds. The Recommended Practices section was also updated with a recommendation to use this new behavior.
  • The Developer Overrides section was reordered slightly to improve the logical flow.

Presets chapter:

  • CMake 3.30 added presets schema version 9. This has been added to the corresponding version table in the High Level Structure section.

Working With Qt chapter:

  • Some Qt-provided translation commands for CMake have been in technology preview since early in the Qt 6 timeframe. Qt 6.7 made them official, but at the same time deprecated them in favour of better replacements. Examples throughout this chapter have been updated to use Qt 6.7 as their version for consistency with the newer APIs.
  • The Translations section was substantially reworked to reflect the new form of the qt_add_translations() command, and the associated changes to the qt_standard_project_setup() command. The old form is still discussed, but in less detail.
  • The Qt Deployment Tools subsection was updated to mention the new DEPLOY_TOOL_OPTIONS keyword for qt_generate_deploy_app_script(), which was added in Qt 6.7.
  • The Deploying Translation Files subsection and the Recommended Practices section were also updated to reflect the new API added in Qt 6.7.

The 18th Edition has been updated for the CMake 3.29 release. This is a fairly modest update, consisting mostly of incremental improvements and a few smaller new features. Full details of the changes are given below.

Flow Control chapter:

  • CMake 3.29 added new IS_READABLE, IS_WRITABLE, and IS_EXECUTABLE expressions for the if() command.

Functions And Macros chapter:

  • The Problems With Argument Handling section contains a small example highlighting the interaction between semicolons and quoting. That example block contained three similar someCommand() calls that earlier editions claimed all produced the same number of arguments, but the third one, someCommand(a;";";c) was in fact different to the other two. This third command has now been dropped from that example.

Language Requirements chapter:

  • The last example in the Setting The Language Standard Directly section contained an error. It was comparing CMAKE_CXX_STANDARD against the values 90 and 99, but those are for the C language, not C++. The example has been updated to compare CMAKE_CXX_STANDARD against 98 instead of those two values.

Custom Tasks chapter:

  • Starting with CMake 3.29, an alias target can now be passed to add_custom_command(TARGET...) when adding build events.
  • CMake 3.29 added a new cmake_language(EXIT) subcommand to immediately end execution. It can only be used in CMake script mode.

Toolchains And Cross Compiling chapter:

  • Starting with version 3.29, CMake now provides a set of CMAKE_<LANG>_COMPILER_LINKER... variables that give information about the linker.

Apple Features chapter:

  • The Xcode generator gained support for embedding XPC services with CMake 3.29.

Build Performance chapter:

  • Unity builds are supported for OBJC and OBJCXX languages starting with CMake 3.29.
  • CMake 3.29 gained a new abstraction for selecting the linker to use. A new CMAKE_LINKER_TYPE variable is the primary way to select the linker, with supporting variables that can be used to define custom linkers if required. Importantly, this new abstraction also supports the new mold linker.
  • The Alternative Linkers section was updated to drop the paragraph and supporting example that discussed using add_link_options() within a project to add raw flags for linker selection. Even with CMake 3.28 or older, that method fails to pass linker details to any try_compile() sub-builds, so it is not robust.

Testing Fundamentals chapter:

  • CMake 3.29 added support for specifying a file containing a list of test names to include or exclude. The Regular Expressions subsection was expanded to cover this new feature and the subsection was renamed to Test Names to reflect its broadened scope.
  • CMake 3.29 added a dedicated test launcher feature. The existing CROSSCOMPILING_EMULATOR property could previously have been repurposed to achieve a similar result, but that was not obvious nor originally intended. The new TEST_LAUNCHER test property has a clear responsibility and the behavior of CROSSCOMPILING_EMULATOR has been changed with policy CMP0158 for non-cross-compiling scenarios. The Cross-compiling And Emulators section was updated and renamed to Cross-compiling, Emulators, And Launchers to reflect these changes. The Recommended Practices section was also updated.

Test Resources And Constraints chapter:

  • Starting with CMake 3.29, the ctest -j and ctest --parallel options now accept the special value 0, or can be given with no value at all. These have special meaning and are intended primarily for situations where ctest is running as a subprocess under a make job server. The CTEST_PARALLEL_LEVEL environment variable support was also updated similarly.

Installing chapter:

  • CMake 3.29 added support for using a CMAKE_INSTALL_PREFIX environment variable to initialize the same-named CMake cache variable.
  • Two new Apple-specific commands, generate_apple_{platform,architecture}_selection_file(), were added to the CMakePackageConfigHelpers module in CMake 3.29. The commands are mentioned briefly at the end of the Config Files For CMake Projects subsection.

Package Generators chapter:

  • A paragraph was added to the WIX section to highlight a long-standing bug with installers generated by CMake 3.28 and earlier. The bug related to the installer only installing some things for the current user instead of all users. CMake 3.29 fixed the bug and also added a new CPACK_WIX_INSTALL_SCOPE variable to specify the type of install to allow.
  • CMake 3.29 changed the default for the CPACK_PRODUCTBUILD_DOMAINS variable via policy CMP0161. The new default enables domains, which avoids using deprecated methods and generates installers with more desirable behavior by default.

Project Structure chapter:

  • The various CMAKE_PROJECT_...INCLUDE... variables associated with the project() command can contain a list rather than just a file name starting with CMake 3.29. List items can also be CMake modules, not just file names.

The 17th Edition has been updated for the CMake 3.28 release. The main highlights for this edition are support for C++20 modules and using XCFrameworks. Motivated by stronger requirements resulting from C++20 modules, the advice in the Language Requirements chapter has also been substantially updated. The changes apply to most projects, not just those using C++20 modules, so it is recommended that all developers review the updated advice in that chapter.

This edition also continues the structural improvements begun in the 16th Edition. File sets are becoming more important in CMake, so relevant details are now covered in earlier chapters instead of most of the material being delayed to the Installing chapter.

Full details of the changes are given below.

Properties chapter:

  • CMake 3.28 made it possible to specify the directory in which to find the test whose properties are being set or queried.
  • The previous Other Property Types section was split up into dedicated Test Properties and Installed File Properties sections.
  • Fixed a test property example which used the wrong argument order for get_test_property(). This example was previously in the Other Property Types section, and is now in the Test Properties section.

Modules chapter:

  • Fixed a wrong cross-reference to the Packaging chapter, which previously linked to the Packaging section in the Getting Started Guide by mistake.

Compiler And Linker Essentials chapter:

  • Added a new File Sets section. This mostly contains material that was previously found in the File Sets section of the Installing chapter, but it has also been updated to mention the new CXX_MODULES file set type for C++20 modules. The new section covers important information much earlier in the book, reflecting the increasingly fundamental nature of file sets in CMake.
  • Added a note early in the Header Search Paths section to highlight that file sets are now a better way to handle header search paths than raw calls to target_include_directories().
  • Slightly reordered some of the paragraphs in the Header Search Paths section to improve the logical flow.
  • Improved the explanation in Header Search Paths regarding the interaction of relative and absolute paths with generator expressions.
  • Added a paragraph to the Recommended Practices section recommending that all headers owned by a target be put into file sets.
  • Replaced all uses of Foo with better names throughout the chapter.
  • Fixed a wrong cross-reference to the Packaging chapter, which previously linked to the Packaging section in the Getting Started Guide by mistake.

Language Requirements chapter:

This chapter received a fairly significant overhaul. Some important recommendations affecting widely used patterns have been changed to better account for requirements of parent projects, and to support new constraints associated with C++20 modules.

  • The recommended way to set the CMAKE_<LANG>_STANDARD and CMAKE_<LANG>_EXTENSIONS variables has been updated. The new recommendations take into account the scenario where a parent project may want to override what a project would normally set, such as when using FetchContent. The need to use a consistent language standard and other compiler settings throughout the build has also become much more important with C++20 modules, and parent projects may need to enforce new constraints related to that.
  • Setting The Language Standard Directly now recommends not setting the <LANG>_STANDARD target property directly, instead letting it be controlled by CMAKE_<LANG>_STANDARD so that parent projects can override it.
  • The discussion of individual compile features has been removed from the Setting The Language Standard By Feature Requirements section. These individual compile features have little benefit with actively used compilers today. Projects should use the meta features like cpp_std_11 for the relevant language standard instead.
  • A new Requirements For C++20 Modules section was added to discuss new language requirements related to the C++20 module support added in CMake 3.28. This section covers the essential things needed to build a project that defines and uses its own C++20 modules. Later chapters deal with other important aspects of C++20 modules.
  • The Recommended Practices section was updated to reflect the new recommendations around CMAKE_<LANG>_STANDARD and CMAKE_<LANG>_EXTENSIONS, and the new C++20 modules support. Previous recommendations around detailed compile features has been removed, being replaced by a recommendation to not use them and instead use the language standard meta feature.

Target Types chapter:

  • The Imported Libraries section was updated to explain the CMake 3.28 changes affecting imported libraries with improved support for Apple frameworks, new support for Apple XCFrameworks, and expanded support for stub or import libraries for a number of platforms (at least Apple, Linux and AIX).

Custom Tasks chapter:

  • CMake 3.28 added support for a new JOBY_SERVER_AWARE option to add_custom_command() and add_custom_target().
  • The Commands That Generate Files section was expanded to explain new behavior in CMake 3.28 which affects how generated files are treated with regard to dependencies between targets. This is an important change, as it is also affected by whether or not a target uses file sets, and the behavior change does not trigger a policy warning while the project relies on the OLD policy setting.

Specifying Version Details chapter:

  • Fixed a wrong cross-reference to the Packaging chapter, which previously linked to the Packaging section in the Getting Started Guide by mistake.

Libraries chapter:

  • A new Additional Complications With C++20 Modules subsection was added to the Symbol Visibility section. CMake 3.28 added support for C++20 modules, but the symbol visibility aspects of that are poorly understood and are rarely mentioned in documentation. This new section highlights some common misconceptions about C++20 modules, and it provides a simple but complete example showing the important symbol visibility aspects of producing a shared library that exports a C++20 module.

Toolchains And Cross Compiling chapter:

  • Added mention of visionOS in a few places where Apple platforms are listed (new support in CMake 3.28).
  • Fixed example command lines in the Tool Selection section to use the correct name for the Visual Studio 16 2019 generator.
  • Minor update to the example in GCC With 32-bit Target On 64-bit Host to use STATUS with the call to message().

Apple Features chapter:

  • CMake 3.28 added support for visionOS. Various parts of this chapter have been updated to mention visionOS and XROS where relevant, but apart from naming the newly supported platform, no other explanations were needed.
  • A new Other Helpful Build Settings section was added, which discusses the CLANG_ENABLE_OBJC_ARC, CLANG_ENABLE_OBJC_WEAK, and CLANG_ENABLE_MODULES Xcode settings. The defaults for these in the CMake-generated file differ from the defaults in an Xcode-generated file. This section highlights that and explains why you may want to explicitly set them, along with the directly related clang module verifier.
  • A new XCFrameworks section was added. CMake 3.28 gained support for consuming XCFrameworks, but not producing one. The new section explains how to use that new support, and also provides some minimal details for creating an XCFramework.
  • The Universal Binaries section was updated to account for XCFrameworks. Apple now discourages putting device and simulator slices in the one universal binary. They now recommend XCFrameworks for that.
  • Linking Frameworks was updated to mention auto-linking of frameworks, which Other Helpful Build Settings now covers.
  • CMake 3.28 gained support for embedding resources, and extended the framework embedding support to XCFrameworks. The Embedding Frameworks, Plugins And Extensions section was renamed to Embedding Frameworks And Other Things, and updated to mention the new embedding resources and XCFramework embedding support. A note was also added about an existing CMake bug that prevents listing an imported framework target in XCODE_EMBED_FRAMEWORKS.
  • The IOS_INSTALL_COMBINED target property and its associated CMAKE_IOS_INSTALL_COMBINED variable are deprecated as of CMake 3.28. They don’t work at all with Xcode 15 or later. The Combined Device And Simulator Binaries subsection has been updated to note the deprecation, and the explanation of how to use the feature has been removed.
  • The -destination option for xcodebuild is now mentioned as an alternative to specifying -arch in a number of places.
  • The Recommended Practices section now recommends creating XCFrameworks instead of using the deprecated IOS_INSTALL_COMBINED feature when producing a framework that supports multiple platforms.

Build Performance chapter:

  • The CMake bug preventing the OPTIMIZE_DEPENDENCIES feature from working effectively with Ninja has been fixed in CMake 3.28. The note in the Optimizing Build Dependencies section has been updated accordingly.

Test Resources And Constraints chapter:

  • CMake 3.28 added support for generating the test resource spec file at test time in a nominated test case. The Specifying Available System Resources sub-section explains how to use this new feature.

Test Frameworks chapter:

  • From Xcode 15, CMake cannot run gtest test discovery as a POST_BUILD step. The executable won’t yet be code-signed and fails to run. A note was added to highlight that the project must use PRE_TEST to avoid this limitation. The existing advice already recommended using PRE_TEST in all situations anyway.

Static Code Analysis chapter:

  • A new File Sets Header Verification section was added. Most of the material in this section was previously found in the File Sets subsection of the Installing chapter. The Recommended Practices section was also updated to move and expand some of the associated recommendations from that chapter to here.
  • The Disabling Checks For Some Files section was moved to later in the chapter after the new File Sets Header Verification section for better overall flow.

Dynamic Code Analysis chapter:

  • Fixed malformed command line in the Xcode Generator section where a line continuation was missing on the cmake --build example.

Finding Things chapter:

  • CMake 3.28 dropped the special Windows-only additional behavior of some find_...() commands relating to how the PATH environment variable is used.
  • The pkg_get_variable() command from the FindPkgConfig module gained a new DEFINE_VARIABLES keyword in CMake 3.28.

Installing chapter:

  • A new Installing C++20 Modules section was added to cover the installation part of the C++20 module support added in CMake 3.28. The new section discusses how to install a library that exports a C++20 module, along with some of the issues surrounding BMI files. It is closely related to the symbol visibility material added in the Libraries chapter, and extends that chapter’s example to demonstrate its installation.
  • The install(TARGETS) command gained a new CXX_MODULES entity type in CMake 3.28.
  • The install(EXPORT) command gained a new CXX_MODULES_DIRECTORY keyword in CMake 3.28.
  • The File Sets section has been refactored, with much of the material moving to earlier chapters. This section now focuses on just the installation aspects of file sets.
  • Advice was added to the Recommended Practices section regarding the use and installation of C++20 modules.
  • All uses of foo and bar have been replaced with alternative names throughout the chapter.

FetchContent chapter:

  • CMake 3.28 added a new EXCLUDE_FROM_ALL option to FetchContent_Declare().

Presets chapter:

  • CMake 3.28 added presets schema version 8, which is a minor change that only adds support for a new $schema field.

Working With Qt chapter:

  • Fixed a wrong cross-reference to the Packaging chapter, which previously linked to the Packaging section in the Getting Started Guide by mistake.

The 16th Edition has been updated for the CMake 3.27 release. The main highlights for this edition include three new chapters:

  • Basic Testing And Deployment
  • Static Code Analysis
  • Dynamic Code Analysis

This edition also includes some structural improvements aimed at making things easier to find and more coherently grouped. Some of the larger chapters have been split up into smaller, more focused chapters that are easier to digest. The first part of the book (five chapters) is also now being made available as a free Getting Started guide.

Full details of the changes are given below.

Part And Chapter Reorganization:

A major focus for this release was to provide a Getting Started set of chapters at the beginning of the book, and to make those chapters freely available as a separate download. For any developer who has never used CMake before, this should provide the basics of using CMake, all the way up to producing simple packages. The first four chapters previously did this up to building simple targets, and a new chapter has been added in this edition to provide an introduction to testing, installing, and packaging.

A second major change with this edition was to split up the Testing chapter into a five separate chapters, group them under a new Testing And Analysis part, and add two completely new chapters on static and dynamic code analysis. Splitting up the existing chapter into smaller, more focused chapters makes each one less daunting, and the reader can more easily find and focus on just the aspect they are interested in learning about. The two new code analysis chapters are also a significant addition to the book, covering tools like clang-tidy, cppcheck, cpplint, include-what-you-use, sanitizers and code coverage.

As the book has grown with each edition, it has become quite large. The reader is now unlikely to want to work through the entire book in order, chapter-by-chapter. To help give clearer direction in guiding the reader, the BuildTypes and Compiler And Linker Essentials chapters have been moved to the Fundamentals part. All parts after that can now be seen as pick-and-choose chapters rather than “continue reading these in order”. It is anticipated that this will be further refined in subsequent editions to help make the book less daunting, but still be a rich resource for learning CMake.

Preface:

  • Updated with a paragraph about consulting activities since the book was first published, and how they drive updates of the book and contributions to CMake itself.

Acknowledgements:

  • Expanded and reformatted the list of individuals who have contributed to the book through reviews, corrections, and feedback. Please get in touch if you believe any names have been left out.

A Minimal Project chapter:

  • Updated the Commenting section to also discuss block comments (#[==[ ... ]==]).

Building Simple Targets chapter:

  • The discussion and code examples in the Recommended Practices section have been updated to more clearly highlight appropriate and inappropriate ways to specify project and target names.

Basic Testing And Deployment chapter:

  • This is an entirely new chapter. Its purpose is to give a basic introduction to testing, installing, and packaging so that the reader can start experimenting with these much earlier in their learning path. It is also included as part of the new Getting Started guide, which is freely available as its own separate download.

Generator Expressions chapter:

  • Added a note that $<PATH:subcommand,...> expressions accept a list of paths with CMake 3.27 or later.
  • Added a new List Expressions section covering the $<LIST:...> expressions added in CMake 3.27.

Debugging And Diagnostics chapter:

  • A new Interactive Debugging section was added to briefly discuss the new support added in CMake 3.27 for the Debug Adapter Protocol. This is mostly for awareness of the feature, not to explain how to use it, since its use is primarily implemented by IDEs.

Build Type chapter:

  • Moved to the Fundamentals part of the book, since the build type is something every developer needs to know about and understand.
  • The Custom Build Types section previously contained examples and advice showing the Profile custom build type’s flags being set in CMake cache variables. That doesn’t work in all cases because the cache variables may already be defined by the time the project was trying to set them. The advice has been updated to use regular non-cache variables instead, with the discussion also mentioning the potential drawbacks of this for developers.

Compiler And Linker Essentials chapter:

  • Moved to the Fundamentals part of the book, since almost every project will use some of the commands, properties and variables discussed in this chapter.
  • A new Target Property Contexts section has been added to provide an expanded discussion of how generator expressions like $<BUILD_INTERFACE:...> and $<INSTALL_INTERFACE:...> affect the way properties are set and used. The expressions $<BUILD_LOCAL_INTERFACE:...> (added in CMake 3.26) and $<COMPILE_ONLY:...> (added in CMake 3.27) are now also discussed, with examples.

Language Requirements chapter:

  • This is now the first chapter in the Builds In Depth part of the book. It was moved one chapter earlier before the Advanced Linking chapter, since it is likely to be more relevant to a wider cross-section of readers. It is also a more logical next step after the Compiler And Linker Essentials chapter.

Target Types chapter:

  • Updated the first main example in the Interface Libraries section to use a $<BUILD_INTERFACE:...> generator expression around the path specified in the call to target_include_directories().

Custom Tasks chapter:

  • Updated the opening paragraph of the Commands That Generate Files section with clearer wording and an example scenario where the OUTPUT form of add_custom_command() is useful.
  • Updated the discussion of relative path handling for the output files in add_custom_command(OUTPUT). The text now advises always using absolute paths for these instead.
  • CMake 3.27 added support for a new DEPENDS_EXPLICIT_ONLY keyword for add_custom_command(OUTPUT). This is discussed briefly in this chapter, with a cross-reference to a more detailed discussion in the Build Performance chapter.

Specifying Version Details chapter:

  • One example was updated to wrap a target_include_directories() path in a $<BUILD_INTERFACE:...> generator expression.

Libraries chapter:

  • A paragraph was added to the Linking Static Libraries section to mention where $<LINK_ONLY:...> may be used by CMake when exporting targets.
  • CMake 3.27 added support for a new DLL_NAME_WITH_SOVERSION target property. The Shared Library Versioning section was updated to cover this, with an example.
  • Paths in target_include_directories() calls have been wrapped in $<BUILD_INTERFACE:...> expressions in the chapter’s examples.

Build Performance chapter:

  • This chapter was moved earlier to the end of the Builds In Depth part of the book. It is squarely focused on build details, so it more logically belongs there rather than near the end of the book.
  • The Optimizing Build Dependencies section was expanded to cover the new DEPENDS_EXPLICIT_ONLY option for add_custom_command(). A paragraph was also inserted at the beginning of that section to make clear it focuses on reducing conservatism in the dependencies.

Testing Fundamentals chapter:

  • This chapter is a reduced version of the Testing chapter of the previous edition. It is more focused on everyday testing needs, with more specialized topics moved out to their own dedicated chapters. It is much shorter and less daunting for the reader as a result.
  • CMake 3.27 added TIMEOUT_SIGNAL_NAME and TIMEOUT_SIGNAL_GRACE_PERIOD test properties. This chapter explains their use, including an example scenario showing how they can help with investigating flaky tests in continuous integration jobs.

Test Resources And Constraints chapter:

  • This new chapter is essentially existing material split out to its own dedicated chapter.

Build And Test Mode chapter:

  • This new chapter is also mostly existing material split out to its own dedicated chapter. The main change is the addition of a new Alternatives section which highlights how CDash scripts or workflow presets may be better alternatives, especially the latter.

Test Frameworks chapter:

  • The existing material for GoogleTest was split out to this chapter.
  • New Catch2 and doctest sections were added, showing how they follow similar setup and usage to GoogleTest (for the CMake-related aspects).

CDash Integration chapter:

  • This new chapter is essentially existing material split out to its own dedicated chapter.

Static Code Analysis chapter:

  • This new chapter contains entirely new material. It covers CMake’s support for the clang-tidy, cppcheck, cpplint, and include-what-you-use code analysis tools, along with a broader discussion of some tools’ usage. This chapter and the next are the most significant updates for this new edition.

Dynamic Code Analysis chapter:

  • This new chapter also contains entirely new material. It goes into a fair amount of detail about how to set up sanitizers and code coverage. Along with the previous chapter, this is one of the most significant updates in this new edition. A full sanitizers example is included as an appendix.

Finding Things chapter:

  • A paragraph was added to the Finding Packages section for the new <PACKAGENAME>_ROOT environment and CMake variables (uppercase versions). Support for these was added in CMake 3.27.

Installing chapter:

  • Some of the material from the Interface Properties sub-section and the Installing Exports section was moved to the new Target Property Contexts section of the Compiler And Linker Essentials chapter. The material that was left behind from the Interface Properties sub-section was absorbed into its parent Installing Project Targets section, and its examples were updated for improved consistency and continuity.

Packaging chapter:

  • The sections covering each individual package generator were moved out to their own dedicated chapter. The remaining sections now focus on packaging concepts and techniques, leaving the generator-specific aspects to that new separate chapter.
  • The discussion of the CPACK_PACKAGE_VERSION_... variables was reworded. It now highlights that CPACK_PACKAGE_VERSION is not accessible in the project’s CMakeLists.txt file.
  • The Components section has been updated and given more structure with sub-sections. It now includes a sub-section on downloadable components. Previously the downloadable component support was only discussed as part of the IFW generator. This edition corrects a long-standing error where past editions previously claimed IFW was the only generator that supported this, but NSIS and the new Inno Setup generators also support downloadable components.

Package Generators chapter:

  • This new chapter contains all the sub-sections previously found in the Package Generators section of the Packaging chapter.
  • A new section was added covering the new Inno Setup CPack generator, which was added in CMake 3.27.
  • Most of the discussion of downloadable components in the IFW generator section was moved to a sub-section of the Components section in the Packaging chapter.
  • The NSIS section was updated to mention that it supports downloadable components.

ExternalProject chapter:

  • Corrected an error in the second example of the Configuration Step section. The PDF version of the book incorrectly used CMAKE_ARGS instead of CMAKE_CACHE_ARGS in previous editions.

Presets chapter:

  • Updated the table in the High Level Structure section to account for the new version 7 presets schema added in CMake 3.27.
  • Added a note to the Test Presets section that they are useful for setting run-time options for sanitizers and code coverage. The section’s example was updated to demonstrate this.

Project Structure chapter:

  • The book’s chapters were split up into a few more parts, and one of those new parts is named Project Organization. This chapter was renamed to avoid confusion with that part name, but its content is mostly the same as the previous edition.
  • The Windows-specific Issues section was updated to mention the new CMAKE_VS_DEBUGGER_... variables added in CMake 3.27.

Working With Qt chapter:

  • The Moc sub-section was updated to discuss the new INTERFACE_AUTOMOC_MACRO_NAMES target property, including a motivating example. This property was added in CMake 3.27.
  • Updated the statement that qt_add_translations() is still in tech preview as of Qt 6.6.

Appendices:

  • A new appendix was added with a complete, working sanitizers example.

The 15th Edition has been updated for the CMake 3.26 release, although the majority of the changes actually relate to updating material for other third-party tools and packages. The main highlights for this edition include:

  • The Apple Features chapter was significantly revised and updated for Xcode 14.
  • The Working With Qt chapter was also significantly revised and updated for Qt 6.
  • Improved flow and structure in some chapters based on reader feedback.

Full details of the changes are given below.

Variables chapter:

  • The chapter underwent some reorganization to improve the flow and keep related content together. In particular, the Cache Variables section now includes the material about surprising behavior of variables and CMake GUI tools, both of which closely relate to cache variable usage. The Scope Blocks section now follows the Cache Variables section instead of interrupting the material primarily about cache variables.

Using Subdirectories chapter:

  • Improved a comment in one of the examples of the Ending Processing Early section, clarifying how return(PROPAGATE) interacts with a surrounding block().

Modules chapter:

  • Replaced mention of FindCUDA with FindCUDAToolkit, since FindCUDA has been deprecated since CMake 3.10.

Debugging And Diagnostics chapter:

  • CMake 3.26 added a new configure log, replacing the CMakeOutput.log and CMakeError.log files, and providing an improved ability to check the steps performed during a CMake configure step.
  • The Perfetto performance tracing tool (https://ui.perfetto.dev) is now mentioned, which is the modern replacement for the legacy about:tracing tool built into some web browsers.

Compiler And Linker Essentials chapter:

  • Briefly mention the new $<BUILD_LOCAL_INTERFACE:...> generator expression added in CMake 3.26.

Custom Tasks chapter:

  • Added discussion of the ENCODING option for execute_process(). Also added a missing note that the RESULTS_VARIABLE requires CMake 3.10 or later.
  • COMMAND_ERROR_IS_FATAL is now used to simplify the archiver.cmake example in the Combining The Difference Approaches section.
  • Updated the guidance in the Recommended Practices section for a number of cases:
    • When to use COMMENT or cmake -E echo in custom commands.
    • Mention using BYPRODUCTS for intermediate files in add_custom_output().
    • Mention using COMMAND_ERROR_IS_FATAL as an alternative way of checking that an execute_process() call was successful.

Working With Files chapter:

  • CMake 3.26 added support for a -t option when using cmake -E copy.
  • CMake 3.26 also added a new cmake -E copy_directory_if_different subcommand.

Toolchains And Cross Compiling chapter:

  • CMake 3.26 added a new CMAKE_VS_VERSION_BUILD_NUMBER variable, available when using a Visual Studio toolchain.

Apple Features chapter:

  • This chapter was significantly revised and updated for Xcode 14. The recommended minimum CMake and Xcode versions have been updated, and some of the techniques and workarounds for much older versions have been significantly condensed or removed.
  • Some restructuring was performed to allow most of the Info.plist material to be presented together in one place, a new Info.plist Files sub-section under Build Settings.
  • The new XCODE_EMBED_EXTENSIONKIT_EXTENSIONS... target properties added by CMake 3.26 are mentioned. The Embedding Frameworks section of the previous edition was renamed to Embedding Frameworks, Plugins And Extensions to more accurately reflect that it covers all supported XCODE_EMBED_... properties.

Installing chapter:

  • Explain the purpose and usage of the new $<BUILD_LOCAL_INTERFACE:...> generator expression added in CMake 3.26.

ExternalProject chapter:

  • CMake 3.26 added support for a new INSTALL_BYPRODUCTS keyword for ExternalProject_Add(). This is an alternative to the existing BUILD_BYPRODUCTS keyword, allowing more accurate and granular dependencies to be specified.

FetchContent chapter:

  • Added sub-headings to the Other Uses For FetchContent section to provide a clearer structure.
  • Expanded the discussion of sharing toolchain files from a separate repository. An example was added to show how to structure the separate toolchains repository’s CMakeLists.txt to provide some simple smoke tests.

Making Projects Consumable chapter:

  • Removed stray closing parenthesis from the end of the first example in Use Project-specific Names section.

Project Organization chapter:

  • Mention that CMake 3.26 added policy CMP0143, which sets the USE_FOLDERS global property to true by default.
  • Fixed wrong target property name for specifying the compile PDB (should be COMPILE_PDB_NAME and COMPILE_PDB_NAME_<CONFIG>, not COMPILE_PDB and COMPILE_PDB_<CONFIG>).
  • Mention that using a compile PDB typically defeats compiler caching, so they are usually something to be avoided.

Build Performance chapter:

  • Added discussion of how /Z... and -Z... forms of compiler flags for Visual Studio compilers are equivalent, but the -Z... form is generally preferred. Also highlight that using -Z7 doesn’t prevent a PDB file being generated for executables and shared libraries (that is controlled by a linker option).

Working With Qt chapter:

  • This chapter was significantly revised and updated to focus on Qt 6. A significantly improved CMake API is available with Qt 6, and the way CMake targets and files are handled has changed considerably. Resource handling, translations and deployment all underwent substantial revision for this update.

The 14th Edition has been updated for the CMake 3.25 release. Main highlights for this edition include:

  • A new compiler abstraction for MSVC debug information formats.
  • Expanded support for system header search paths.
  • Expanded scope control with a new block() command and new return() capabilities.
  • Support for validators in most of the find_...() commands.
  • New package and workflow preset types.

Full details of the changes are given below.

Variables chapter:

  • CMake 3.25 added a new block() command, which can be used to define a new scope for variables (and policies). A new Scope Blocks section was added to cover the new functionality.

Flow Control chapter:

  • The Interrupting Loops subsection was extended to cover the behavior of break() and continue() when called inside a local scope defined by block() commands.

Using Subdirectories chapter:

  • The add_subdirectory() command gained a new SYSTEM keyword in CMake 3.25.
  • In the Scope subsection, the explanation of the scope-related effects when adding a subdirectory has been tweaked. It is now more technically accurate and a bit simpler.
  • The return() command gained support for a PROPAGATE keyword in CMake 3.25. The Ending Processing Early section has been extended to cover this new keyword, including its interaction with the block() command also added in CMake 3.25.

Functions And Macros chapter:

  • The Scope section was renamed to Returning Values, and separate subsections were added for Returning Values From Functions and Returning Values From Macros. These extend the previous content by covering the new PROPAGATE keyword for the return() command and interaction with the block() command.

Policies chapter:

  • The Policy Scope section was updated to cover the new block() command added in CMake 3.25. This command can define a new policy scope more robustly than using the manual cmake_policy(PUSH) / cmake_policy(POP) pattern. A new example also compares the two methods and highlights why the old method is more fragile.
  • The Recommended Practices section was updated to prefer using the block() command instead of the old manual push/pop pattern.

Debugging And Diagnostics chapter:

  • CMake 3.25 gained support for obtaining the current active message logging level using a new cmake_language(GET_MESSAGE_LOG_LEVEL) subcommand. The Log Levels subsection was extended to cover this, including an example for a common usage scenario.

Build Type chapter:

  • Updated the text and examples to only modify CMAKE_CONFIGURATION_TYPES or CMAKE_BUILD_TYPE in the top level CMakeLists.txt file. It is not safe to modify these in any other directory scope for some CMake generators.

Compiler And Linker Essentials chapter:

  • A new compiler abstraction was added in CMake 3.25 for selecting the debug information format with the MSVC toolchain. A new MSVC_DEBUG_INFORMATION_FORMAT target property and associated CMAKE_MSVC_DEBUG_INFORMATION_FORMAT variable can be used to select the format instead of having to work directly with the corresponding flags (/Z7, /Zi and /ZI). Policy CMP0141 was added to provide backward compatibility for code not aware of the new abstraction.
  • CMake 3.25 added a number of new properties related to how header search paths may be treated as “system”. A new System Header Search Paths subsection was added to the Compiler Option Abstractions section, which was in turn moved to later in the chapter. The new subsection covers the new SYSTEM target and directory properties, the new EXPORT_NO_SYSTEM target property, and the deprecation of the IMPORTED_NO_SYSTEM target property. Key CMake and toolchain versions where system-related support was extended is now also explicitly stated.
  • Added advice to the Recommended Practices section to avoid using the SYSTEM keyword with target_include_directories() or include_directories() for paths that are not outside the project.

Language Requirements chapter:

  • Updated the details for CXX_STANDARD to mention that 26 is now a supported value as of CMake 3.25, even though CMake does not yet support C++26 for any of the toolchains it currently knows about.

Toolchains And Cross Compiling chapter:

  • The Tool Selection section now uses -T ClangCL rather than -T llvm in its examples. The llvm toolset is from the no longer maintained LLVM Visual Studio extension. The ClangCL toolset is part of Visual Studio built-in LLVM distribution and is the recommended toolset for using clang-based compilers on Windows with VS2019 or later.

Apple Features chapter:

  • The XCODE_SCHEME_... properties and CMAKE_XCODE_SCHEME_... variables are now mentioned (very briefly).

Finding Things chapter:

  • CMake 3.25 added support for a new VALIDATOR keyword in the find_file(), find_path(), find_program() and find_library() commands. The new keyword provides more precise and customizable control over whether these commands accept a particular candidate during their search. More extended validator examples are provided for find_file() and find_library(), including a way to potentially distinguish between a static library and an import library for a DLL on Windows (not previously possible with CMake 3.24 or earlier).
  • CMake 3.25 added <prefix>/<packageName>*/(cmake|CMake)/<packageName>*/ as a new search path for find_package().

Testing chapter:

  • The gtest_discover_tests() command has supported a XML_OUTPUT_DIR keyword since CMake 3.18, but earlier editions did not mention it. This omission has been addressed and the keyword is now discussed.

Packaging chapter:

  • CMake 3.25 added support for a new CPACK_ARCHIVE_FILE_EXTENSION variable. It can be used to customize the extension of generated package archives produced by CPack.
  • A note was added for the productbuild generator to highlight a long-standing bug which can result in empty packages being produced. A simple workaround is given for avoiding that bug.

FetchContent chapter:

  • FetchContent_Declare() gained support for a new SYSTEM keyword in CMake 3.25. This is part of the expanded support for “system” header search paths and will apply to subdirectories added by FetchContent_MakeAvailable().
  • In the Other Uses For FetchContent section, the JoeSmithUtilsSetup example contained an error. It used a macro with ${CMAKE_CURRENT_LIST_DIR} instead of a function with ${CMAKE_CURRENT_FUNCTION_LIST_DIR} when extending CMAKE_MODULE_PATH. The example has now been fixed and extended further to explicitly show how to use the function.

Presets chapter:

  • CMake 3.25 added two new preset types: package and workflow. New sections have been added to cover both.

Project Organization chapter:

  • The discussion of the superbuild structure has been extended slightly, providing an additional example showing how to use CMAKE_PREFIX_PATH to share a common base install location between dependencies.
  • The 13th Edition updated the advice around how/where to bring dependencies into a non-superbuild arrangement, but some conflicting wording remained. The text has been updated again to remove the inconsistencies and ensure the new advice is clearer.

Build Performance chapter:

  • include_file_ctime is now also mentioned in the discussion of the CCACHE_SLOPPINESS environment variable.
  • Following recently added content in the Ccache documentation, the -fno-pch-timestamp flag is now recommended when using clang with Ccache 4.0 or later.
  • The MSVC-specific code example was updated to handle the CMAKE_MSVC_DEBUG_INFORMATION_FORMAT variable, if it is defined.

Appendix B: Full Compiler Cache Example:

  • The example code now adds the -fno-pch-timestamp flag if using clang.
  • Both the /Zx and -Zx forms of the debug information format flags are now handled, not just the former.
  • The CMAKE_MSVC_DEBUG_INFORMATION_FORMAT variable is handled appropriately, if defined.
  • If using a Visual Studio generator, the example no longer assumes the C language is enabled. It now only requires that at least one of C or C++ is enabled.
 

The 13th Edition has been updated for the CMake 3.24 release. This is by far the largest update yet. A number of new chapters have been added: Advanced Linking, Making Projects Consumable and Dependency Providers. The External Content chapter was also split into two, since the FetchContent material grew significantly and became its own separate chapter. A major new feature covered in this edition is the integration between find_package() and the FetchContent module. The material on Ccache has also been updated for the recently added support for the Visual Studio toolchain. As usual, a variety of smaller updates and clarifications have been made as well. Full details of the changes are given below.

 

Flow Control chapter:

  • CMake 3.24 added a new PATH_EQUAL operator for the if() command. It is similar to STREQUAL but handles repeated path separators.
  • Added an example for if(IN_LIST) and highlight that policy CMP0057 must be set to NEW in order to use it.

Functions And Macros chapter:

  • Added explanation for how to robustly forward arguments in a macro command where list flattening isn’t a concern. This will be relevant for some dependency provider implementations (a new feature in CMake 3.24).

Generator Expressions chapter:

  • CMake 3.24 added new $<PATH:...> and $<PATH_EQUAL:...> generator expressions. These are essentially the generator expression equivalents of the cmake_path() sub-commands.

Debugging And Diagnostics chapter:

  • CMake 3.24 gained support for enabling color diagnostics in the output of the build tool and compiler. This is controlled by a new CMAKE_COLOR_DIAGNOSTICS CMake variable and a corresponding environment variable of the same name. These replace the old CMAKE_COLOR_MAKEFILE variable which enabled colorised output for just the make build tool.
  • The new cmake --fresh option can be used with CMake 3.24 or later to discard the cache from any previous run in the same build directory.

Compiler And Linker Essentials chapter:

  • A new section on compiler option abstractions was added.
    • One subsection covers turning compiler warnings into errors with the COMPILE_WARNING_AS_ERROR target property and its associated CMAKE_COMPILE_WARNING_AS_ERROR variable. These are new features in CMake 3.24. Later parts of the chapter were also updated to no longer use -Werror in any examples.
    • Another subsection covers how to specify the Visual Studio runtime library with the MSVC_RUNTIME_LIBRARY target property and its associated CMAKE_MSVC_RUNTIME_LIBRARY variable. These have been supported since CMake 3.15.
  • The De-duplicating Options section previously made an incorrect statement that LINKER:... arguments could be de-duplicated. This is not correct, as expansion of LINKER:... items occurs after de-duplication. The text and examples have been updated accordingly.
  • The Advanced Linking Relationships section was moved out to its own separate Advanced Linking chapter.
  • Added advice to the Recommended Practices section to avoid hard-coding turning compiler warnings into errors.

Advanced Linking chapter:

This is a new chapter for the 13th Edition.

  • The Advanced Linking Relationships section of the previous chapter was moved to this chapter as the Require Targets For Linking section.
  • A new section covers the new $<LINK_GROUP:...> and $<LINK_LIBRARY:...> generator expressions added in CMake 3.24. These provide features like grouping libraries on the linker command line for rescanning for unresolved symbols, indicating that all symbols of a static library should be retained (i.e. the behavior of flags like /WHOLEARCHIVE and --whole-archive), robustly identifying an Apple framework and other Apple-specific linker capabilities.
  • Another new section covers the new INTERFACE_LINK_LIBRARIES_DIRECT target property added in CMake 3.24. It includes a detailed discussion of how to use that property to robustly implement the link seaming technique.

Language Requirements chapter:

  • Fixed an example in the Detection And Use Of Optional Language Features section where -D prefixes were incorrectly included in arguments passed to target_compile_definitions(). Such prefixes are not stripped when part of a generator expression.

Custom Tasks chapter:

  • Starting with CMake 3.24, execute_process() no longer sets the CC and CXX environment variables on the first run. That behavior existed with CMake 3.23 and earlier, but was undocumented. It could lead to different behavior between the first and subsequent runs, causing subtle and hard-to-trace issues if you didn’t know about that behavior. Policy CMP0132 provides backward compatibility. The discussion at the end of the Configure Time Tasks section has been updated to highlight these changes, along with a workaround for when using CMake 3.23 or earlier.
  • An example in the Combining The Different Approaches section previously used cmake_minimum_required(VERSION 3.0), but the example actually used features from CMake 3.17. The example has been updated to use cmake_minimum_required(VERSION 3.17) instead.

Working With Files chapter:

  • CMake 3.24 extended file(DOWNLOAD) to support downloading only part of a file.

Libraries chapter:

  • The discussion in Mixing Static And Shared Libraries about using “whole archive” linker flags was updated to mention the $<LINK_LIBRARY:WHOLE_ARCHIVE,...> generator expression, available starting with CMake 3.24.

Apple Features chapter:

  • CMake 3.24 added support for *.xcconfig files with the Xcode generator. A new CMAKE_XCODE_XCCONFIG variable can be used to specify files to apply globally, while a new XCODE_XCCONFIG target property supports files defining target-specific settings. These features may be useful for projects transitioning to CMake from an exclusively Xcode-only arrangement where *.xcconfig files are commonly used.
  • The Linking Frameworks section was updated to mention the new $<LINK_LIBRARY:FRAMEWORK,...> generator expression available starting with CMake 3.24.

Finding Things chapter:

  • Various places have been updated to cross-reference other chapters that discuss new features added in CMake 3.24 which integrate with find_package().
  • All the find_...() commands gained new REGISTRY_VIEW and NO_CMAKE_INSTALL_PREFIX keywords in CMake 3.24, along with an associated CMAKE_FIND_USE_INSTALL_PREFIX variable.
  • CMake 3.24 added a new GLOBAL keyword for find_package(). When the GLOBAL keyword is present, imported targets created as part of that call will have global visibility (they are normally created with visibility in only the current directory scope and below). A CMAKE_FIND_PACKAGE_TARGETS_GLOBAL variable was also added as a way to change the default behavior.
  • A new search location for find_package() was added in CMake 3.24. This location is given by the new read-only CMAKE_FIND_PACKAGE_REDIRECTS_DIR variable and it takes priority over all other search locations. It is used primarily for integration with the FetchContent module (new functionality in CMake 3.24). Some brief notes about this integration were added here in this chapter, with cross-references to the detailed discussions in other chapters.
  • A note was added to highlight that CMAKE_REQUIRE_FIND_PACKAGE_<packageName> can break project logic. An example of a common scenario where this would occur is given.
  • The Recommended Practices section was updated to also mention $<LINK_LIBRARY:FRAMEWORK,...> as another way to link to something by name without breaking a developer’s ability to switch between device and simulator builds when targeting Apple platforms.

Testing chapter:

  • CMake 3.24 added more granular control over the truncation of test output. A new CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION variable controls which part of the output is truncated. A new ctest --test-output-truncation option provides equivalent control for non-dashboard runs using the --output-junit option.
  • Examples using GoogleTest were updated to use the newer GTest::gtest and GTest::gtest_main targets rather than the older GTest::GTest and GTest::Main targets, which have been deprecated since CMake 3.20. A brief explanation of the situation was added to the The GoogleTest section.

Installing chapter:

  • CMake 3.24 added a new feature for verifying that headers are self-contained, meaning they don’t rely on some other header having been included first. It builds on the file sets feature added in CMake 3.23. The new CMAKE_VERIFY_INTERFACE_HEADER_SETS variable can be set to true to enable the creation of targets that carry out these checks for appropriately defined file sets. It is intended to be a developer control, not something the project sets. For projects already using file sets to install their headers, it should be a very simple step for developers to enable these checks. The new capability is covered in the File Sets section of this chapter.
  • The OUTPUT_NAME target property is now discussed in the same place where the EXPORT_NAME target property is introduced in the Installing Exports section. These two properties are related, so they should be discussed together.

Packaging chapter:

  • CMake 3.24 changed the default value of CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE, subject to the new policy CMP0133. The behavior corresponding to the old default is no longer supported by recent Xcode releases.
  • The deprecated PackageMaker package generator was completely removed in CMake 3.24.

ExternalProject chapter:

The External Content chapter of the previous edition has been split up. The FetchContent section was moved out to its own dedicated chapter. The ExternalProject sections were revised and extensively restructured to provide a more logical flow, and the chapter has been renamed to ExternalProject in recognition of the narrower focus. The ExternalData section remains as part of the ExternalProject chapter.

  • The ExternalProject_Add() command gained a new DOWNLOAD_EXTRACT_TIMESTAMP option for use with URL archive downloads. It controls whether the timestamp of extracted files is updated to the time of extraction or set to the timestamp as contained in the archive. Policy CMP0135 was also added, since the default behavior was changed in this regard.

FetchContent chapter:

This is a new chapter for the 13th Edition. The FetchContent section of the External Content chapter in the previous edition has been moved here, heavily revised and extended.

  • A major new feature was added in CMake 3.24, providing integration between find_package() and FetchContent. Dependencies requested via one method can now be transparently fulfilled by the other. Controls are provided for both the project and the developer. A substantial new section was added to this chapter covering the new features.
  • Discussion of the constraints around when FetchContent can be used for a particular dependency is now the subject of its own new chapter, Making Projects Consumable. The Restrictions section in the FetchContent chapter is now more brief, providing cross-references to the more comprehensive discussions in the other new chapter instead.
  • The discussion of the manual population pattern has mostly been removed. The chapter now focuses first and foremost on using FetchContent_MakeAvailable(), since it now has a much richer set of features than the manual population pattern can provide.

Making Projects Consumable chapter:

This is a new chapter for the 13th Edition. It provides clear and fairly comprehensive guidelines for what projects can do so that other projects can most easily consume them. The focus is on supporting the common methods consumers may use to bring the project in as a dependency, in particular as pre-built binary installs and building from source. These roughly correspond to the traditional find_package() and FetchContent scenarios. The integration between these two main methods in CMake 3.24 increases the importance of the points highlighted in this chapter. The material is combination of collecting individual points discussed elsewhere in the book, as well as some new recommendations. The guidelines are structured around a few key principles, with specific, actionable points discussed for each one.

Dependency Providers chapter:

This is another new chapter for the 13th Edition. CMake 3.24 added a significant new feature called dependency providers. These allow calls to find_package() and FetchContent_MakeAvailable() to be intercepted by a command the developer defines. That command can choose to fulfil the request in whatever way it prefers and indicate back to CMake whether it was successful, or whether to fall back to the built-in default implementation. The primary use case is for setting up package managers, but the chapter covers other use cases for this feature as well. An example showing how to use the feature to time dependency request calls is provided in an Appendix.

A new CMAKE_PROJECT_TOP_LEVEL_INCLUDES variable is also introduced, which provides a well-defined injection point for one-time setup at the top of the project. This is also the only place a dependency provider can be set.

Project Organization chapter:

  • The advice around how/where to bring dependencies into the build has changed from previous editions. With the new integration features between find_package() and FetchContent, it is now more advantageous to bring dependencies into the build in the project’s top level scope rather than in a dedicated subdirectory. The focus on using FetchContent_MakeAvailable() rather than the manual population pattern removes the main motivation for using a separate directory scope. Examples have been updated accordingly and are now much simpler. Most of the discussions about the old manual population pattern have been removed.
  • A number of examples have been simplified to use the PROJECT_IS_TOP_LEVEL variable instead of comparing CMAKE_SOURCE_DIR with CMAKE_CURRENT_SOURCE_DIR. The minimum CMake version in the examples has been updated accordingly, where needed.
  • Variables used in examples to enable or disable testing have been renamed to be project specific, bringing them into line with recommendations in the new Making Projects Consumable chapter.
  • The discussion of the OUTPUT_NAME target property was removed from the Target Outputs section, since that is now covered in the Installing Exports section of the Installing chapter. Since the material that remains all relates to the location of build outputs, the section has been renamed to Target Output Locations.
  • The Injecting Files Into Projects section was updated to mention to the new CMAKE_PROJECT_TOP_LEVEL_INCLUDES variable introduced in the Dependency Providers chapter. The discussion contrasts the different uses of the various injection variables supported by the project() command. Discussion of examples related to CI setup have been removed from this section, since that is now more appropriately done via presets or a script provided by CMAKE_PROJECT_TOP_LEVEL_INCLUDES.

Build Performance chapter:

  • A substantial new section on Build Parallelism was added. For each of the main CMake generator types, it covers how to enable parallel builds and what generator-specific controls are available. For Ninja, a detailed discussion of job pools is provided. For Visual Studio, the Multi-ToolTask scheduler is discussed, along with its relationship to the well-known /MP compiler option. CMake’s handling of the -parallelizeTargets option for xcodebuild when using the Xcode generator is also discussed. The existing Optimizing Build Dependencies was also moved under this section.
  • Discussion of Ccache was expanded to cover the recently added support for the Visual Studio toolchain on Windows, including with the Visual Studio generators. Discussion about features in much older Ccache versions has been reduced and the material has been updated to focus more on recent Cccache releases. A complete, production-ready implementation supporting all the main CMake generators is provided as an Appendix.
 

The 12th Edition has been updated for the CMake 3.23 release. A significant new feature covered in this update is the new file sets capabilities. The Compiler And Linker Essentials, Installing and Project Organization chapters all underwent substantial changes to account for the new functionality. Presets have also been given more prominence with their own dedicated chapter. As usual, a range of smaller updates and clarifications have also been made. The main changes in this edition are listed below.

Properties chapter:

  • CMake 3.23 added a new INITIALIZE_FROM_VARIABLE keyword for the define_property() command. Almost any target property (including custom properties) can now be initialized from a nominated variable when a target is created.
  • The BRIEF_DOCS and FULL_DOCS options of define_property() became optional with CMake 3.23 or later.

Compiler And Linker Essentials chapter:

  • The Target Properties section gained a Sources sub-section that introduces the SOURCES and INTERFACE_SOURCES properties.
  • The Target Property Commands sub-section was pulled up one level to improve discoverability and navigation. Sub-sections were then added for each target property command.
  • The target_sources() command is now introduced in its own sub-section under the Target Property Commands section. Previously, most of this material was found in the Project Organization chapter, but it had been harder to find and was introduced very late in the book. New features added by CMake 3.23 and covered in the Installing chapter mean it is more important to learn about target_sources() earlier.
  • Mention that target_link_libraries() could not be called on a target defined in a different directory until CMake 3.13. Previously, this wasn’t mentioned until the Project Organization chapter.
  • CMake 3.23 added support for a new IMPORTED_NO_SYSTEM target property, primarily aimed at use with imported targets. It is discussed along with the existing NO_SYSTEM_FROM_IMPORTED property as part of the explanation of the SYSTEM keyword of the target_include_directories() command.
  • A new Advanced Linking Relationships section was added to cover the new LINK_LIBRARIES_ONLY_TARGETS target property added in CMake 3.23. The new property can be used to enforce linking only against CMake targets, which can help catch project errors. An example is given for how to mask non-target libraries with a CMake target of the same name to assist with transitioning older projects to the new feature.

Target Types chapter:

  • The Interface Imported Libraries section now covers the IMPORTED_LIBNAME target property. That property is more relevant now, given its potential use with the new LINK_LIBRARIES_ONLY_TARGETS feature.

Libraries chapter:

  • The discussion about setting header search paths when using generate_export_header() now cross-references the new file sets feature added in CMake 3.23.

Apple chapter:

  • CMake 3.23 added a new XCODE_EMBED_PLUGINS target property. Mention this briefly in the existing discussion covering the other closely related XCODE_EMBED_... target properties.
  • Update the discussion about PUBLIC_HEADERS and PRIVATE_HEADERS to cross-reference the moved sub-section about them in the Installing chapter.

Finding Things chapter:

  • A new Ignoring Search Paths section was added. It expands the existing discussion about CMAKE_IGNORE_PATH and CMAKE_SYSTEM_IGNORE_PATH, covering in more detail how they affect the various find_...() commands. The section also covers the new CMAKE_IGNORE_PREFIX_PATH and CMAKE_SYSTEM_IGNORE_PREFIX_PATH variables added in CMake 3.23. The search path re-rooting of all four variables is now also covered. Guidance is given to highlight when these two new variables should be preferred over the other two existing ones, both in the new section and in the Recommended Practices section.
  • The Debugging find_…() Calls section was updated to cover the new cmake command line options --debug-find-pkg and --debug-find-var added in CMake 3.23.

Testing chapter:

  • Discussion of the ENVIRONMENT and ENVIRONMENT_MODIFICATION test properties was moved to its own dedicated Test Environment section to improve discoverability and navigation.
  • Errors in examples related to the handling of semicolons in the ENVIRONMENT test property have been corrected. Discussion in the Test Environment section was expanded to cover the subtle problems underlying those errors.
  • The Recommended Practices section was updated to recommend using the more robust ENVIRONMENT_MODIFICATION test property rather than the ENVIRONMENT property.

Installing chapter:

CMake 3.23 added a significant new feature called file sets. These provide a much stronger abstraction for associating files of a particular type with a specific target. The primary use for file sets in the 3.23 release is to associated headers with a target and install them as part of the target via install(TARGETS). A key benefit is the ability to preserve relative paths to the files from a set of base directories. Material in this chapter has been restructured to account for this significant new feature.

  • The Installing Files And Directories section of previous editions has been renamed to just Installing Files. It now has a number of sub-sections covering the different ways files can be installed.
  • A new sub-section dedicated to file sets has been added. This covers the new syntax of the target_sources() command for defining file sets, as well as the changes to install(TARGETS) for installing them as part of the target they are associated with.
  • The material covering how PUBLIC_HEADERS and PRIVATE_HEADERS can be used to install headers and how they relate to frameworks was moved out of Apple-specific Targets and into another sub-section under Installing Files. Discussion has been expanded to highlight the conventional way headers are included from frameworks and how these two properties are subject to path stripping.
  • Material covering how to install a whole directory tree of files was also moved into a new sub-section under Installing Files.
  • A new paragraph was added to the Recommended Practices section to provide guidance on how to choose between the different methods for installing headers.

Packaging chapter:

  • CMake 3.23 added a number of new variables and capabilities for the IFW generator. CPACK_IFW_PACKAGE_RUN_PROGRAM and related variables can be used to optionally run a program upon successful completion of an install. CPACK_IFW_PACKAGE_PRODUCT_IMAGES can provide a list of PNG images to show in a cycle while an installation is in progress. On macOS, CPACK_IFW_PACKAGE_SIGNING_IDENTITY can provide an identity to use for signing the installer. The Qt Installer Framework (IFW) section has been updated to discuss these new variables and capabilities.
  • CMake 3.23 also added a number of new variables and capabilities for the productbuild generator. CPACK_PRODUCTBUILD_DOMAINS and related variables now control where the installer may be allowed to install to. A key benefit of this new capability is that installers can now potentially install to a user’s home directory, which doesn’t require administrative privileges.
  • CMake 3.23 essentially deprecated the use of CPACK_RESOURCE_LICENSE_FILE with the DragNDrop generator. A new variable CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE controls whether to use or ignore CPACK_RESOURCE_LICENSE_FILE for this generator only.

Presets chapter:

  • The material covering presets was moved out of the Project Organization chapter into its own dedicated chapter. This was done to improve discoverability and navigation, and to tighten the focus of the Project Organization chapter.
  • CMake 3.23 added a new presets schema version (4). The main addition is a new include field, which enables preset files to include other files. A new ${fileDir} macro was also added to support that use case. The new Presets chapter covers these new capabilities, including their impact on preset inheritance.
  • The Configure Presets section now has sub-sections to provide better navigation.
  • The Build Presets section now mentions that the available build presets can also be obtained with the alternative command line cmake --list-presets build.
  • The Build Presets and Test Presets sections now mention the problem of combinatorial explosion of presets when they are over-used.

Project Organization chapter:

  • Some of the material from the Target Sources sub-section under Defining Targets has been moved to earlier chapters. The remaining material has a tighter focus, and the section has been renamed to Building Up A Target Across Directories.
  • Discussion and examples in the Windows-specific Issues and Recommended Practices sections were updated to address errors relating to the handling of semicolons and the ENVIRONMENT test property. The ENVIRONMENT_MODIFICATION property is now recommended and used in the examples instead.
  • The entire Presets section was moved to its own separate chapter.
 

The 11th Edition has been updated for the CMake 3.22 release. Compared to previous releases, CMake 3.22 was a relatively small update. The 11th Edition is therefore also correspondingly smaller than usual. The most significant change for this edition is a rewrite of the section covering Android. The new environment modification test property is also noteworthy. As usual, a range of smaller updates and clarifications have also been made. The main changes in this edition are listed below.

Flow Control chapter:

  • Added a note to highlight that if(ENV{some_var}) always evaluates to false.

Build Type chapter:

  • CMake 3.22 added support for initialising the build type from a CMAKE_BUILD_TYPE environment variable for single configuration generators.
  • CMake 3.22 added support for initialising the set of build types from a CMAKE_CONFIGURATION_TYPES environment variable for multi configuration generators.

Language Requirements chapter:

  • Updated and clarified the CMake versions that first supported various CUDA language standards (the CMake documentation had previously been somewhat incorrect and was also updated). CUDA 23 was also added by CMake 3.22.
  • CMake 3.22 now honours <LANG>_EXTENSIONS fully independently from <LANG>_STANDARD. In previous CMake versions, the latter had to be set for the former to have any effect. This relates to a new CMP0128 policy, which also has other effects related to setting the language standard and enabling compiler extensions.

Working With Files chapter:

  • Fixed an error in one of the earlier cmake_path() examples to do with setting the path variable from a string.

Toolchains And Cross Compiling chapter:

  • The example section for Android was lifted out to its own proper section and was almost entirely rewritten. It now focuses on using NDK r23 or later with CMake 3.21 or later. The previous discussion for earlier NDK and CMake versions has mostly been removed, apart from some historical context. The new section is more focused and easier to follow. Discussion of the unmaintained Nvidia Nsight Tegra Visual Studio Edition has also been removed.

Finding Things chapter:

  • CMake 3.22 added support for a new CMAKE_REQUIRE_FIND_PACKAGE_<packageName> variable to turn optional packages into required ones.
  • CMake 3.22 updated the FindPkgConfig module to allow passing arbitrary arguments to the pkgconfig executable.

Testing chapter:

  • CMake 3.22 added a new ENVIRONMENT_MODIFICATION test property which allows a test’s environment variables to be modified at test time instead of only being able to specify values based on details available at configure time.
  • With CMake 3.22, tests can now add test labels dynamically by including appropriate tags in the test output. These are made available in CDash dashboard results.
  • Memcheck dashboard steps now also submit their test results to CDash (new behavior in CMake 3.22, previously those test results were lost and only the memory check results were submitted).
  • The gtest_discover_tests() command now supports a new TEST_FILTER keyword which can be used to filter the set of discovered tests (new in CMake 3.22).

Installing chapter:

  • Added a recommended practice related to the support for a new CMAKE_INSTALL_MODE environment variable added in CMake 3.22.

Packaging chapter:

  • CMake 3.22 added a new CPACK_NSIS_IGNORE_LICENSE_PAGE variable to turn off the license page in NSIS installers.

Working With Qt chapter:

  • Added some very brief comments regarding Qt 6, but the chapter still focuses predominantly on Qt 5.
 

The 10th Edition has been updated for the CMake 3.21 release. The more substantial changes for this edition include new sections on installing runtime dependencies and new output control capabilities for ctest (e.g. JUnit, per-test measurements and attachments). As usual, a range of smaller updates and clarifications have also been made. The main changes in this edition are listed below.

NOTE: As foreshadowed in the previous release, the MOBI format is no longer provided. The kindlegen tool used to create it previously was withdrawn from public distribution last year and Amazon has officially dropped support for creating reflowable MOBI files. The EPUB format continues to be provided.

Variables chapter:

  • CMake 3.21 improved the behavior of the set() command such that it no longer discards a non-cache variable of the same name when setting a cache variable. This makes it more consistent with similar changes made to the option() command in CMake 3.13. Special cases are noted.

Flow Control chapter:

  • Corrected a minor error. The if(...IN_LIST...) command was added in CMake 3.3, not 3.5 as previously claimed.

Using Subdirectories chapter:

  • CMake 3.21 added a new PROJECT_IS_TOP_LEVEL variable, along with related project-specific variables.

Language Requirements chapter:

  • CMake 3.21 added support for specifying C17 and C23 by setting CMAKE_C_STANDARD to 17 or 23 respectively.

Custom Tasks chapter:

  • CMake 3.21 extended add_custom_command() to add DEPFILE support for Xcode and Visual Studio.

Working With Files chapter:

  • CMake 3.21 added a new file(COPY_FILE) subcommand, intended to provide a simpler, more familiar syntax for more common basic file copy operations.
  • CMake 3.21 added a new EXPAND_TILDE option for the file(REAL_PATH) sub-command.
  • CMake 3.21 added new RESULT and NO_REPLACE options for the file(RENAME) sub-command. It is now possible to detect when the operation fails and provide alternative behavior instead of CMake halting with a fatal error.
  • Material relating to renaming files and making directories was re-ordered to improve the logical flow.

Toolchains And Cross Compiling chapter:

  • CMake 3.21 added a new --toolchain option for the cmake command. This is a convenience and is equivalent to setting the CMAKE_TOOLCHAIN_FILE cache variable. Support for a CMAKE_TOOLCHAIN_FILE environment variable was also added.
  • Some minor corrections were added for when toolchain files could be re-read during a configure run.

Apple Features chapter:

  • Added a brief note for the new XCODE_EMBED_APP_EXTENSIONS target properties added in CMake 3.21, mostly just to raise awareness.

Finding Things chapter:

  • find_file(), find_path(), find_library() and find_program() gained a new NO_CACHE option in CMake 3.21. The behavior of these commands also changed with regard to when a non-cache result variable already exists at the time of the call. Implications of both are discussed.

Testing chapter:

  • Embedding <DartMeasurement> and <DartMeasurementFile> tags in test output is now officially documented as of CMake 3.21. Material related to this has been updated, including the newly documented (but still always supported) BaselineImage as a synonym for ValidImage measurement type.
  • CMake 3.21 added the ability to attach arbitrary files to a test using <DartMeasurementFile>, not just images. Previously, this resulted in files that were not accessible from CDash, but it now works and is officially documented.
  • CMake 3.21 now supports overriding the Details field of a test by including a <CTestDetails> tag in its results.
  • A new Output Control section was added to this chapter. The new section covers how to use the new JUnit XML format output functionality added in CMake 3.21. It also discusses variables that can be used to override the limits on how much test output is recorded in the CDash and JUnit results.

Installing chapter:

  • CMake 3.21 added some significant capabilities associated with installing runtime dependencies of targets. New options were added to the install(TARGETS) command and two new install() subcommands were also added. The book contains two new sections, Installing Imported Targets and Runtime Dependency Sets which discuss the new capabilities.
  • Advice on choosing between the different methods (old and new) for installing runtime dependencies has been updated.
  • The install(SCRIPT) and install(CODE) sub-commands gained a new ALL_COMPONENTS keyword in CMake 3.21.
  • One of the main examples in the Config Files For CMake Projects section was expanded to demonstrate how to safely handle the use of if(...IN_LIST...) in config files when processed by an older version of CMake that doesn’t supported it.

Packaging chapter:

  • CMake 3.21 added the ability to use component and group names containing hyphens when using cpack wth QtIFW 3.1 or later.
  • The .dmg file system type can now be specified for the DragNDrop CPack generator using a new CPACK_DMG_FILESYSTEM variable.

Project Organization chapter:

  • Presets gained a new version 3 schema in CMake 3.21, expanding the capabilities of the previous schema version. Some of the more significant changes include the binaryDir and generator no longer being compulsory for configure presets and the ability to enable a preset only if certain conditions are met (e.g. the host platform matches a given string). The Presets section was expanded to cover the more important new features, with examples.

Index:

  • The index was expanded to cover individual sub-commands for some of the more complex built-in commands. This includes cmake_language(), file(), install(), list() and string().
 

The 9th Edition has been updated for the CMake 3.20 release. The more substantial changes for this edition include support for embedding frameworks with the Xcode generator, a new cmake_path() command for general path manipulation, extension of the presets feature to support build and test presets, and removal of material related to the now deprecated TestBigEndian and WriteCompilerDetectionHeader modules. A collection of smaller updates and clarifications have also been made. The main changes in this edition are listed below.

NOTE: This is the last edition for which the MOBI format will be provided. The kindlegen tool used to create it thus far was withdrawn from public distribution last year and Amazon is officially dropping support for creating MOBI files altogether in June 2021. The EPUB format will continue to be made available.

Flow Control chapter:

  • The discussion of how if(IS_NEWER_THAN) can be misleading has been expanded and examples have been added.

Modules chapter:

  • CMake 3.20 deprecated the TestBigEndian module. The corresponding Endianness section has been removed from this chapter and the Recommended Practices section was updated to mention the new CMAKE_<LANG>_BYTE_ORDER variable that replaces it.

Compiler And Linker Essentials chapter:

  • CMake 3.20 added a new AFTER keyword to the target_include_directories() command (mostly for symmetry, since AFTER is already the default behavior).

Language Requirements chapter:

  • CMake 3.20 added support for specifying C++23 by setting CMAKE_CXX_STANDARD to 23.
  • Added more precise details for which CMake releases added support for which CUDA versions.
  • CMake 3.20 deprecated the WriteCompilerDetectionHeader module. The corresponding discussion of that module in the Detection And Use Of Optional Language Features section has been removed and replaced by a brief note about the deprecation. The Recommended Practices section was also updated to advise more strongly not to use the module.

Custom Tasks chapter:

  • CMake 3.20 added limited support for generator expressions in the OUTPUT and BYPRODUCT arguments of add_custom_command() and add_custom_target().
  • CMake 3.20 expanded depfile support in add_custom_command() to include Makefile generators (previously only Ninja generators were supported). A new associated policy CMP0116 was also added, but it leads to noisy warnings in potentially harmless situations. An explanation of the cause of those warnings and how to avoid them has been added.

Working With Files chapter:

  • CMake 3.20 added a new cmake_path() command. The Manipulating Paths section has been updated to introduce the new command and present some common uses. Its relationship to the existing get_filename_component() and file() sub-commands is also highlighted.
  • The Recommended Practices section now recommends preferring the new cmake_path() command. It also highlights some subtle differences in behavior compared to the if(IS_ABSOLUTE) command.
  • CMake 3.20 expanded the control of permissions for configure_file() and file(GENERATE) such that they both now both support the same NO_PERMISSIONS, USE_SOURCE_PERMISSIONS and FILE_PERMISSIONS keywords as the file(COPY) sub-command.

Toolchains And Cross Compiling chapter:

  • CMake 3.20 added hooks and fixes needed for the Android NDK to drive CMake’s built-in Android support reliably, with corresponding updates expected in the upcoming NDK r23 release. The Android note in the Examples section regarding the status of this work and corresponding advice in the Recommended Practices section have been updated accordingly, but the rest of the content still largely reflects the old approach.

Apple Features chapter:

  • Discussion of the XCODE_LINK_BUILD_PHASE_MODE target property in the Linking Frameworks section was expanded to explain the supported options and their effect.
  • A long-standing deficiency in CMake’s install name handling would leave iOS apps using embedded shared libraries unable to run. That bug was fixed in CMake 3.20.1. A note has been added to the end of the Linking Frameworks section to draw attention to that bug and it being fixed.
  • CMake 3.20 added direct support for embedding frameworks into app bundles when using the Xcode generator. The Embedding Frameworks section was updated to cover the new capabilities. The old approach is still presented as a workaround for those who need to remain on an older CMake version for the time being. The Limitations and Recommended Practices sections have also been updated in recognition of the new features.
  • Wording around the CMAKE_APPLE_SILICON_PROCESSOR variable has been tightened to make it clear that it has to be a cache variable, not just any variable.

Testing chapter:

  • In CMake 3.20, the ctest command gained a new --test-dir option for specifying the directory for which tests should be run (instead of assuming the current directory).
  • The Defining And Executing A Simple Test section had been incorrectly stating that ctest supported -VVV as an “extra verbose” command line option. The erroneous text has been corrected.

Installing chapter:

  • CMake 3.20 added support for directly rewriting RPATH details for the XCOFF binary format on AIX.
  • A note was added to the Apple-specific Targets sub-section to draw attention to the long-standing bug in CMake’s install name handling, which was fixed in CMake 3.20.1 (this is the more detailed description of the same problem noted briefly in the Apple Features chapter).
  • Added a brief comment in the Apple-specific Targets sub-section to state the equivalent RPATH target property values for iOS when describing the relationship between executables and their embedded frameworks. Previously, only the values for macOS were given.
  • Updated the RPATH example for an app bundle with embedded frameworks to link directly to its frameworks instead of using the form -framework XXX. This simplification takes advantage of improvements made in CMake 3.19.

Packaging chapter:

  • Added brief note that cpack_ifw_configure_component() and cpack_ifw_configure_component_group() accept DEPENDENCIES as a synonym for DEPENDS.
  • Added discussion explaining how to set a version requirement on a DEPENDS value passed to cpack_ifw_configure_component().
  • Updated comments about QtIFW to note that it now supports unattended command-line installs since QtIFW 4.0.
  • CMake 3.20 added support for modifying the branding text in NSIS installers. A brief comment was added to mention the new variables used to control this behavior.
  • CMake 3.20 expanded the configuration variables supported by the NuGet installer. The text was updated to briefly mention the type of capabilities that were added.

External Content chapter:

  • Corrected an existing discussion to make clear that when using ExternalProject_Add(), if the requested GIT_TAG was an actual tag and was already checked out, the command would not fetch from the remote to check if the tag had moved.
  • Fixed typo where ExternalProject_Add_Step() was incorrectly written as External_Project_Add_Step().

Project Organization chapter:

  • CMake 3.20 now allows target_sources() to be used with custom targets. The Target Sources sub-section has been updated accordingly.
  • CMake 3.20 extended the existing configure presets to support build and test presets as well. The Presets section has been updated to account for the new capabilities, generalise some of the discussions and provide an example for each new type of preset.

Build Performance chapter:

  • CMake 3.20 added a new UNITY_BUILD_UNIQUE_ID target property. A brief note was added to mention its intended use to raise awareness, but the added text advises to prefer to rework the code to avoid the need for it.

Working With Qt chapter:

  • Updated the note regarding back-porting of the cleandead fix in CMake 3.19.2 for a Ninja-related bug. The fix was ultimately not back-ported to CMake 3.17, only to 3.18.
 

The 8th Edition has been updated for the CMake 3.19 release. It includes new and updated material. Major highlights for this edition include support for Xcode’s new build system and Apple Silicon, along with a range of other linking-related improvements for Apple frameworks. A significant new feature called presets was added in CMake 3.19, as was another new feature allowing deferred execution of CMake code at the end of a directory scope. The following lists the main changes in this edition.

Variables chapter:

  • Improved the message labelling in the unbalanced square brackets example so that the sample output is clearer.
  • Mentioned briefly that the string() command now provides some JSON handling, but no detail beyond that is given in this edition.

Functions And Macros chapter:

  • CMake 3.19 added a new set of cmake_language(DEFER) subcommands. These can be used to define arbitrary CMake code to be executed at some later time.
  • Expanded the Special Cases For Argument Expansion subsection to account for the new cmake_language(DEFER) subcommands. Further sub-headings were also added to improve structure and navigation in this subsection.

Modules chapter:

  • Replace use of CMAKE_SOURCE_DIR with CMAKE_CURRENT_SOURCE_DIR in the CMAKE_MODULE_PATH example. This now follows the advice in other parts of the book regarding these variables.
  • CMake 3.19 added a new CheckSourceCompiles module, intended as a more generic replacement for the individual Check<LANG>SourceCompiles modules.
  • CMake 3.19 added a new CheckSourceRuns module, intended as a more generic replacement for the individual Check<LANG>SourceRuns modules.
  • CMake 3.19 added a new CheckCompilerFlag module, intended as a more generic replacement for the individual Check<LANG>CompilerFlag modules.

Debugging And Diagnostics chapter:

  • Clarified the descriptions of the NOTICE and STATUS log levels to make it clearer which one is the default when no log level is specified. A corresponding comment in the Recommended Practices section was also updated to remove an ambiguity in what a default log level meant.
  • Added reasoning for why one should generally prefer STATUS over NOTICE for informational messages.

Build Type chapter:

  • Added a note that when using Visual Studio compilers with single configuration generators (e.g. Ninja or NMake Makefiles), the default build type is Debug rather than an empty string.

Compiler And Linker Essentials chapter:

  • Added comments highlighting which target properties relating to compiler and linker options are subject to automatic de-duplication by CMake.
  • Added a new De-duplicating Options section. It presents scenarios where de-duplication needs to be prevented and shows how to use the SHELL: prefix to achieve that.
  • Earlier editions listed common mistakes made with variables under bold headings. These were promoted to proper sub-subheadings in this edition so that they show up in the table of contents and improve ease of navigation.

Target Types chapter:

  • A brief note about BUILD_SHARED_LIBS was added to the Libraries section to reiterate its use to select between STATIC and SHARED libraries when no library type is specified.
  • Subsections were added to the Libraries section to make finding information about some of the less common library types more discoverable.
  • CMake 3.19 added the ability to add private sources to interface libraries. Material has been added which highlights the restrictions this removes, using header-only libraries as a use case.
  • Made the note about propagation of an object library’s own link dependencies more prominent (it is not safe to rely on before CMake 3.14).
  • Fixed a wrong reference in the library alias example about linking to namespaced names. The reference was moved to a callout and is now an actual link to the Finding Things chapter.

Custom Tasks chapter:

  • CMake 3.19 relaxed some of the automatic dependency creation around some $<TARGET_...> generator expressions when they were used in custom commands. This is protected by the new policy CMP0112.
  • The execute_process() command gained a new COMMAND_ERROR_IS_FATAL keyword in CMake 3.19. This can remove the need to manually check the result of such calls, thereby making the code much more concise. The material added to the book also highlights that this new feature initially had some overlooked error cases in the 3.19.0 release, but that these were fixed in CMake 3.19.2.

Working With Files chapter:

  • CMake 3.19 added the file(REAL_PATH) subcommand. Material has been added about this, including a discussion about the inconsistencies it brings compared to the existing get_filename_component() command.
  • CMake 3.19 added the NO_SOURCE_PERMISSIONS keyword to the configure_file() command.
  • CMake 3.19 added the TARGET keyword to the file(GENERATE) subcommand. It can be used to provide a target for the evaluation of generator expressions that require a target for evaluation, such as $<TARGET_PROPERTY:...>.
  • CMake 3.19 added the file(CHMOD) and file(CHMOD_RECURSE) subcommands for manipulating file and directory permissions.
  • CMake 3.19 now allows the file name given to file(DOWNLOAD) to be omitted. This will discard the downloaded file, which can be useful if you just want to check that it can be downloaded without actually saving it anywhere.

Toolchains And Cross Compiling chapter:

  • CMake 3.19 now allows CMAKE_<LANG>_COMPILER to be a list rather than just a single executable. Mandatory arguments can now be included in the list.
  • Mentioned that CMake 3.19 now allows the Android NDK to be used with the Visual Studio generator.

Apple Features chapter:

CMake 3.19 included a significant amount of work for Apple platforms. Much of this is not directly user-visible, but the features enabled by that work are significant.

  • CMake 3.19 now supports Xcode’s new build system, but only for Xcode 12 or later. The new build system is used by default when using Xcode 12, so this change is mostly transparent to the developer.
  • Support for Xcode’s new build system in turn allowed support for Apple Silicon to be added. CMake 3.19.2 and Xcode 12.2 should be considered the minimum versions for targeting Apple Silicon, which is noted in the updated material in the book.
  • Updated the Universal Binaries section and added a new Intel And Apple Silicon Binaries subsection to it, explaining how to create universal binaries for macOS. This includes comments regarding how CMake itself being a universal binary may also affect the build.
  • Added a note to the Combined Device And Simulator Binaries section regarding an extra step that may be needed if building iOS universal binaries on an Apple Silicon host.
  • Updated the advice in the Compiler Test Workarounds subsection to note that CMAKE_XCODE_ATTRIBUTE_CODE_SIGNING_ALLOWED no longer has to be manually set in try_compile() calls as of CMake 3.18.2.
  • The Linking And Embedding Frameworks section was split into two separate sections, each covering one of these areas. The Linking Frameworks section was expanded to cover changes in behavior with CMake 3.19 which make linking frameworks work more seamlessly by default, especially for archive operations. The existing content of this section was also reworked in places to make it more complete and to improve the discussion flow. CMake 3.19’s new functionality relating to using Xcode’s Link Binaries With Libraries build phase is also discussed.
  • The Limitations section was also updated to account for the improved framework linking with CMake 3.19.
  • Minor changes were made to the Recommended Practices section to account for the changes mentioned above.
  • Added a note that the names for an Xcode project’s build settings can also be shown using the Editor > Show Setting Names menu item.
  • Fixed an example in the Deployment Target section where CMAKE_OSX_DEPLOYMENT_TARGET was erroneously being created as a regular variable instead of a cache variable.
  • Fixed a typo in an iOS example where Apple Developer was used for the code signing identity instead of Apple Development.

Finding Things chapter:

  • CMake 3.19 now supports specifying version ranges in the version requirements given to find_package().

Testing chapter:

  • CMake 3.19 allows test names to contain spaces, quotes and other special characters. The book notes the history of this support, as it was originally added in 3.18, but then withdrawn after it was found to break existing projects. CMake 3.19 reintroduced it again, this time with a policy.
  • Sections of the book relating to CDash were updated to use the terminology groups rather than tracks. CMake 3.16 deprecated the --track option in favor of a new --group option.
  • CMake 3.19 added support for a new MemCheck type, Cuda Sanitizer.

Installing chapter:

  • Updated the Config Files For CMake Projects section to account for CMake 3.19’s new support for version ranges in calls to find_package(). The set of variables provided to package version files has been expanded considerably.

External Content chapter:

  • CMake 3.19 added the INDEPENDENT keyword to the ExternalProject_Add_Step() command as part of the work to support Xcode’s new build system. A discussion of what the keyword does and why one might want to use it is provided.
  • Related to the preceding point, CMake 3.19 deprecated the NO_DEPENDS keyword to ExternalProject_Add_StepTargets().
  • The CompanyXToolchains example for FetchContent was updated to use FetchContent_MakeAvailable(), making it more concise.

Project Organization chapter:

  • CMake 3.19 added a significant new feature called presets. These provide a convenient new way of configuring the first CMake run in a build directory with prepared settings. These are useful in a number of different scenarios. A new Presets section has been added to cover the most important aspects of this new functionality.
  • The Recommended Practices section was updated to mention the VS_DEBUGGER_ENVIRONMENT target property as a better way of improving the debugger experience within the Visual Studio IDE. Previously, it mentioned the older VS_USER_PROPS target property, but this was not updated in an earlier edition of the book when discussion of the VS_DEBUGGER_ENVIRONMENT property was introduced elsewhere.

Build Performance chapter:

  • Added a note to the Alternative Linkers section regarding a bug in lld which may affect developers using the Android NDK.
  • CMake 3.19 added a new ability to relax dependencies of static and object libraries in certain situations. This can potentially reduce rebuilds or improve build parallelism. A new Optimizing Build Dependencies section was added to cover this new functionality.

Working With Qt chapter:

  • Some minor updates were added to this chapter to reflect that Qt 6.0 has now been officially released. Since the CMake support for Qt 6.0 is still considered to be in Tech Preview, this chapter still largely focuses on Qt 5.
  • Added a note about a change in behavior since CMake 3.17.0 (which has subsequently been reverted in CMake 3.19.2) which had an adverse effect on projects using the qt5_create_translation() command conditionally based on a CMake cache variable. The change resulted in .ts files being deleted in certain situations. The book provides exactly this scenario as an example, so a note has been added highlighting the specific circumstances where the problem may arise.
 
The 7th Edition has been updated for the CMake 3.18 release. It includes new, updated and reorganized material. Major highlights for this edition include significantly expanded coverage of command argument handling and a new chapter on debugging and diagnostics for running CMake. For the first time, the book is now also available in EPUB and MOBI formats, in addition to the usual PDF. The following lists the main changes in this edition.

 

General:

The formats in which the book is available has been expanded to include PDF, EPUB and MOBI. The formats contain the same content with the following minor differences:

  • Some EPUB and MOBI code examples have slight differences (typically just formatting) to allow for better readability on devices with narrower widths.
  • The EPUB and MOBI formats do not have an index at the end of the book.

The PDF file size has also been significantly reduced by about 60% through additional post-processing.

Variables chapter:

  • Most of the section covering the message() command has been moved to its own new chapter (Debugging And Diagnostics). Only the essential points have been retained in the Variables chapter to avoid distracting the reader from the main focus.
  • Added a note that the ccmake tool is not part of the official CMake packages for Windows.
  • CMake added a new NATURAL sorting option for the list(SORT) command.
  • A new section Problems With Unbalanced Square Brackets was added to cover a less well-known aspect of CMake’s list handling behavior.

Flow Control chapter:

  • Correct a slightly inaccurate statement about what variables are defined for the IN ZIP_LISTS form of the foreach() command. Variables past the end of shorter lists are undefined, not set to empty.

Functions And Macros chapter:

This chapter was substantially reworked and expanded to better cover argument handling and other features new in CMake 3.18. The main changes were the following:

  • CMake 3.18 added a new cmake_language() command, which is now covered in a new section Other Ways Of Invoking CMake Code.
  • CMake 3.18 also added support for a number of CMAKE_CURRENT_FUNCTION* variables which can be used to provide information about the function currently being executed. This is covered in a new section Special Variables For Functions.
  • Added discussion of the PARSE_ARGV form of the cmake_parse_arguments() command. This form has been available since CMake 3.7 and provides improved robustness when parsing function arguments.
  • Added a note that the contents of <prefix>_UNPARSED_ARGUMENTS will have semicolons escaped when using the PARSE_ARGV form of the cmake_parse_arguments() function. Examples were updated to highlight how and why this can be useful.
  • More clearly explain how and whether variables are defined for valueless, single-value and multi-value keyword arguments.
  • Added a discussion and example of implementing multi-level keyword argument parsing.
  • Added a note regarding the limitation that cmake_parse_arguments() does not support repeated keywords except for certain multi-value argument parsing arrangements.
  • A new section Problems With Argument Handling was added. It covers some often poorly understood aspects of CMake’s command argument handling in detail. A number of important observations are presented, along with explanations of some common problems associated with argument parsing and forwarding (e.g. list flattening and empty arguments being dropped). Techniques for how to avoid or work around these problems are given. Some special cases relating to argument expansion are also discussed. The PARSE_ARGV form of cmake_parse_arguments() and the new cmake_language() command are key parts of this new section.

Properties chapter:

  • CMake 3.18 added the ability to specify a directory scope when calling one of the setter or getter property commands to operate on source file properties. Previously, only source properties from the current directory scope could be set or retrieved.

Generator Expressions chapter:

  • Removed a couple of stray values from the table that showed various boolean generator expressions and their results. Both erroneous values were for rows that generate an error rather than producing a value.
  • Slightly expanded the discussion of quoting as part of the $<JOIN:...> expression details. The text now also mentions how quoting is necessary to avoid semicolons causing unwanted argument splitting.
  • Added a cross-reference in the Recommended Practices section to the Debugging Generator Expressions section in a separate new chapter.

Modules chapter:

  • Moved the contents of the Useful Development Aids section to the new Debugging And Diagnostics chapter.
  • Slightly simplified the example for the CheckCSourceCompiles module.
  • CMake 3.18 added a new CheckLinkerFlag module.
  • Updated the Recommended Practices section to note that code checks often dominate the profiling results of a CMake run (profiling is a new feature in CMake 3.18).

Debugging And Diagnostics chapter:

This is a new chapter for the 7th Edition. Material relating to debugging and diagnostics was moved from a number of earlier chapters and collected here in this new chapter. A number of significant new sections have also been added:

  • CMake 3.16 and 3.17 added features for message indenting, message contexts and messages associated with performing checks. These significantly expand the versatility of the message() command and provide projects and users with more control over the log output CMake generates.
  • A new section was added to discuss and provide examples for how to debug generator expressions.
  • CMake 3.18 added new cmake command line options for profiling the CMake run itself. This can be used to gain insight into what commands and parts of the project are taking the most time during the configure stage.

Language Requirements chapter:

  • Removed the comment that “…for some compilers/linkers, [the <LANG>_EXTENSIONS] setting can change the standard library the target is linked with”.

Target Types chapter:

  • From CMake 3.18, it is now possible to create a (non-global) alias for a non-global imported target. For libraries, how such aliases compare to INTERFACE IMPORTED libraries is also discussed.

Custom Tasks chapter:

  • CMake 3.18 added new ECHO_OUTPUT_VARIABLE and ECHO_ERROR_VARIABLE options to the execute_process() command. These can be used to capture the output and error streams but still have them show up in the CMake output too.

Working With Files chapter:

  • CMake 3.18 added the file(CONFIGURE) subcommand. It can be used to perform a similar task as configure_file() except that the input comes from a string instead of a file.
  • CMake 3.18 extended the file(UPLOAD) subcommand to support the TLS_VERIFY and TLS_CAINFO options. Previously, these options were only available for file(DOWNLOAD).

Specifying Version Details chapter:

  • Added a note that symbol visibility may need to be considered if version functions are to be exposed as part of a shared library’s API.

Finding Things chapter:

  • CMake 3.18 added support for a REQUIRED option to the find_file(), find_path(), find_program() and find_library() commands. This makes them more consistent with find_package() which already supported a REQUIRED option.

Testing chapter:

  • CMake 3.18 added support for a new ctest --stop-on-failure option. This will end a test run immediately upon the first error encountered.
  • Added a note that CMake 3.8 and earlier considers skipped tests to be an error, but CMake 3.9 and later does not.
  • A new CTEST_RESOURCE_SPEC_FILE variable can be used with CMake 3.18 or later as an alternative way to specify the JSON file that defines the resources available to a ctest run.
  • The gtest_discover_tests() command gained a new DISCOVERY_MODE keyword in CMake 3.18. This can be used to control whether test discovery is performed at built time or test time (the latter can be important if cross-compiling). A new CMAKE_GTEST_DISCOVER_TESTS_DISCOVERY_MODE variable can be used to change the default behavior globally.

Packaging chapter:

  • CMake 3.18 added support for a new CPACK_NSIS_MANIFEST_DPI_AWARE variable. It can be used to make NSIS installers DPI-aware.

External Content chapter:

  • The FetchContent module gained support for the SOURCE_SUBDIR option in CMake 3.18. The option is given to FetchContent_Declare() and used by FetchContent_MakeAvailable(). The option works in a similar way to the same-named option already available for ExternalProject_Add().

Project Organization chapter:

  • CMake 3.18 extended the source_group() command to also allow forward slashes to be used as separators between nesting levels, not just backslashes.

Build Performance chapter:

  • The initial unity build support added in CMake 3.16 only allowed an automatic batching of source files based on number of files and the order in which they were added to the target. CMake 3.18 adds a new UNITY_BUILD_MODE target property which can be used to select between the existing automatic behavior and manual grouping. A new UNITY_GROUP source file property controls the unity group each source file belongs to in manual mode.

Working With Qt chapter:

  • Added a brief discussion of the qt5_add_big_resources() command.
  • Added a new section Transition To Qt 6, which discusses features added in Qt 5.15 to help projects prepare for Qt 6.

 

 
The 6th Edition has been updated for the CMake 3.17 release and includes a substantial amount of new material. Major highlights of this edition are a new chapter on Qt support and an expansion of the topics covered in the Apple chapter. The following lists the main changes in this edition.

 

General presentation:

  • Conventions used for upper/lowercase naming of targets and tests has been made more consistent throughout the book.
  • An updated syntax highlighting scheme has been defined to improve consistency and reduce questionable highlighting in some code samples.

Introduction chapter:

  • Replaced mention of the CMake users mailing list with a link to the CMake forums.

Setting Up A Project chapter:

  • Updated generator examples table to mention Visual Studio 16 2019 and the new Ninja Multi-Config generator.

A Minimal Project chapter:

  • Replaced comments about when to call the project() command and toolchain configuration with cross-references to other chapters which cover the equivalent material in more detail. In particular, removed the ambiguous statement about calling project() “early enough”.

Variables chapter:

  • CMake 3.17 added the ability to set a default log level with the new CMAKE_MESSAGE_LOG_LEVEL cache variable.
  • Fixed some operators being listed twice in the description of the math() command.

Flow Control chapter:

  • CMake 3.17 added a new IN ZIP_LISTS form for the foreach() command.

Using Subdirectories chapter:

  • Added a new subsection When To Call project(). This expands on the previously ambiguous “calling project() early enough” comment in the A Minimal Project chapter. It also adds new material related to calling project() in subdirectories and calling it more than once, with particular reference to Visual Studio and Xcode projects.
  • Added advice to the Recommended Practices section discouraging calling project() in every subdirectory.

Functions And Macros chapter:

  • CMake 3.17 added a number of new variables that provide information related to the currently executing function. These are CMAKE_CURRENT_FUNCTION, CMAKE_CURRENT_FUNCTION_LIST_FILE, CMAKE_CURRENT_FUNCTION_LIST_DIR and CMAKE_CURRENT_FUNCTION_LIST_LINE. A common use case for CMAKE_CURRENT_FUNCTION_LIST_DIR is presented.

Properties chapter:

  • Added an example showing how to set source file properties.

Modules chapter:

  • Fixed the check_c_source_compiles() example which would previously have always returned the same result due to the name of the output variable always matching the regular expression.

Build Type chapter:

  • CMake 3.17 added a new Ninja Multi-Config generator. Some brief comments have been added to mention its support for specifying a default build type with the new CMAKE_DEFAULT_BUILD_TYPE variable.
  • Fixed the examples where the CMAKE_STATIC_LINKER_FLAGS_PROFILE variable was being given flags that are not relevant for a library archive tool.

Language Requirements chapter:

  • CMake 3.17 added the ability to directly specify compile features for CUDA rather than having to rely on a fallback to C or C++ compile features (this is only a brief note, CUDA is not covered in any great detail).
  • Condensed the discussion of compile features in the Recommended Practices section to give less prominence to granular compile features. Granular features are of decreasing importance, being restricted to C++11 and C++14 only and are no longer being added for later language standards. The standard meta features (e.g. cxx_std_17) continue to be added for each standard version.

Custom Tasks chapter:

  • CMake 3.17 added a new cmake -E rm command as a replacement for the now deprecated cmake -E remove and cmake -E remove_directory commands.
  • Added a paragraph to the Recommended Practices section briefly discussing use cases that the new Ninja Multi-Config generator uniquely supports. Comments are fairly restricted at this time due to the relatively new status and limited real-world experience with this generator.

Working With Files chapter:

  • Updated examples and discussion for cmake -E commands related to removing files and directories. The motivation for why cmake -E rm was added in CMake 3.17 is briefly discussed.

Libraries chapter:

  • Briefly mentioned the new MACHO_COMPATIBILITY_VERSION and MACHO_CURRENT_VERSION target properties added in CMake 3.17. They are discussed in more detail in the Apple Features chapter.

Toolchains And Cross Compiling chapter:

  • Fixed non-generator expression example in Tool Selection section where CMAKE_CXX_COMPILER_ID and CMAKE_CXX_COMPILER_VERSION variables were missing their CMAKE_ prefix.

Apple Features chapter:

A number of sections in this chapter were significantly reworked for this edition. Some sections were restructured to improve discoverability and navigation, while others are entirely new. Updates to account for changes with Xcode 11 have also been made.

  • Added a brief example showing how to obtain a summary of a project’s build settings from the command line.
  • Highlighted the change to using Apple Development as the default signing identity from Xcode 11, regardless of the target platform. Examples have been updated to use this identity where relevant.
  • The Application Bundles section has been divided into subsections to make it easier to quickly find information on specific aspects. Some content was reordered to improve the flow, especially with regard to the examples.
  • A more detailed discussion has been added around how to add resources and other files to an application bundle. The differences in behaviour between RESOURCE target property and the MACOSX_PACKAGE_LOCATION source property are now more clearly presented, particularly with regard to resources that need to be compiled before being added to the bundle. The main example also now includes an asset catalog to briefly show how they can be added too.
  • The Frameworks section has also been divided into subsections to improve discoverability and navigation.
  • The Build Settings section received a number of updates and has also been divided into subsections with a clearer, more coherent flow. The SDK subsection now shows how to select the simulator SDK when building from the command line. A significant new subsection Compiler Test Workarounds was added to address very common problems related to changes with Xcode 11, preventing code signing during compiler checks or try_compile() calls, and avoiding checks failing due to the use of an inappropriate target type for the chosen platform.
  • The Code Signing section has been divided into subsections and advice has been updated for signing-related changes that came in with Xcode 11 (mostly related to the new Apple Development identity being applicable across all target platforms). All examples in this section now use CMake 3.14 as their minimum CMake version. Comments regarding sign-on-copy for shared frameworks have been updated.
  • A significant new Universal Binaries section has been added. Both regular builds and archive actions are covered. Universal binaries can be device-only or device-and-simulator. This section discusses areas that are often unnecessarily over-constrained or misconfigured by many users.
  • Another new section Linking And Embedding Frameworks has been added. This section shows how to link to frameworks in a way that works for both archive actions and regular builds. It also presents techniques for copying frameworks into application bundles, including sign-on-copy if required.
  • The Limitations section has been updated to account for the techniques presented in the newly added sections.
  • The Recommended Practices section has been updated to account for the various changes to the rest of the chapter.

Finding Things chapter:

  • A new section Debugging find_…() Calls was added to cover the new --debug-find option and its associated CMAKE_FIND_DEBUG_MODE variable. This functionality is new for CMake 3.17.

Testing chapter:

  • CMake 3.17 added a new CMAKE_CTEST_ARGUMENTS variable, which is used by the test or RUN_TESTS build targets when invoking ctest.
  • Added subsections to the Test Grouping And Selection section for improved navigation and discoverability.
  • CMake 3.17 added support for Dr Memory to the MemCheck action (CDash scripts).

Installing chapter:

  • Updated discussions related to linking, copying and embedding of frameworks when targeting Apple platforms. The example for RPATH handling with app bundles was also updated.
  • Moved and slightly expanded the comments regarding the check_required_components() command in the Custom Install Logic section.

Packaging chapter:

  • CMake 3.17 added more customization options for the NSIS package generator related to user-visible installer and uninstaller aspects.
  • Added a note highlighting the increased minimum NSIS version from 2.09 to 3.0 with CMake 3.17, including a bug related to this change in CMake 3.17.0 which was fixed in CMake 3.17.1.
  • CMake 3.17 added support for per-component file names with the DragNDrop package generator.
  • Mentioned that CMake 3.17 officially deprecated the PackageMaker generator.

Build Performance chapter:

  • Added note that it may be desirable to add include_file_mtime to the CCACHE_SLOPPINESS options for improved cache hit rate.
  • Fixed typo in two examples CACHE_SLOPPINESS –> CCACHE_SLOPPINESS.

Working With Qt chapter:

This is an entirely new chapter dedicated to the CMake support provided for Qt. It covers basic setup such as how to correctly find Qt and make it available to the build. Some less obvious build configuration points-of-care are highlighted. Each of the essential moc, uic and rcc tools are also discussed, including both automatic and manual handling. The steps needed to incorporate translations into a CMake project are presented, including their deployment. Deploying Qt applications in general using tools like windeployqt and macdeployqt is also discussed.

Index:

The index has been converted to a single column and no longer has numerous cases of long keywords being broken up through line wrapping.

 

 
The 5th Edition has been updated for the CMake 3.16.0 release and covers a number of new significant features as well as the usual set of minor improvements. Major highlights of this edition are a new chapter on build performance and a substantial new section in the Testing chapter covering the new fine-grained test resources functionality. The following lists the main changes in this edition.

 

Variables chapter:

  • CMake 3.16 renamed the --loglevel option to --log-level.
  • Added note about changed behavior in CMake 3.5.0 for whether DEPRECATION messages are shown by default or not.

Flow Control chapter:

  • Addressed some minor inaccuracies in how the if() command interprets quoted constants.
  • Fixed incorrect logic and output for example for Interrupting Loops section.

Functions And Macros chapter:

  • Removed unnecessary extra variable dereference in example for parsing function arguments.

Properties chapter:

  • Mention that source properties can impact build performance due to interaction with unity builds.

Language Requirements chapter:

  • CMake 3.16 added support for recognizing OBJC and OBJCXX as their own distinct languages.

Target Types chapter:

  • Fixed object library example that used $<TARGET_SOURCES:...> (which isn’t a valid generator expression) instead of $<TARGET_OBJECTS:...>.

Custom Tasks chapter:

  • Fixed missing quote for a message() command in an execute_process() example.

Specifying Version Details chapter:

  • Added quotes around COMPILE_DEFINITIONS property value in example because it could be a list.
  • Added a call to target_include_directories() in example so that foobar_version.h can be found.

Working With Files chapter:

  • Added note highlighting that the -f option to cmake -E remove does not behave as documented.

Toolchains And Cross Compiling chapter:

  • CMake 3.16 restored support for Android NDK r19.
  • Briefly expanded discussion of Android toolchain examples to compare results for GCC and Clang for NDK <r18, r18 and r19.

Apple Features chapter:

  • Corrected and updated discussion of CFBundleVersion.
  • Mention new OBJC and OBJCXX language support added in CMake 3.16.

Finding Things chapter:

  • CMake 3.16 added support for a number of new variables of the form CMAKE_FIND_USE_... which can be used to change the defaults for the associated keyword options in the various find_...() commands.
  • From CMake 3.16, pkg_search_module() now populates <prefix>_MODULE_NAME with the module that was found.
  • Replaced all uses of the term “build slave” with other alternatives.

Testing chapter:

  • Added a substantial new section Managing Test Resources which covers the new fine-grained test resource allocation functionality added in CMake 3.16.
  • CMake 3.16 added support for a COMMAND_EXPAND_LISTS keyword for add_test().
  • CMake 3.16 added support for a new test property SKIP_REGULAR_EXPRESSION.
  • Gave the ambiguity of the -D option for ctest more prominence. It now has its own specific warning callout in the text.

Installing chapter:

  • Mentioned the new file(GET_RUNTIME_DEPENDENCIES) subcommand added in CMake 3.16.
  • Fixed variable dereferencing, naming and typos in main example of Config Files For CMake Projects section. The dependency on BagOfBeans was also switched to the mandatory Runtime component to simplify the example a little.

Packaging chapter:

  • CMake 3.16 added direct support for creating multi-configuration packages with cpack -C.
  • CMake 3.16 added support for creating archives using Zstandard compression.

Build Performance chapter:

  • New chapter focusing on techniques and CMake features for improving build performance.
  • CMake 3.16 added support for unity builds and precompiled headers.
  • Also contains sections covering ccache, split dwarf and using alternative linkers. The interaction between these and other features mentioned in the chapter is also discussed.

 

 
The 4th Edition has been updated for the CMake 3.15.0 release and also contains some other minor improvements. The following lists the main changes in this edition.

 

General Presentation:

  • Text readability has been improved by using fully black text. Previous editions used a dark grey, which was not as clear.

Setting Up A Project chapter:

  • New for CMake 3.15, the CMAKE_GENERATOR environment variable can be used to specify a default generator.
  • New for CMake 3.15, multiple targets can be given for the cmake --target command line option.

Variables chapter:

  • CMake 3.15 expanded the set of supported message types for the message() command, adding NOTICE, VERBOSE, DEBUG and TRACE logging levels. The minimum log level can also be specified with the --loglevel command line option.
  • Added comments highlighting that string(LENGTH) counts bytes rather than characters.
  • Added mention of the list(PREPEND), list(POP_FRONT) and list(POP_BACK) subcommands new for CMake 3.15.

Flow Control chapter:

  • Clarified wording for how numbers are treated by the if() command.

Using Subdirectories chapter:

  • Added new Project-relative Variables section describing the set of variables defined by the project() command.
  • Added paragraph to the Recommended Practices section advising to avoid using CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR and prefer the project-relative variables instead.

Functions And Macros chapter:

  • Fixed incorrect variable name for numbered arguments ARG# –> ARGV#, adjusted example to highlight that numbering starts from 0 and point out that accessing ARGVx with x >= ARGC is undefined behavior.
  • Added explanation and example for handling unprocessed arguments with <prefix>_UNPARSED_ARGUMENTS when using cmake_parse_arguments().
  • New for CMake 3.15, when using cmake_parse_arguments(), the <prefix>_KEYWORDS_MISSING_VALUES variable can be used to detect single or multi-value keywords that were not given any values.
  • Highlighted that functions receive a copy of all variables from the calling scope.
  • Added advice to the Recommended Practices section to prefer to pass information into functions and macros via arguments rather than relying on variables from the calling scope.

Properties chapter:

  • Clarified the difference between DEFINED and SET for the get_property() command.

Generator Expressions chapter:

  • Added a brief note that new generator expressions were added in CMake 3.15 for extracting the base name, prefix and suffix of target-related file names.
  • Made the wording a bit clearer regarding CMake 3.12 allowing object libraries to be linked directly instead of using $<TARGET_OBJECTS:...>.

Compiler And Linker Essentials chapter:

  • Added a small example showing how to more robustly add language-specific compiler flags to targets.

Custom Tasks chapter:

  • CMake 3.15 added a new JOB_POOL option to the add_custom_command() and add_custom_target() commands.
  • Added more explicit comments that a target cannot be made to depend on an output of add_custom_command() from a different directory scope.
  • New for CMake 3.15, the execute_process() command now accepts a new COMMAND_ECHO option and has an associated CMAKE_EXECUTE_PROCESS_COMMAND_ECHO variable.
  • Fixed typo in example: add_program() –> add_executable().
  • Added extra comments for archiver.cmake example to highlight why having it as a separate file can be useful.
  • Added note to the Recommended Practices section for when using execute_process() may be appropriate.

Working With Files chapter:

  • CMake 3.15 added a new FOLLOW_SYMLINK_CHAIN option to the file(COPY) and file(INSTALL) subcommands.
  • Updated the file(COPY) example to use more appropriate permissions (world execute rather than world write for the whoami.sh file).

Toolchains And Cross Compiling chapter:

  • Added discussion of CMAKE_GENERATOR_PLATFORM and CMAKE_GENERATOR_TOOLSET and their associated -A and -T command line options, with examples for Visual Studio.
  • Added brief explanation of CMAKE_GENERATOR_INSTANCE and when it may be useful.

Apple Features chapter:

  • New for CMake 3.15, the CMAKE_FRAMEWORK variable is now used to initialize the FRAMEWORK target property.

Finding Things chapter:

  • New for CMake 3.15, the CMAKE_FIND_PACKAGE_PREFER_CONFIG variable can be used to change the search preference of find_package() to look for config package files before a find module.
  • CMake 3.15 introduced policy CMP0090 to make the default behavior of export(PACKAGE) not update the package registry. The new CMAKE_EXPORT_PACKAGE_REGISTRY variable can be used to re-enable it if required.
  • Added note that pkg_get_variable() would incorrectly ignore CMAKE_PREFIX_PATH with CMake 3.14 and earlier due to a bug (fixed in CMake 3.15.0).

Testing chapter:

  • CMake 3.15 allows CROSSCOMPILING_EMULATOR to hold a list rather than just a single value. It can now include arguments too, not just a single script or executable.

Installing chapter:

  • CMake 3.15 removed the problematic caching optimization in find_dependency() that sometimes caused package components to be handled incorrectly.
  • CMake 3.15 added a new cmake --install command line option to allow an install to be performed without invoking the build tool. It also has more flexibility and is easier to use than running the cmake_install.cmake script from the build directory.

Project Organization chapter:

  • Split up the Miscellaneous Project Features section into three new sections with more specific focus: Cleaning Files, Re-running CMake On File Changes and Injecting Files Into Projects.
  • CMake 3.15 added ADDITIONAL_CLEAN_FILES directory and target properties as more general replacements for the existing ADDITIONAL_MAKE_CLEAN_FILES directory property.
  • CMake 3.15 added new CMAKE_PROJECT_INCLUDE and CMAKE_PROJECT_INCLUDE_BEFORE variables for injecting content after or before any project() command.
  • Added a paragraph to the Recommended Practices section mentioning how CMAKE_PROJECT_<PROJNAME>_INCLUDE can be used with continuous integration builds to mitigate problems with unwanted values in the CMake cache for incremental builds.

 

 
The 3rd Edition has been updated for the CMake 3.14.0 release and also contains some other minor improvements. The following lists the main changes in this edition.

 

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.

 

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

 

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.

 

 
The book was initially released with a X.Y.Z versioning scheme, but this was found to be incompatible with some book-tracking systems. All 1.0.z releases are considered to be “1st Edition” and do not have any ISBN.

 

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.

 

 

* The 1st Edition included a few minor updates and followed a X.Y.Z versioning scheme. The 2nd Edition was initially released as v1.1.0 on 21st November 2018 but was formally published as the 2nd Edition on 12th December 2018.

X-twitter