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 to- WindowsPhoneor- WindowsStoreon the- cmake(1)command-line or in a- CMAKE_TOOLCHAIN_FILEto activate these platforms. Also set- CMAKE_SYSTEM_VERSIONto- 8.0or- 8.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 to- Androidon the- cmake(1)command-line or in a- CMAKE_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 policy- CMP0053.
- The - if()command no longer automatically dereferences variables named in quoted or bracket arguments. See policy- CMP0054.
Commands¶
- The - add_custom_command()command learned to interpret- cmake-generator-expressions(7)in arguments to- DEPENDS.
- The - export(PACKAGE)command learned to check the- CMAKE_EXPORT_NO_PACKAGE_REGISTRYvariable to skip exporting the package.
- The - file(STRINGS)command gained a new- ENCODINGoption to enable extraction of- UTF-8strings.
- The - find_package()command learned to check the- CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRYand- CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRYvariables to skip searching the package registries.
- The - get_property()command learned a new- INSTALLscope for properties.
- The - install()command learned a- MESSAGE_NEVERoption to avoid output during installation.
- The - set_property()command learned a new- INSTALLscope for properties.
- The - string()command learned a new- GENEX_STRIPsubcommand which removes- generator expression.
- The - string()command learned a new- UUIDsubcommand to generate a universally unique identifier.
- New - target_compile_features()command allows populating the- COMPILE_FEATUREStarget property, just like any other build variable.
- The - target_sources()command was added to add to the- SOURCEStarget 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 the- cmake(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 the- CMAKE_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_STANDARDand- CXX_EXTENSIONStarget properties may specify values which CMake uses to compute required compile options such as- -std=c++11or- -std=gnu++11. The- CMAKE_CXX_STANDARDand- CMAKE_CXX_EXTENSIONSvariables may be set to initialize the target properties.
- New - C_STANDARDand- C_EXTENSIONStarget properties may specify values which CMake uses to compute required compile options such as- -std=c11or- -std=gnu11. The- CMAKE_C_STANDARDand- CMAKE_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_NAMEand- COMPILE_PDB_OUTPUT_DIRECTORYtarget properties were introduced to specify the MSVC compiler program database file location (- cl /Fd). This complements the existing- PDB_NAMEand- PDB_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 contains- generator expressionsuch as- TARGET_OBJECTSwhen read at configure time, if policy- CMP0051is- NEW.
- The - SOURCEStarget property now generally supports- generator expression. The generator expressions may be used in the- add_library()and- add_executable()commands.
- It is now possible to write and append to the - SOURCEStarget property. The- CMAKE_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 properties- XCODE_EXPLICIT_FILE_TYPEand- XCODE_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 - CMakePackageConfigHelpersmodule- configure_package_config_file()command learned a new- INSTALL_PREFIXoption to generate package configuration files meant for a prefix other than- CMAKE_INSTALL_PREFIX.
- The - CheckFortranSourceCompilesmodule was added to provide a- CHECK_Fortran_SOURCE_COMPILESmacro.
- The - ExternalDatamodule learned to tolerate a- DATA{}reference to a missing source file with a warning instead of rejecting it with an error. This helps developers write new- DATA{}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 - ExternalProjectmodule- ExternalProject_Addcommand learned a new- BUILD_ALWAYSoption to cause the external project build step to run every time the host project is built.
- The - ExternalProjectmodule- ExternalProject_Addcommand learned a new- EXCLUDE_FROM_ALLoption to cause the external project target to have the- EXCLUDE_FROM_ALLtarget property set.
- The - ExternalProjectmodule- ExternalProject_Add_Stepcommand learned a new- EXCLUDE_FROM_MAINoption to cause the step to not be a direct dependency of the main external project target.
- The - ExternalProjectmodule- ExternalProject_Addcommand learned a new- DOWNLOAD_NO_PROGRESSoption to disable progress output while downloading the source tarball.
- The - FeatureSummarymodule- feature_summaryAPI learned to accept multiple values for the- WHAToption and combine them appropriately.
- The - FindCUDAmodule learned to support- fatbinand- cubinmodules.
- The - FindGTestmodule- gtest_add_testsmacro learned a new- AUTOoption to automatically read the- SOURCEStarget 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 new- Hg_WC_INFOmacro to help run- hgto extract information about a Mercurial work copy.
- The - FindOpenCLmodule was introduced.
- The - FindOpenMPmodule learned to support Fortran.
- The - FindPkgConfigmodule learned to use the- PKG_CONFIGenvironment variable value as the- pkg-configexecutable, if set.
- The - FindXercesCmodule was introduced.
- The - FindZLIBmodule now provides imported targets.
- The - GenerateExportHeadermodule- generate_export_headerfunction learned to allow use with Object Libraries.
- The - InstallRequiredSystemLibrariesmodule gained a new- CMAKE_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 the- SWIG_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_FEATURES- generator expressionallows setting build properties based on available compiler features.
CTest¶
- The - ctest_coverage()command learned to read variable- CTEST_COVERAGE_EXTRA_FLAGSto set- CoverageExtraFlags.
- The - ctest_coverage()command learned to support Intel coverage files with the- codecovtool.
- The - ctest_memcheck()command learned to support sanitizer modes, including- AddressSanitizer,- MemorySanitizer,- ThreadSanitizer, and- UndefinedBehaviorSanitizer. Options may be set using the new- CTEST_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 new- CPACK_DEBIAN_COMPRESSION_TYPEvariable to set the tarball compression type.
- The - CPack WIX Generatorlearned to support a- CPACK_WIX_ACLinstalled file property to specify an Access Control List.
Other¶
- The - cmake(1)- -Eoption learned a new- envcommand.
- 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 (using- FXCompilein- .vcxprojfiles). Source file properties- VS_SHADER_TYPE,- VS_SHADER_MODEL, and- VS_SHADER_ENTRYPOINTwere added added to specify the shader type, model, and entry point name.
New Diagnostics¶
- Policy - CMP0052introduced to control directories in the- INTERFACE_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 the- execute_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 now- OpenWatcom, and the- CMAKE_<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.
