CMake 3.19 Release Notes¶
Contents
Changes made since CMake 3.18 include the following.
New Features¶
Presets¶
cmake(1)andcmake-gui(1)now recognizeCMakePresets.jsonandCMakeUserPresets.jsonfiles (seecmake-presets(7)).
Generators¶
The
Xcodegenerator now uses the Xcode "new build system" when generating for Xcode 12.0 or higher. See theCMAKE_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 newXCODE_LINK_BUILD_PHASE_MODEtarget property, which is initialized by a newCMAKE_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_NAMEtoAndroidto generate.vcxprojfiles for the Android tools.
Languages¶
CMake learned to support
ISPCas a first-class language that can be enabled via theproject()andenable_language()commands.ISPCis currently supported by the Makefile Generators and theNinjagenerator on Linux, macOS, and Windows using the Intel ISPC compiler.CUDAlanguage support for Clang now includes:separable compilation (
CUDA_SEPARABLE_COMPILATION), andfinding 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 usinguname -m. Since this may vary based on CMake's own architecture and that of the invoking process tree, theCMAKE_APPLE_SILICON_PROCESSORvariable orCMAKE_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 theCMAKE_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 2versionfield has been updated to 2.2.The
cmake-file-api(7)"codemodel" version 2 "target" object gained a newlanguageStandardfield in thecompileGroupsobjects.
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 policyCMP0110.The
cmake_language()command gained aDEFERmode to schedule command calls to occur at the end of processing a directory.The
configure_file()command gained aNO_SOURCE_PERMISSIONSoption to suppress copying the input file's permissions to the output file.The
execute_process()command gained aCOMMAND_ERROR_IS_FATALoption to specify a fatal error.The
file(ARCHIVE_CREATE)command gained aCOMPRESSION_LEVELoption to specify the compression level.The
file(CHMOD)andfile(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 newTARGETkeyword to support resolving target-dependent generator expressions.The
file()command gained a newREAL_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 newPROGRAMoption. 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 theset_property(),get_property(), andget_directory_property()commands now accepts references to binary directory paths, such as the value ofCMAKE_CURRENT_BINARY_DIR.The
string()command gained a set of newJSONsub 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 newOPTIMIZE_DEPENDENCIEStarget property and avoid unnecessarily building dependencies for a static library.The
CMAKE_PCH_INSTANTIATE_TEMPLATESvariable was added to initialize the newPCH_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 supportsgenerator 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 supportsgenerator expressions.
Modules¶
The
CheckCompilerFlagmodule has been added to generalizeCheckCCompilerFlagandCheckCXXCompilerFlagto more languages. It also supports theCUDAandISPClanguages.The
CheckLinkerFlagmodule now supports theCUDAlanguage.The
CheckSourceCompilesmodule has been added to generalizeCheckCSourceCompilesandCheckCXXSourceCompilesto more languages. It also supports theCUDAandISPClanguages.The
CheckSourceRunsmodule has been added to generalizeCheckCSourceRunsandCheckCXXSourceRunsto more languages. It also supports theCUDAlanguage.The
CMakePackageConfigHelpersmodule gained support for version ranges.The
FindCUDAToolkitmodule gained support for finding CUDA toolkits that do not containnvcc, as well as for finding scattered toolkit installations when cross-compiling.The
FindPackageHandleStandardArgsmodule learned to handle version ranges. It also gained thefind_package_check_version()command to check the validity of a version against version-related arguments offind_package()command.The
FindPython3,FindPython2andFindPythonmodules gained the ability to handle a version range.The
FindPython3,FindPython2andFindPythonmodules provide, respectively, the variablePython3_LINK_OPTIONS,Python2_LINK_OPTIONSandPython_LINK_OPTIONSfor link options.The
FindSDLmodule now provides:An imported target
SDL::SDL.Result variables
SDL_LIBRARIESandSDL_INCLUDE_DIRS.Version variables
SDL_VERSION,SDL_VERSION_MAJOR,SDL_VERSION_MINOR, andSDL_VERSION_PATCH.
The
FindSWIGmodule gained the ability to handle a version range.The
FindTIFFmodule gained aCXXcomponent to find thetiffxxlibrary containing C++ bindings.The
FindVulkanmodule now provides aVulkan::glslcimported target and associatedVulkan_GLSLC_EXECUTABLEvariable which contain the path to the GLSL SPIR-V compiler.The
UseSWIGmodule gained support for new source file propertiesOUTPUT_DIRandOUTFILE_DIRto manage output directories on a per-source basis.
CTest¶
ctest(1)now supports the CUDAcompute-sanitizerchecker (previously known ascuda-memcheck) as theCTEST_MEMORYCHECK_COMMAND. The different tools (memcheck,racecheck,synccheckandinitcheck) supported bycompute-sanitizercan be selected by adding appropriate flags to theCTEST_MEMORYCHECK_COMMAND_OPTIONSvariable. The default flags are--tool memcheck --leak-check full.
CPack¶
CPack gained the
CPACK_PRE_BUILD_SCRIPTS,CPACK_POST_BUILD_SCRIPTS, andCPACK_PACKAGE_FILESvariables.The
CPack External Generatorgained theCPACK_EXTERNAL_BUILT_PACKAGESvariable.The
CPack WIX Generatorgained aCPACK_WIX_CUSTOM_XMLNSoption to specify custom XML namespaces.
Other¶
Interface Libraries may now have source files added via
add_library()ortarget_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()orcmake_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). Thecmake-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 theCCand other environment variables.The
CMAKE_<LANG>_FLAGS_INITvariable will now be considered during the compiler identification check if other sources likeCMAKE_<LANG>_FLAGSorCFLAGSare not set.The
find_program()command now requires permission to execute but not to read the file found. See policyCMP0109.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_DIRTARGET_LINKER_FILE_BASE_NAMETARGET_LINKER_FILE_NAMETARGET_LINKER_FILE_DIRTARGET_SONAME_FILE_NAMETARGET_SONAME_FILE_DIRTARGET_PDB_FILE_NAMETARGET_PDB_FILE_DIRTARGET_BUNDLE_DIRTARGET_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 policyCMP0114.The
OSX_ARCHITECTUREStarget property is now respected for theASMlanguage.If
CUDAcompiler detection fails with user-specifiedCMAKE_CUDA_ARCHITECTURESorCMAKE_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 withx86_64andarm64architectures. It requires macOS 10.10 or newer. The package file naming pattern has been changed fromcmake-$ver-Darwin-x86_64tocmake-$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 usinguname -mas CMake 3.18 and below did. Since this may vary based on CMake's own architecture and that of the invoking process tree, theCMAKE_APPLE_SILICON_PROCESSORvariable orCMAKE_APPLE_SILICON_PROCESSORenvironment variable may be set to specify a host architecture explicitly.The
CMAKE_ISPC_HEADER_SUFFIXvariable and correspondingISPC_HEADER_SUFFIXtarget property were added to control the header suffix used byISPCcompiler generated headers.
3.19.3¶
A precompiled Linux
aarch64binary is now provided oncmake.org.Two precompiled macOS binaries are now provided on
cmake.org:The naming pattern
cmake-$ver-macos-universalis a universal binary withx86_64andarm64architectures. It requires macOS 10.13 or newer.The naming pattern
cmake-$ver-macos10.10-universalis a universal binary withx86_64andarm64architectures. 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 theVisual 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 theXcodegenerator is used, it is now possible to initiate an install or package creation by runningcmake --installorcpackfrom 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 theinstallorpackagetargets 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 inCMakePresets.jsonorCMakeUserPresets.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_TOOLSETfieldversion=now accepts three-component MSVC toolset versions such as14.28.29910. See theCMAKE_VS_PLATFORM_TOOLSET_VERSIONvariable.