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 Tool Mode (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.