CMake 3.12 Release Notes¶
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 the- CMAKE_GENERATOR_TOOLSETvalue (e.g. via the- cmake(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 supersedes- add_definitions().
- The - cmake_minimum_required()and- cmake_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)and- file(GLOB_RECURSE)commands learned a new flag- CONFIGURE_DEPENDSwhich enables expression of build system dependency on globbed directory's contents.
- The - file(TOUCH)and- file(TOUCH_NOCREATE)commands were added to expose- TOUCHfunctionality without having to use CMake's command-line tool mode with- execute_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 all- find_*commands inside find modules also search the roots as prefixes. See policy- CMP0074.
- The - install()command learned an optional- NAMELINK_COMPONENTparameter, which allows you to change the component for a shared library's namelink. If none is specified, the value of- COMPONENTis used by default.
- The - list()command learned a- JOINsub-command to concatenate list's elements separated by a glue string.
- The - list()command learned a- SUBLISTsub-command to get a sublist of the list.
- The - list()command learned a- TRANSFORMsub-command to apply various string transformation to list's elements.
- The - project()command learned an optional- HOMEPAGE_URLparameter which has the effect of setting variables like- PROJECT_HOMEPAGE_URL,- <PROJECT-NAME>_HOMEPAGE_URLand- CMAKE_PROJECT_HOMEPAGE_URL.
- The - string()command learned a- JOINsub-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 the- FOLDERproperty on all targets.
- The - CMAKE_DOTNET_TARGET_FRAMEWORK_VERSIONvariable was defined to initialize all- DOTNET_TARGET_FRAMEWORK_VERSIONtarget properties.
- CMAKE_PROJECT_VERSION*variables have been introduced:
- The - CMAKE_SUPPRESS_REGENERATIONvariable was extended to support the- Ninjaand 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 in- MSVC_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 corresponding- IMPORTED_COMMON_LANGUAGE_RUNTIMEtarget property was added to support- C++/CLIfor imported targets.
- The - DOTNET_TARGET_FRAMEWORK_VERSIONtarget property was introduced as replacement for- VS_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 the- install(EXPORT)and- export()commands.
- The - PDB_OUTPUT_DIRECTORYproperty learned to support- generator expressions.
- A - TESTSdirectory property was added to hold the list of tests defined by the- add_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_OPTIMIZATIONSand- VS_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 the- target_link_libraries()command.
- New - FindPython3and- FindPython2modules, as well as a new- FindPythonmodule, 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 through- UseSWIG_MODULE_VERSIONvariable to ensure legacy support as well as more robust handling of- SWIGadvanced features (like- %template).
- The - UseSWIGmodule learned to support CSHARP variant wrapper files.
- The - WriteCompilerDetectionHeadermodule gained a- BARE_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 call- ctest_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 variables- CMAKE_PROJECT_VERSION_MAJOR,- CMAKE_PROJECT_VERSION_MINORand- CMAKE_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 the- cxx_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 policy- CMP0073.
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 the- install()documentation so that external packaging software can take advantage of CPack-style component installs.
- The - CheckIncludeFilemodule- check_include_filemacro learned to honor the- CMAKE_REQUIRED_LIBRARIESvariable. See policy- CMP0075.
- The - CheckIncludeFileCXXmodule- check_include_file_cxxmacro learned to honor the- CMAKE_REQUIRED_LIBRARIESvariable. See policy- CMP0075.
- The - CheckIncludeFilesmodule- check_include_filesmacro learned to honor the- CMAKE_REQUIRED_LIBRARIESvariable. See policy- CMP0075.
- 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 - UseSWIGmodule- swig_add_library()command (and legacy- swig_add_modulecommand) now set the prefix of Java modules to- ""for MINGW, MSYS, and CYGWIN environments.
