CMake 3.18 Release Notes¶
Changes made since CMake 3.17 include the following.
New Features¶
Languages¶
The
CUDAlanguage can now be compiled using Clang on non-Windows platforms. Separable compilation is not yet supported on any platform.
Command-Line¶
Commands¶
The
add_library()andadd_executable()commands learned to create Alias Targets referencing non-GLOBALImported Targets.The
cmake_language()command was added for meta-operations on scripted or built-in commands, starting with a mode toCALLother commands, andEVAL CODEto inplace evaluate a CMake script.The
execute_process()command gained theECHO_OUTPUT_VARIABLEandECHO_ERROR_VARIABLEoptions.The
export()command now raise an error if used multiple times with sameFILEwithoutAPPEND. See policyCMP0103.The
file()command gained theARCHIVE_CREATEandARCHIVE_EXTRACTsubcommands to expose thecmake(1)-E tarfunctionality to CMake scripting code.The
file(CONFIGURE)subcommand was created in order to replicate theconfigure_file()functionality without resorting to a pre-existing file on disk as input. The content is instead passed as a string.The
file(UPLOAD)command gainedTLS_VERIFYandTLS_CAINFOoptions to control server certificate verification.The
find_program(),find_library(),find_path()andfind_file()commands gained a newREQUIREDoption that will stop processing with an error message if nothing is found.The
get_property()command withSOURCEscope gained theDIRECTORYandTARGET_DIRECTORYoptions to get a property from the provided directory scope.The
get_source_file_property()command gained theDIRECTORYandTARGET_DIRECTORYoptions to get a property from the provided directory scope.The
list()operationSORTgained theNATURALsort option to sort using natural order (seestrverscmp(3)manual).The
set_property()command with theSOURCEscope gained theDIRECTORYandTARGET_DIRECTORYoptions to set properties in the provided directory scopes.The
set_source_files_properties()command gained theDIRECTORYandTARGET_DIRECTORYoptions to set properties in the provided directory scopes.The
string()command learned a newHEXsub-command, which converts strings into their hexadecimal representation.
Variables¶
A
CMAKE_CUDA_ARCHITECTURESvariable was added to specify CUDA output architectures. Users are encouraged to use this instead of specifying options manually, as this approach is compiler-agnostic. The variable is initialized automatically whenCMAKE_CUDA_COMPILER_IDisNVIDIA. The variable is used to initialize the newCUDA_ARCHITECTUREStarget property. See policyCMP0104.The
CMAKE_PCH_WARN_INVALIDvariable was added to initialize thePCH_WARN_INVALIDtarget property to allow the removal of the precompiled header invalid warning.
Properties¶
The
CUDA_ARCHITECTUREStarget property was added to specify CUDA output architectures. Users are encouraged to use this instead of specifying options manually, as this approach is compiler-agnostic. The property is initialized by the newCMAKE_CUDA_ARCHITECTURESvariable. See policyCMP0104.The
Fortran_PREPROCESStarget property andFortran_PREPROCESSsource-file property were added to control preprocessing of Fortran source files.The
FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>target property and associatedCMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>variable were created to allow adding a postfix to the name of a framework file name when using a multi-config generator.The
OBJECT_OUTPUTSsource file property now supportsgenerator expressions.The
PCH_WARN_INVALIDtarget property was added to allow the removal of the precompiled header invalid warning.The
UNITY_BUILD_MODEtarget property was added to tell generators which algorithm to use for grouping included source files.The
VS_SOURCE_SETTINGS_<tool>target property was added to tell Visual Studio Generators for VS 2010 and above to add metadata to non-built source files using<tool>.The
VS_SETTINGSsource file property was added to tell Visual Studio Generators for VS 2010 and above to add metadata to a non-built source file.The
VS_PLATFORM_TOOLSETtarget property was added to tell Visual Studio Generators for VS 2010 and above to override the platform toolset.The
VS_SOLUTION_DEPLOYtarget property was added to tell Visual Studio Generators for VS 2010 and above to mark a target for deployment even when not building for Windows Phone/Store/CE.
Modules¶
The
CheckLinkerFlagmodule has been added to provide a facility to check validity of link flags.The
ExternalProjectmoduleExternalProject_Add()command gained a newGIT_REMOTE_UPDATE_STRATEGYkeyword. This can be used to specify how failed rebase operations during a git update should be handled. TheCMAKE_EP_GIT_REMOTE_UPDATE_STRATEGYvariable was also added as a global default and is honored by both theExternalProjectandFetchContentmodules.The
FetchContentmoduleFetchContent_Declare()command now supports aSOURCE_SUBDIRoption. It can be used to directFetchContent_MakeAvailable()to look in a different location for theCMakeLists.txtfile.The
FindBLASmodule now provides an imported target.The
FindCUDAToolkitmodule:gained the variable
CUDAToolkit_LIBRARY_ROOT, which is the directory containing thenvvmdirectory andversion.txt.uses toolkit and library root found during
CUDAcompiler detection.
The
FindLAPACKmodule now provides an imported target.The
FindPython3,FindPython2andFindPythonmodules:gained the possibility to create per-artifact cache variables for interactive editing in
cmake-gui(1)andccmake(1).gained sub-components
Development.ModuleandDevelopment.Embedunder theDevelopmentcomponent.gained the capability to specify which Python implementations to find, including
IronPythonandPyPy.
The
FindRubymodule input and output variables were all renamed fromRUBY_toRuby_for consistency with other find modules. Input variables of the old case will be honored if provided, and output variables of the old case are always provided.The
FindSWIGmodule now accepts target languages asCOMPONENTSandOPTIONAL_COMPONENTSarguments tofind_package.The
GoogleTestmodulegtest_discover_tests()command:gained a new
DISCOVERY_MODEoption to control when the test discovery step is run. It offers a newPRE_TESTsetting to run the discovery at test time instead of build time. A newCMAKE_GTEST_DISCOVER_TESTS_DISCOVERY_MODEvariable can be used to change the default globally.gained a new optional parameter
XML_OUTPUT_DIR. When set the JUnit XML test results are stored in that directory.
The
FindLibXsltmodule now provides imported targets.The
UseSWIGmodule now supports Fortran as a target language if theSWIG_EXECUTABLEis SWIG-Fortran.
Generator Expressions¶
The
$<DEVICE_LINK:...>and$<HOST_LINK:...>generator expressionswere added to manage device and host link steps.The
$<LINK_LANGUAGE:...>and$<LINK_LANG_AND_ID:...>generator expressionswere added.
CTest¶
ctest(1)gained a newCTEST_RESOURCE_SPEC_FILEvariable, which can be used to specify a resource specification file.ctest(1)gained a--stop-on-failureoption, which can be used to stop running the tests once one has failed.The
ctest_test()command gained aSTOP_ON_FAILUREoption which can be used to stop running the tests once one has failed.The
CTestCoverageCollectGCOVmodulectest_coverage_collect_gcov()command gained aTARBALL_COMPRESSIONoption to control compression of the tarball of collected results.
CPack¶
The
CPack Archive Generator'sTXZformat learned theCPACK_ARCHIVE_THREADSvariable to enable parallel compression. Requires support in theliblzmaused by CMake.The
CPack NSIS Generatorgained a new variableCPACK_NSIS_MANIFEST_DPI_AWAREto declare that the installer is DPI-aware.The
CPack RPM GeneratorgainedCPACK_RPM_PRE_TRANS_SCRIPT_FILEandCPACK_RPM_POST_TRANS_SCRIPT_FILEvariables to specify pre- and post-transaction scripts.
Other¶
cmake-gui(1)now populates its generator selection widget default value from theCMAKE_GENERATORenvironment variable. Additionally, environment variablesCMAKE_GENERATOR_PLATFORMandCMAKE_GENERATOR_TOOLSETare used to populate their respective widget defaults.ccmake(1)learned to read aCCMAKE_COLORSenvironment variable to customize colors.The
Compile Featuresfunctionality is now aware of the availability of C11 features in MSVC 19.27 and 19.28, including support for thec_restrict,c_static_assertfeatures and the-std:c11flag.
Deprecated and Removed Features¶
The
Documentationmodule has been deprecated viaCMP0106. This module was essentially VTK code that CMake should not be shipping anymore.An explicit deprecation diagnostic was added for policy
CMP0070and policyCMP0071(CMP0069and 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.
Other Changes¶
On Windows, the
NinjaandNinja Multi-Configgenerators, when a compiler is not explicitly specified, now select the first compiler (of any name) found in directories listed by thePATHenvironment variable.The
LINK_OPTIONSandINTERFACE_LINK_OPTIONStarget properties are now used for the device link step. See policyCMP0105.Creation of an
ALIAStarget overwriting an existing target now raises an error. See policyCMP0107.Linking a target to itself through an alias now raises an error. See policy
CMP0108.The
FindPackageHandleStandardArgsmodule optionREQUIRED_VARSis now optional ifHANDLE_COMPONENTSis specified.The
source_group()command now also recognizes forward slashes as subgroup delimiters, not just backslashes.ctest(1)now logs environment variables that it sets for each test, either due to theENVIRONMENTproperty or the resource allocation feature, and submits this log to CDash. It does not log environment variables that were set outside of CTest.When building CMake itself from source and not using a system-provided libcurl, HTTP/2 support is now enabled for commands supporting network communication via
http(s), such asfile(DOWNLOAD),file(UPLOAD), andctest_submit(). The precompiled binaries provided oncmake.orgnow support HTTP/2.The
cmake-file-api(7)"codemodel" version 2versionfield has been updated to 2.1.The
cmake-file-api(7)"codemodel" version 2 "target" object gained a newprecompileHeadersfield in thecompileGroupsobjects.
Updates¶
Changes made since CMake 3.18.0 include the following.
3.18.1¶
The
Xcodegenerator, whenCMAKE_OSX_ARCHITECTURESis not defined, now selects$(NATIVE_ARCH_ACTUAL)as the default architecture (the XcodeARCHSsetting). This is needed for Xcode 12 to select the host's architecture, which older versions of Xcode did by default.In CMake 3.18.0 the
add_test()command learned to support special characters in test names. This was accidentally left out of its release notes. Unfortunately the fix breaks existing projects that were using manual quoting or escaping to work around the prior limitation. This fix has been reverted in 3.18.1, but may be re-introduced in future versions of CMake with a policy for compatibility.
3.18.2¶
The default value of
CMAKE_AUTOMOC_PATH_PREFIXwas changed toOFFbecause this feature can break existing projects that have identically named header files in different include directories. This restores compatibility with behavior of CMake 3.15 and below. The default was also changed toOFFin 3.16.9 and 3.17.5.The
Compile Featuresfunctionality was updated for MSVC 19.27 as mentioned above (c_restrict).
3.18.3¶
The
Compile Featuresfunctionality was updated for MSVC 19.28 as mentioned above (c_static_assert).