CMake 3.1 Release Notes¶
Contents
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 univerally 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 an- IFWgenerator to package using Qt Framework Installer tools. See the- CPack IFW Generator.
- cpack(1)gained- 7Zand- TXZgenerators 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 use- generator 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 the- CMAKE_VERSIONvariable value to make the workaround version-specific too.
- Callbacks established by the - variable_watch()command will no longer receive the- ALLOWED_UNKNOWN_READ_ACCESSaccess type when the undocumented- CMAKE_ALLOW_UNKNOWN_VARIABLE_READ_ACCESSvariable is set. Uninitialized variable accesses will always be reported as- UNKNOWN_READ_ACCESS.
- The - CMakeDetermineVSServicePackmodule now warns that it is deprecated and should not longer be used. Use the- CMAKE_<LANG>_COMPILER_VERSIONvariable instead.
- The - FindITKmodule has been removed altogether. It was a thin-wrapper around- find_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 around- find_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.
