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()and- add_compile_options()commands gained a- SHELL: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.
