CMake 3.1 Release Notes

Contents

• CMake 3.1 Release Notes
  • Documentation Changes
  • New Features
    • Generators
      • Windows Phone and Windows Store
      • NVIDIA Nsight Tegra
    • Syntax
    • Commands
    • Variables
    • Properties
    • Modules
    • Generator Expressions
    • CTest
    • CPack
    • Other
  • New Diagnostics
  • Deprecated and Removed Features
  • Other Changes

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 2015 generator 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_NAME variable to WindowsPhone or WindowsStore on the cmake(1) command-line or in a CMAKE_TOOLCHAIN_FILE to activate these platforms. Also set CMAKE_SYSTEM_VERSION to 8.0 or 8.1 to 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_NAME variable to Android on the cmake(1) command-line or in a CMAKE_TOOLCHAIN_FILE to 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_REGISTRY variable to skip exporting the package.
• The file(STRINGS) command gained a new ENCODING option to enable extraction of UTF-8 strings.
• The find_package() command learned to check the CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY and CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY variables to skip searching the package registries.
• The get_property() command learned a new INSTALL scope for properties.
• The install() command learned a MESSAGE_NEVER option to avoid output during installation.
• The set_property() command learned a new INSTALL scope for properties.
• The string() command learned a new GENEX_STRIP subcommand which removes generator expression.
• The string() command learned a new UUID subcommand to generate a univerally unique identifier.
• New target_compile_features() command allows populating the COMPILE_FEATURES target property, just like any other build variable.
• The target_sources() command was added to add to the SOURCES target property.

Variables

• The Visual Studio generators for versions 8 (2005) and above learned to read the target platform name from a new CMAKE_GENERATOR_PLATFORM variable 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 -A option, e.g. -G "Visual Studio 12 2013" -A x64.
• The CMAKE_GENERATOR_TOOLSET variable may now be initialized in a toolchain file specified by the CMAKE_TOOLCHAIN_FILE variable. This is useful when cross-compiling with the Xcode or Visual Studio generators.
• The CMAKE_INSTALL_MESSAGE variable was introduced to optionally reduce output installation.

Properties

• New CXX_STANDARD and CXX_EXTENSIONS target properties may specify values which CMake uses to compute required compile options such as -std=c++11 or -std=gnu++11. The CMAKE_CXX_STANDARD and CMAKE_CXX_EXTENSIONS variables may be set to initialize the target properties.
• New C_STANDARD and C_EXTENSIONS target properties may specify values which CMake uses to compute required compile options such as -std=c11 or -std=gnu11. The CMAKE_C_STANDARD and CMAKE_C_EXTENSIONS variables may be set to initialize the target properties.
• New COMPILE_FEATURES target 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_NAME and COMPILE_PDB_OUTPUT_DIRECTORY target properties were introduced to specify the MSVC compiler program database file location (cl /Fd). This complements the existing PDB_NAME and PDB_OUTPUT_DIRECTORY target properties that specify the linker program database file location (link /pdb).
• The INTERFACE_LINK_LIBRARIES target property now supports a $<LINK_ONLY:...> generator expression.
• A new INTERFACE_SOURCES target property was introduced. This is consumed by dependent targets, which compile and link the listed sources.
• The SOURCES target property now contains generator expression such as TARGET_OBJECTS when read at configure time, if policy CMP0051 is NEW.
• The SOURCES target 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 SOURCES target property. The CMAKE_DEBUG_TARGET_PROPERTIES variable may be used to trace the origin of sources.
• A VS_DEPLOYMENT_CONTENT source 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_LOCATION source 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_COMPONENT target property was created to tell Visual Studio generators to compile a shared library as a Windows Runtime (WinRT) component.
• The Xcode generator learned to check source file properties XCODE_EXPLICIT_FILE_TYPE and XCODE_LAST_KNOWN_FILE_TYPE for a custom Xcode file reference type.

Modules

• The BundleUtilities module learned to resolve and replace @rpath placeholders on OS X to correctly bundle applications using them.
• The CMakePackageConfigHelpers module configure_package_config_file() command learned a new INSTALL_PREFIX option to generate package configuration files meant for a prefix other than CMAKE_INSTALL_PREFIX.
• The CheckFortranSourceCompiles module was added to provide a CHECK_Fortran_SOURCE_COMPILES macro.
• The ExternalData module 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 ExternalProject module learned to support lzma-compressed source tarballs with .7z, .tar.xz, and .txz extensions.
• The ExternalProject module ExternalProject_Add command learned a new BUILD_ALWAYS option to cause the external project build step to run every time the host project is built.
• The ExternalProject module ExternalProject_Add command learned a new EXCLUDE_FROM_ALL option to cause the external project target to have the EXCLUDE_FROM_ALL target property set.
• The ExternalProject module ExternalProject_Add_Step command learned a new EXCLUDE_FROM_MAIN option to cause the step to not be a direct dependency of the main external project target.
• The ExternalProject module ExternalProject_Add command learned a new DOWNLOAD_NO_PROGRESS option to disable progress output while downloading the source tarball.
• The FeatureSummary module feature_summary API learned to accept multiple values for the WHAT option and combine them appropriately.
• The FindCUDA module learned to support fatbin and cubin modules.
• The FindGTest module gtest_add_tests macro learned a new AUTO option to automatically read the SOURCES target property of the test executable and scan the source files for tests to be added.
• The FindGLEW module now provides imported targets.
• The FindGLUT module now provides imported targets.
• The FindHg module gained a new Hg_WC_INFO macro to help run hg to extract information about a Mercurial work copy.
• The FindOpenCL module was introduced.
• The FindOpenMP module learned to support Fortran.
• The FindPkgConfig module learned to use the PKG_CONFIG environment variable value as the pkg-config executable, if set.
• The FindXercesC module was introduced.
• The FindZLIB module now provides imported targets.
• The GenerateExportHeader module generate_export_header function learned to allow use with Object Libraries.
• The InstallRequiredSystemLibraries module gained a new CMAKE_INSTALL_OPENMP_LIBRARIES option to install MSVC OpenMP runtime libraries.
• The UseSWIG module learned to detect the module name from .i source files if possible to avoid the need to set the SWIG_MODULE_NAME source file property explicitly.
• The WriteCompilerDetectionHeader module was added to allow creation of a portable header file for compiler optional feature detection.

Generator Expressions

• New COMPILE_FEATURES generator expression allows setting build properties based on available compiler features.

CTest

• The ctest_coverage() command learned to read variable CTEST_COVERAGE_EXTRA_FLAGS to set CoverageExtraFlags.
• The ctest_coverage() command learned to support Intel coverage files with the codecov tool.
• 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_OPTIONS variable.

CPack

• cpack(1) gained an IFW generator to package using Qt Framework Installer tools. See the CPack IFW Generator.
• cpack(1) gained 7Z and TXZ generators supporting lzma-compressed archives.
• The CPack DEB Generator learned a new CPACK_DEBIAN_COMPRESSION_TYPE variable to set the tarball compression type.
• The CPack WIX Generator learned to support a CPACK_WIX_ACL installed file property to specify an Access Control List.

Other

• The cmake(1) -E option learned a new env command.
• The cmake(1) -E tar command 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. .dat is okay but not .def).
• Visual Studio generators for VS 8 and later learned to support the ASM_MASM language.
• The Visual Studio generators learned to treat .hlsl source files as High Level Shading Language sources (using FXCompile in .vcxproj files). Source file properties VS_SHADER_TYPE, VS_SHADER_MODEL, and VS_SHADER_ENTRYPOINT were added added to specify the shader type, model, and entry point name.

New Diagnostics

• Policy CMP0052 introduced to control directories in the INTERFACE_INCLUDE_DIRECTORIES of exported targets.

Deprecated and Removed Features

• In CMake 3.0 the target_link_libraries() command accidentally began allowing unquoted arguments to use generator expressions containing 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-messages to 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_VERSION variable value to make the workaround version-specific too.

• Callbacks established by the variable_watch() command will no longer receive the ALLOWED_UNKNOWN_READ_ACCESS access type when the undocumented CMAKE_ALLOW_UNKNOWN_VARIABLE_READ_ACCESS variable is set. Uninitialized variable accesses will always be reported as UNKNOWN_READ_ACCESS.

• The CMakeDetermineVSServicePack module now warns that it is deprecated and should not longer be used. Use the CMAKE_<LANG>_COMPILER_VERSION variable instead.

• The FindITK module 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 FindVTK module 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_ID is now OpenWatcom, and the CMAKE_<LANG>_COMPILER_VERSION now uses the Open Watcom external version numbering. The external version numbers are lower than the internal version number by 11.
• The cmake-mode.el major Emacs editing mode no longer treats _ as part of words, making it more consistent with other major modes.