CMake 3.19 Release Notes¶
Changes made since CMake 3.18 include the following.
New Features¶
Presets¶
- cmake(1)and- cmake-gui(1)now recognize- CMakePresets.jsonand- CMakeUserPresets.jsonfiles (see- cmake-presets(7)).
Generators¶
- The - Xcodegenerator now uses the Xcode "new build system" when generating for Xcode 12.0 or higher. See the- CMAKE_XCODE_BUILD_SYSTEMvariable. One may use- -T buildsystem=1to switch to the legacy build system.
- The - Xcodegenerator gained support for linking libraries and frameworks via the Link Binaries With Libraries build phase instead of always by embedding linker flags directly. This behavior is controlled by a new- XCODE_LINK_BUILD_PHASE_MODEtarget property, which is initialized by a new- CMAKE_XCODE_LINK_BUILD_PHASE_MODEvariable.
- The Visual Studio Generators for VS 2015 and above gained support for the Visual Studio Tools for Android. One may now set - CMAKE_SYSTEM_NAMEto- Androidto generate- .vcxprojfiles for the Android tools.
Languages¶
- CMake learned to support - ISPCas a first-class language that can be enabled via the- project()and- enable_language()commands.- ISPCis currently supported by the Makefile Generators and the- Ninjagenerator on Linux, macOS, and Windows using the Intel ISPC compiler.
- CUDAlanguage support for Clang now includes:- separable compilation ( - CUDA_SEPARABLE_COMPILATION), and
- finding scattered toolkit installations when cross-compiling. 
 
- CUDAlanguage support now works on QNX.
Platforms¶
- Apple Silicon is now supported (since CMake 3.19.2): - The - CMAKE_HOST_SYSTEM_PROCESSORis selected using- uname -m. Since this may vary based on CMake's own architecture and that of the invoking process tree, the- CMAKE_APPLE_SILICON_PROCESSORvariable or- CMAKE_APPLE_SILICON_PROCESSORenvironment variable may be set to specify a host architecture explicitly.
- If - CMAKE_OSX_ARCHITECTURESis not set, CMake adds explicit flags to tell the compiler to build for the- CMAKE_HOST_SYSTEM_PROCESSORso the toolchain does not have to guess based on the process tree's architecture.
 
File-Based API¶
- The - cmake-file-api(7)"codemodel" version 2- versionfield has been updated to 2.2.
- The - cmake-file-api(7)"codemodel" version 2 "target" object gained a new- languageStandardfield in the- compileGroupsobjects.
Command-Line¶
GUI¶
- The - CMake GUInow has an environment variable editor.
Commands¶
- The - add_test()command now (officially) supports whitespace and other special characters in the name for the test it creates. See policy- CMP0110.
- The - cmake_language()command gained a- DEFERmode to schedule command calls to occur at the end of processing a directory.
- The - configure_file()command gained a- NO_SOURCE_PERMISSIONSoption to suppress copying the input file's permissions to the output file.
- The - execute_process()command gained a- COMMAND_ERROR_IS_FATALoption to specify a fatal error.
- The - file(ARCHIVE_CREATE)command gained a- COMPRESSION_LEVELoption to specify the compression level.
- The - file(CHMOD)and- file(CHMOD_RECURSE)subcommands were added to set permissions of files and directories.
- The - file(DOWNLOAD)command- <file>argument is now optional. If it is not specified, the file is not saved.
- The - file(GENERATE)command gained a new- TARGETkeyword to support resolving target-dependent generator expressions.
- The - file()command gained a new- REAL_PATHsub-command to compute a path with symlinks resolved.
- The - find_package()command learned to handle a version range.
- The - separate_arguments()command gained a new- PROGRAMoption. It allows the arguments to be treated as a program invocation and will resolve the executable to a full path if it can be found.
- The - DIRECTORYoption of the- set_property(),- get_property(), and- get_directory_property()commands now accepts references to binary directory paths, such as the value of- CMAKE_CURRENT_BINARY_DIR.
- The - string()command gained a set of new- JSONsub commands that provide JSON parsing capabilities.
Variables¶
- The - CMAKE_CLANG_VFS_OVERLAYvariable was added to tell Clang to use a VFS overlay to support the Windows SDK when cross-compiling from hosts with case-sensitive filesystems.
- The - CMAKE_MFC_FLAGvariable now supports generator expressions.
- The - CMAKE_OPTIMIZE_DEPENDENCIESvariable was added to initialize the new- OPTIMIZE_DEPENDENCIEStarget property and avoid unnecessarily building dependencies for a static library.
- The - CMAKE_PCH_INSTANTIATE_TEMPLATESvariable was added to initialize the new- PCH_INSTANTIATE_TEMPLATEStarget property.
- The - CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUMvariable was added to tell the Visual Studio Generators what maximum version of the Windows SDK to choose.
Properties¶
- The - EXCLUDE_FROM_ALLtarget property now supports- generator expressions.
- The - OPTIMIZE_DEPENDENCIEStarget property was added to avoid unnecessarily building dependencies for a static library.
- The - PCH_INSTANTIATE_TEMPLATEStarget property was added to enable template instantiation in the precompiled header. This is enabled by default and may significantly improve compile times. Currently only supported for Clang (version 11 or later).
- The - WIN32_EXECUTABLEtarget property now supports- generator expressions.
Modules¶
- The - CheckCompilerFlagmodule has been added to generalize- CheckCCompilerFlagand- CheckCXXCompilerFlagto more languages. It also supports the- CUDAand- ISPClanguages.
- The - CheckLinkerFlagmodule now supports the- CUDAlanguage.
- The - CheckSourceCompilesmodule has been added to generalize- CheckCSourceCompilesand- CheckCXXSourceCompilesto more languages. It also supports the- CUDAand- ISPClanguages.
- The - CheckSourceRunsmodule has been added to generalize- CheckCSourceRunsand- CheckCXXSourceRunsto more languages. It also supports the- CUDAlanguage.
- The - CMakePackageConfigHelpersmodule gained support for version ranges.
- The - FindCUDAToolkitmodule gained support for finding CUDA toolkits that do not contain- nvcc, as well as for finding scattered toolkit installations when cross-compiling.
- The - FindPackageHandleStandardArgsmodule learned to handle version ranges. It also gained the- find_package_check_version()command to check the validity of a version against version-related arguments of- find_package()command.
- The - FindPython3,- FindPython2and- FindPythonmodules gained the ability to handle a version range.
- The - FindPython3,- FindPython2and- FindPythonmodules provide, respectively, the variable- Python3_LINK_OPTIONS,- Python2_LINK_OPTIONSand- Python_LINK_OPTIONSfor link options.
- The - FindSDLmodule now provides:- An imported target - SDL::SDL.
- Result variables - SDL_LIBRARIESand- SDL_INCLUDE_DIRS.
- Version variables - SDL_VERSION,- SDL_VERSION_MAJOR,- SDL_VERSION_MINOR, and- SDL_VERSION_PATCH.
 
- The - FindSWIGmodule gained the ability to handle a version range.
- The - FindTIFFmodule gained a- CXXcomponent to find the- tiffxxlibrary containing C++ bindings.
- The - FindVulkanmodule now provides a- Vulkan::glslcimported target and associated- Vulkan_GLSLC_EXECUTABLEvariable which contain the path to the GLSL SPIR-V compiler.
- The - UseSWIGmodule gained support for new source file properties- OUTPUT_DIRand- OUTFILE_DIRto manage output directories on a per-source basis.
CTest¶
- ctest(1)now supports the CUDA- compute-sanitizerchecker (previously known as- cuda-memcheck) as the- CTEST_MEMORYCHECK_COMMAND. The different tools (- memcheck,- racecheck,- synccheckand- initcheck) supported by- compute-sanitizercan be selected by adding appropriate flags to the- CTEST_MEMORYCHECK_COMMAND_OPTIONSvariable. The default flags are- --tool memcheck --leak-check full.
CPack¶
- CPack gained the - CPACK_PRE_BUILD_SCRIPTS,- CPACK_POST_BUILD_SCRIPTS, and- CPACK_PACKAGE_FILESvariables.
- The - CPack External Generatorgained the- CPACK_EXTERNAL_BUILT_PACKAGESvariable.
- The - CPack WIX Generatorgained a- CPACK_WIX_CUSTOM_XMLNSoption to specify custom XML namespaces.
Other¶
- Interface Libraries may now have source files added via - add_library()or- target_sources(). Those with sources will be generated as part of the build system.
Deprecated and Removed Features¶
- Compatibility with versions of CMake older than 2.8.12 is now deprecated and will be removed from a future version. Calls to - cmake_minimum_required()or- cmake_policy()that set the policy version to an older value now issue a deprecation diagnostic.
- An explicit deprecation diagnostic was added for policy - CMP0071(- CMP0071and below were already deprecated). The- cmake-policies(7)manual explains that the OLD behaviors of all policies are deprecated and that projects should port to the NEW behaviors.
- macOS SDKs older than 10.5 are no longer supported. 
- cmake-gui(1)now requires Qt5. Support for compiling with Qt4 has been removed.
- The - cmake(1)command-line option- --warn-unused-varshas been removed and is now silently ignored. The option has not worked correctly since CMake 3.3.
Documentation¶
The following guides have been added:
Other Changes¶
- Building for macOS will now use the latest SDK available on the system, unless the user has explicitly chosen a SDK using - CMAKE_OSX_SYSROOT. The deployment target or system macOS version will not affect the choice of SDK.
- The - CMAKE_<LANG>_COMPILERvariable may now be used to store "mandatory" compiler flags like the- CCand other environment variables.
- The - CMAKE_<LANG>_FLAGS_INITvariable will now be considered during the compiler identification check if other sources like- CMAKE_<LANG>_FLAGSor- CFLAGSare not set.
- The - find_program()command now requires permission to execute but not to read the file found. See policy- CMP0109.
- An imported target missing its location property fails during generation if the location is used. See policy - CMP0111.
- The following target-based generator expressions that query for directory or file name components no longer add a dependency on the evaluated target. See policy - CMP0112.- TARGET_FILE_DIR
- TARGET_LINKER_FILE_BASE_NAME
- TARGET_LINKER_FILE_NAME
- TARGET_LINKER_FILE_DIR
- TARGET_SONAME_FILE_NAME
- TARGET_SONAME_FILE_DIR
- TARGET_PDB_FILE_NAME
- TARGET_PDB_FILE_DIR
- TARGET_BUNDLE_DIR
- TARGET_BUNDLE_CONTENT_DIR
 
- Makefile Generators no longer repeat custom commands from target dependencies. See policy - CMP0113.
- The - ExternalProjectmodule handling of step target dependencies has been revised. See policy- CMP0114.
- The - OSX_ARCHITECTUREStarget property is now respected for the- ASMlanguage.
- If - CUDAcompiler detection fails with user-specified- CMAKE_CUDA_ARCHITECTURESor- CMAKE_CUDA_HOST_COMPILER, an error is raised.
Updates¶
Changes made since CMake 3.19.0 include the following.
3.19.1¶
- CMake 3.19.0 compiles source files with the - LANGUAGEproperty by passing an explicit language flag such as- -x c. This is consistent with the property's documented meaning that the source file is written in the specified language. However, it can break projects that were using the property only to cause the specified language's compiler to be used. This has been reverted to restore behavior from CMake 3.18 and below.
- CUDA 11.1 support for Clang. 
3.19.2¶
- The precompiled macOS binary provided on - cmake.orgis now a universal binary with- x86_64and- arm64architectures. It requires macOS 10.10 or newer. The package file naming pattern has been changed from- cmake-$ver-Darwin-x86_64to- cmake-$ver-macos-universal.
- Apple Silicon host architecture selection support was updated. CMake 3.19.0 and 3.19.1 always chose - arm64as the host architecture. CMake 3.19.2 returns to using- uname -mas CMake 3.18 and below did. Since this may vary based on CMake's own architecture and that of the invoking process tree, the- CMAKE_APPLE_SILICON_PROCESSORvariable or- CMAKE_APPLE_SILICON_PROCESSORenvironment variable may be set to specify a host architecture explicitly.
- The - CMAKE_ISPC_HEADER_SUFFIXvariable and corresponding- ISPC_HEADER_SUFFIXtarget property were added to control the header suffix used by- ISPCcompiler generated headers.
3.19.3¶
- A precompiled Linux - aarch64binary is now provided on- cmake.org.
- Two precompiled macOS binaries are now provided on - cmake.org:- The naming pattern - cmake-$ver-macos-universalis a universal binary with- x86_64and- arm64architectures. It requires macOS 10.13 or newer.
- The naming pattern - cmake-$ver-macos10.10-universalis a universal binary with- x86_64and- arm64architectures. It requires macOS 10.10 or newer.
 
3.19.4¶
- The - CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUMvariable introduced in 3.19.0 previously worked only with the- Visual Studio 14 2015generator. It has now been fixed to work with Visual Studio Generators for later VS versions too.
3.19.5¶
- When - IOS_INSTALL_COMBINEDis enabled and the- Xcodegenerator is used, it is now possible to initiate an install or package creation by running- cmake --installor- cpackfrom the command line. When using the Xcode new build system, these are the only supported methods due to a limitation of Xcode. Initiating these operations by building the- installor- packagetargets in Xcode is only supported when using the legacy build system.
- The framework handling introduced in 3.19.0 as part of supporting Xcode's Link Binaries With Libraries build phase broke the ability to switch between device and simulator builds without reconfiguring. That capability has now been restored. 
3.19.6¶
- The - cmake-presets(7)feature no longer allows comments in- CMakePresets.jsonor- CMakeUserPresets.jsonfiles. This was mistakenly allowed by the implementation in CMake 3.19.0 through CMake 3.19.5, and was not documented.
3.19.7¶
- With Visual Studio Generators for VS 2017 and higher, the - CMAKE_GENERATOR_TOOLSETfield- version=now accepts three-component MSVC toolset versions such as- 14.28.29910. See the- CMAKE_VS_PLATFORM_TOOLSET_VERSIONvariable.
