CMake 3.12 Release Notes¶
Contents
Changes made since CMake 3.11 include the following.
New Features¶
Generators¶
The Visual Studio Generators for VS 2017 learned to support a
version=14.##option in theCMAKE_GENERATOR_TOOLSETvalue (e.g. via thecmake(1)-Toption) to specify a toolset version number.
Command-Line¶
The
cmake(1)Build a Project (cmake --build) gained--parallel [<jobs>]and-j [<jobs>]options to specify a parallel build level. They map to corresponding options of the native build tool.
Commands¶
The
add_compile_definitions()command was added to set preprocessor definitions at directory level. This supersedesadd_definitions().The
cmake_minimum_required()andcmake_policy(VERSION)commands now accept a version range using the form<min>[...<max>]. The<min>version is required but policies are set based on the older of the running CMake version and the version specified by<max>. This allows projects to specify a range of versions for which they have been updated and avoid explicit policy settings.The
file(GLOB)andfile(GLOB_RECURSE)commands learned a new flagCONFIGURE_DEPENDSwhich enables expression of build system dependency on globbed directory’s contents.The
file(TOUCH)andfile(TOUCH_NOCREATE)commands were added to exposeTOUCHfunctionality without having to use CMake’s command-line tool mode withexecute_process().The
find_package()command now searches prefixes specified by the<PackageName>_ROOTCMake variable and the<PackageName>_ROOTenvironment variable. Package roots are maintained as a stack so nested calls to allfind_*commands inside find modules also search the roots as prefixes. See policyCMP0074.The
install()command learned an optionalNAMELINK_COMPONENTparameter, which allows you to change the component for a shared library’s namelink. If none is specified, the value ofCOMPONENTis used by default.The
list()command learned aJOINsub-command to concatenate list’s elements separated by a glue string.The
list()command learned aSUBLISTsub-command to get a sublist of the list.The
list()command learned aTRANSFORMsub-command to apply various string transformation to list’s elements.The
project()command learned an optionalHOMEPAGE_URLparameter which has the effect of setting variables likePROJECT_HOMEPAGE_URL,<PROJECT-NAME>_HOMEPAGE_URLandCMAKE_PROJECT_HOMEPAGE_URL.The
string()command learned aJOINsub-command to concatenate input strings separated by a glue string.target_compile_options()andadd_compile_options()commands gained aSHELL:prefix to specify a group of related options using shell-like quoting.The
target_link_libraries()command now supports Object Libraries. Linking to an object library uses its object files in direct dependents and also propagates usage requirements.
Variables¶
The
CMAKE_FOLDERvariable was added to initialize theFOLDERproperty on all targets.The
CMAKE_DOTNET_TARGET_FRAMEWORK_VERSIONvariable was defined to initialize allDOTNET_TARGET_FRAMEWORK_VERSIONtarget properties.CMAKE_PROJECT_VERSION*variables have been introduced:The
CMAKE_SUPPRESS_REGENERATIONvariable was extended to support theNinjaand Makefile Generators. It is also now documented.CMAKE_VS_SDK_*_DIRECTORIESvariables were defined to tell Visual Studio Generators for VS 2010 and above how to populate fields in.vcxprojfiles that specify SDK directories. The variables are:A
MSVC_TOOLSET_VERSIONvariable was added to provide the MSVC toolset version associated with the current MSVC compiler version inMSVC_VERSION.
Properties¶
The
COMMON_LANGUAGE_RUNTIMEtarget property was introduced to configure the use of managed C++ for Visual Studio Generators for VS 2010 and above. A correspondingIMPORTED_COMMON_LANGUAGE_RUNTIMEtarget property was added to supportC++/CLIfor imported targets.The
DOTNET_TARGET_FRAMEWORK_VERSIONtarget property was introduced as replacement forVS_DOTNET_TARGET_FRAMEWORK_VERSION, which is considered deprecated now.An
EXPORT_PROPERTIEStarget property was added to specify a custom list of target properties to include in targets exported by theinstall(EXPORT)andexport()commands.The
PDB_OUTPUT_DIRECTORYproperty learned to supportgenerator expressions.A
TESTSdirectory property was added to hold the list of tests defined by theadd_test()command.A
VS_DEBUGGER_COMMANDtarget property was created to set the debugging command line with Visual Studio Generators for VS 2010 and above.HLSL source file properties
VS_SHADER_DISABLE_OPTIMIZATIONSandVS_SHADER_ENABLE_DEBUGgained support for generator expressions.HLSL source file property
VS_SHADER_OBJECT_FILE_NAMEhas been added to the Visual Studio Generators for VS 2010 and above. The property specifies the file name of the compiled shader object.
Modules¶
The
FindALSAmodule now provides imported targets.The
FindCURLmodule now provides imported targets.The
FindJPEGmodule now provides imported targets.The
FindLibXml2module now provides imported targets.The
FindMatlabmodule now supports the Matlab Runtime Compiler (MCR) for compiling and linking matlab extensions.A
FindODBCmodule was added to find an Open Database Connectivity (ODBC) library.The
FindPkgConfigmodule has learned to export the found libraries with full path for direct consumption with thetarget_link_libraries()command.New
FindPython3andFindPython2modules, as well as a newFindPythonmodule, have been added to provide a new way to locate python environments.The
UseSWIGmodule gained a whole refresh and is now more consistent with standard CMake commands to generate libraries and is fully configurable through properties.The
UseSWIGmodule learned to manage multiple behaviors throughUseSWIG_MODULE_VERSIONvariable to ensure legacy support as well as more robust handling ofSWIGadvanced features (like%template).The
UseSWIGmodule learned to support CSHARP variant wrapper files.The
WriteCompilerDetectionHeadermodule gained aBARE_FEATURESoption to add a compatibility define for the exact keyword of a new language feature.
Generator Expressions¶
A new
$<GENEX_EVAL:...>and$<TARGET_GENEX_EVAL:target,...>generator expressionhas been added to enable consumption of generator expressions whose evaluation results itself in generator expressions.A new
$<IN_LIST:...>generator expressionhas been added.A new
$<TARGET_EXISTS:...>generator expressionhas been added.A new
$<TARGET_NAME_IF_EXISTS:...>generator expressionhas been added.
CTest¶
The
ctest_start()command has been reworked so that you can simply callctest_start(APPEND)and it will read all the needed information from the TAG file. The argument parsing has also been relaxed so that the order of the arguments is less significant.A
PROCESSOR_AFFINITYtest property was added to request that CTest run a test with CPU affinity for a set of processors disjoint from other concurrently running tests with the property set.
CPack¶
The
CPackmodule now uses variablesCMAKE_PROJECT_VERSION_MAJOR,CMAKE_PROJECT_VERSION_MINORandCMAKE_PROJECT_VERSION_PATCHto initialize corresponding CPack variables.A
CPack NuGet Generatorwas was added with basic support for NuGet.
Other¶
The
Compile Featuresfunctionality is now aware of C++ 20. No specific features are yet enumerated besides thecxx_std_20meta-feature.The
Compile Featuresfunctionality is now aware of the availability of C features in MSVC since VS 2010.The
Compile Featuresfunctionality is now aware of C language standards supported by Texas Instruments C compilers.
Deprecated and Removed Features¶
The
Visual Studio 8 2005generator has been removed.CMake no longer produces
<tgt>_LIB_DEPENDScache entries for library targets. See policyCMP0073.
Other Changes¶
Include flags for directories marked as
SYSTEMare now moved after non-system directories. The-isystemflag does this automatically, so moving them explicitly to the end makes the behavior consistent on compilers that do not have any-isystemflag.Fortran dependency scanning now supports dependencies implied by Fortran Submodules.
The existence and functionality of the file
${CMAKE_BINARY_DIR}/cmake_install.cmakehas now been documented in theinstall()documentation so that external packaging software can take advantage of CPack-style component installs.The
CheckIncludeFilemodulecheck_include_filemacro learned to honor theCMAKE_REQUIRED_LIBRARIESvariable. See policyCMP0075.The
CheckIncludeFileCXXmodulecheck_include_file_cxxmacro learned to honor theCMAKE_REQUIRED_LIBRARIESvariable. See policyCMP0075.The
CheckIncludeFilesmodulecheck_include_filesmacro learned to honor theCMAKE_REQUIRED_LIBRARIESvariable. See policyCMP0075.The
cmake(1)-E copy_directorytool now fails when the source directory does not exist. Previously it succeeded by creating an empty destination directory.The
UseSWIGmoduleswig_add_library()command (and legacyswig_add_modulecommand) now set the prefix of Java modules to""for MINGW, MSYS, and CYGWIN environments.