CMake 3.1 Release Notes¶
Changes made since CMake 3.0 include the following.
Documentation Changes¶
A new
cmake-compile-features(7)manual was added.
New Features¶
Generators¶
The
Visual Studio 14 2015generator was added.
Windows Phone and Windows Store¶
Generators for Visual Studio 11 (2012) and above learned to generate projects for Windows Phone and Windows Store. One may set the
CMAKE_SYSTEM_NAMEvariable toWindowsPhoneorWindowsStoreon thecmake(1)command-line or in aCMAKE_TOOLCHAIN_FILEto activate these platforms. Also setCMAKE_SYSTEM_VERSIONto8.0or8.1to specify the version of Windows to be targeted.
NVIDIA Nsight Tegra¶
Generators for Visual Studio 10 (2010) and above learned to generate projects for NVIDIA Nsight Tegra Visual Studio Edition. One may set the
CMAKE_SYSTEM_NAMEvariable toAndroidon thecmake(1)command-line or in aCMAKE_TOOLCHAIN_FILEto activate this platform.
Syntax¶
The
cmake-language(7)syntax for Variable References and Escape Sequences was simplified in order to allow a much faster implementation. See policyCMP0053.The
if()command no longer automatically dereferences variables named in quoted or bracket arguments. See policyCMP0054.
Commands¶
The
add_custom_command()command learned to interpretcmake-generator-expressions(7)in arguments toDEPENDS.The
export(PACKAGE)command learned to check theCMAKE_EXPORT_NO_PACKAGE_REGISTRYvariable to skip exporting the package.The
file(STRINGS)command gained a newENCODINGoption to enable extraction ofUTF-8strings.The
find_package()command learned to check theCMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRYandCMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRYvariables to skip searching the package registries.The
get_property()command learned a newINSTALLscope for properties.The
install()command learned aMESSAGE_NEVERoption to avoid output during installation.The
set_property()command learned a newINSTALLscope for properties.The
string()command learned a newGENEX_STRIPsubcommand which removesgenerator expression.The
string()command learned a newUUIDsubcommand to generate a universally unique identifier.New
target_compile_features()command allows populating theCOMPILE_FEATUREStarget property, just like any other build variable.The
target_sources()command was added to add to theSOURCEStarget property.
Variables¶
The Visual Studio generators for versions 8 (2005) and above learned to read the target platform name from a new
CMAKE_GENERATOR_PLATFORMvariable when it is not specified as part of the generator name. The platform name may be specified on thecmake(1)command line with the-Aoption, e.g.-G "Visual Studio 12 2013" -A x64.The
CMAKE_GENERATOR_TOOLSETvariable may now be initialized in a toolchain file specified by theCMAKE_TOOLCHAIN_FILEvariable. This is useful when cross-compiling with the Xcode or Visual Studio generators.The
CMAKE_INSTALL_MESSAGEvariable was introduced to optionally reduce output installation.
Properties¶
New
CXX_STANDARDandCXX_EXTENSIONStarget properties may specify values which CMake uses to compute required compile options such as-std=c++11or-std=gnu++11. TheCMAKE_CXX_STANDARDandCMAKE_CXX_EXTENSIONSvariables may be set to initialize the target properties.New
C_STANDARDandC_EXTENSIONStarget properties may specify values which CMake uses to compute required compile options such as-std=c11or-std=gnu11. TheCMAKE_C_STANDARDandCMAKE_C_EXTENSIONSvariables may be set to initialize the target properties.New
COMPILE_FEATUREStarget property may contain a list of features required to compile a target. CMake uses this information to ensure that the compiler in use is capable of building the target, and to add any necessary compile flags to support language features.New
COMPILE_PDB_NAMEandCOMPILE_PDB_OUTPUT_DIRECTORYtarget properties were introduced to specify the MSVC compiler program database file location (cl /Fd). This complements the existingPDB_NAMEandPDB_OUTPUT_DIRECTORYtarget properties that specify the linker program database file location (link /pdb).The
INTERFACE_LINK_LIBRARIEStarget property now supports a$<LINK_ONLY:...>generator expression.A new
INTERFACE_SOURCEStarget property was introduced. This is consumed by dependent targets, which compile and link the listed sources.The
SOURCEStarget property now containsgenerator expressionsuch asTARGET_OBJECTSwhen read at configure time, if policyCMP0051isNEW.The
SOURCEStarget property now generally supportsgenerator expression. The generator expressions may be used in theadd_library()andadd_executable()commands.It is now possible to write and append to the
SOURCEStarget property. TheCMAKE_DEBUG_TARGET_PROPERTIESvariable may be used to trace the origin of sources.A
VS_DEPLOYMENT_CONTENTsource file property was added to tell the Visual Studio generators to mark content for deployment in Windows Phone and Windows Store projects.A
VS_DEPLOYMENT_LOCATIONsource file property was added to tell the Visual Studio generators the relative location of content marked for deployment in Windows Phone and Windows Store projects.The
VS_WINRT_COMPONENTtarget property was created to tell Visual Studio generators to compile a shared library as a Windows Runtime (WinRT) component.The
Xcodegenerator learned to check source file propertiesXCODE_EXPLICIT_FILE_TYPEandXCODE_LAST_KNOWN_FILE_TYPEfor a custom Xcode file reference type.
Modules¶
The
BundleUtilitiesmodule learned to resolve and replace@rpathplaceholders on OS X to correctly bundle applications using them.The
CMakePackageConfigHelpersmoduleconfigure_package_config_file()command learned a newINSTALL_PREFIXoption to generate package configuration files meant for a prefix other thanCMAKE_INSTALL_PREFIX.The
CheckFortranSourceCompilesmodule was added to provide aCHECK_Fortran_SOURCE_COMPILESmacro.The
ExternalDatamodule learned to tolerate aDATA{}reference to a missing source file with a warning instead of rejecting it with an error. This helps developers write newDATA{}references to test reference outputs that have not yet been created.The
ExternalProjectmodule learned to support lzma-compressed source tarballs with.7z,.tar.xz, and.txzextensions.The
ExternalProjectmoduleExternalProject_Addcommand learned a newBUILD_ALWAYSoption to cause the external project build step to run every time the host project is built.The
ExternalProjectmoduleExternalProject_Addcommand learned a newEXCLUDE_FROM_ALLoption to cause the external project target to have theEXCLUDE_FROM_ALLtarget property set.The
ExternalProjectmoduleExternalProject_Add_Stepcommand learned a newEXCLUDE_FROM_MAINoption to cause the step to not be a direct dependency of the main external project target.The
ExternalProjectmoduleExternalProject_Addcommand learned a newDOWNLOAD_NO_PROGRESSoption to disable progress output while downloading the source tarball.The
FeatureSummarymodulefeature_summaryAPI learned to accept multiple values for theWHAToption and combine them appropriately.The
FindCUDAmodule learned to supportfatbinandcubinmodules.The
FindGTestmodulegtest_add_testsmacro learned a newAUTOoption to automatically read theSOURCEStarget property of the test executable and scan the source files for tests to be added.The
FindGLEWmodule now provides imported targets.The
FindGLUTmodule now provides imported targets.The
FindHgmodule gained a newHg_WC_INFOmacro to help runhgto extract information about a Mercurial work copy.The
FindOpenCLmodule was introduced.The
FindOpenMPmodule learned to support Fortran.The
FindPkgConfigmodule learned to use thePKG_CONFIGenvironment variable value as thepkg-configexecutable, if set.The
FindXercesCmodule was introduced.The
FindZLIBmodule now provides imported targets.The
GenerateExportHeadermodulegenerate_export_headerfunction learned to allow use with Object Libraries.The
InstallRequiredSystemLibrariesmodule gained a newCMAKE_INSTALL_OPENMP_LIBRARIESoption to install MSVC OpenMP runtime libraries.The
UseSWIGmodule learned to detect the module name from.isource files if possible to avoid the need to set theSWIG_MODULE_NAMEsource file property explicitly.The
WriteCompilerDetectionHeadermodule was added to allow creation of a portable header file for compiler optional feature detection.
Generator Expressions¶
New
COMPILE_FEATURESgenerator expressionallows setting build properties based on available compiler features.
CTest¶
The
ctest_coverage()command learned to read variableCTEST_COVERAGE_EXTRA_FLAGSto setCoverageExtraFlags.The
ctest_coverage()command learned to support Intel coverage files with thecodecovtool.The
ctest_memcheck()command learned to support sanitizer modes, includingAddressSanitizer,MemorySanitizer,ThreadSanitizer, andUndefinedBehaviorSanitizer. Options may be set using the newCTEST_MEMORYCHECK_SANITIZER_OPTIONSvariable.
CPack¶
cpack(1)gained anIFWgenerator to package using Qt Framework Installer tools. See theCPack IFW Generator.cpack(1)gained7ZandTXZgenerators supporting lzma-compressed archives.The
CPack DEB Generatorlearned a newCPACK_DEBIAN_COMPRESSION_TYPEvariable to set the tarball compression type.The
CPack WIX Generatorlearned to support aCPACK_WIX_ACLinstalled file property to specify an Access Control List.
Other¶
The
cmake(1)-Eoption learned a newenvcommand.The
cmake(1)-E tarcommand learned to support lzma-compressed files.Object Libraries may now have extra sources that do not compile to object files so long as they would not affect linking of a normal library (e.g.
.datis okay but not.def).Visual Studio generators for VS 8 and later learned to support the
ASM_MASMlanguage.The Visual Studio generators learned to treat
.hlslsource files as High Level Shading Language sources (usingFXCompilein.vcxprojfiles). Source file propertiesVS_SHADER_TYPE,VS_SHADER_MODEL, andVS_SHADER_ENTRYPOINTwere added added to specify the shader type, model, and entry point name.
New Diagnostics¶
Policy
CMP0052introduced to control directories in theINTERFACE_INCLUDE_DIRECTORIESof exported targets.
Deprecated and Removed Features¶
In CMake 3.0 the
target_link_libraries()command accidentally began allowing unquoted arguments to usegenerator expressionscontaining a (;separated) list within them. For example:set(libs B C) target_link_libraries(A PUBLIC $<BUILD_INTERFACE:${libs}>)
This is equivalent to writing:
target_link_libraries(A PUBLIC $<BUILD_INTERFACE:B C>)
and was never intended to work. It did not work in CMake 2.8.12. Such generator expressions should be in quoted arguments:
set(libs B C) target_link_libraries(A PUBLIC "$<BUILD_INTERFACE:${libs}>")
CMake 3.1 again requires the quotes for this to work correctly.
Prior to CMake 3.1 the Makefile generators did not escape
#correctly inside make variable assignments used in generated makefiles, causing them to be treated as comments. This made code like:add_compile_options(-Wno-#pragma-messages)
not work in Makefile generators, but work in other generators. Now it is escaped correctly, making the behavior consistent across generators. However, some projects may have tried to workaround the original bug with code like:
set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wno-\\#pragma-messages")
This added the needed escape for Makefile generators but also caused other generators to pass
-Wno-\#pragma-messagesto the shell, which would work only in POSIX shells. Unfortunately the escaping fix could not be made in a compatible way so this platform- and generator-specific workaround no longer works. Project code may test theCMAKE_VERSIONvariable value to make the workaround version-specific too.Callbacks established by the
variable_watch()command will no longer receive theALLOWED_UNKNOWN_READ_ACCESSaccess type when the undocumentedCMAKE_ALLOW_UNKNOWN_VARIABLE_READ_ACCESSvariable is set. Uninitialized variable accesses will always be reported asUNKNOWN_READ_ACCESS.The
CMakeDetermineVSServicePackmodule now warns that it is deprecated and should not longer be used. Use theCMAKE_<LANG>_COMPILER_VERSIONvariable instead.The
FindITKmodule has been removed altogether. It was a thin-wrapper aroundfind_package(ITK ... NO_MODULE). This produces much clearer error messages when ITK is not found.The
FindVTKmodule has been removed altogether. It was a thin-wrapper aroundfind_package(VTK ... NO_MODULE). This produces much clearer error messages when VTK is not found.The module also provided compatibility support for finding VTK 4.0. This capability has been dropped.
Other Changes¶
The
cmake-gui(1)learned to capture output from child processes started by theexecute_process()command and display it in the output window.The
cmake-language(7)internal implementation of generator expression and list expansion parsers have been optimized and shows non-trivial speedup on large projects.The Makefile generators learned to use response files with GNU tools on Windows to pass library directories and names to the linker.
When generating linker command-lines, CMake now avoids repeating items corresponding to SHARED library targets.
Support for the Open Watcom compiler has been overhauled. The
CMAKE_<LANG>_COMPILER_IDis nowOpenWatcom, and theCMAKE_<LANG>_COMPILER_VERSIONnow uses the Open Watcom external version numbering. The external version numbers are lower than the internal version number by 11.The
cmake-mode.elmajor Emacs editing mode no longer treats_as part of words, making it more consistent with other major modes.