CMake 3.1 Release Notes | |
*********************** | |
.. only:: html | |
.. contents:: | |
Changes made since CMake 3.0 include the following. | |
Documentation Changes | |
===================== | |
* A new :manual:`cmake-compile-features(7)` manual was added. | |
New Features | |
============ | |
Generators | |
---------- | |
* The :generator:`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 | |
:variable:`CMAKE_SYSTEM_NAME` variable to ``WindowsPhone`` | |
or ``WindowsStore`` on the :manual:`cmake(1)` command-line | |
or in a :variable:`CMAKE_TOOLCHAIN_FILE` to activate these platforms. | |
Also set :variable:`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 :variable:`CMAKE_SYSTEM_NAME` variable to ``Android`` on the | |
:manual:`cmake(1)` command-line or in a :variable:`CMAKE_TOOLCHAIN_FILE` | |
to activate this platform. | |
Syntax | |
------ | |
* The :manual:`cmake-language(7)` syntax for :ref:`Variable References` and | |
:ref:`Escape Sequences` was simplified in order to allow a much faster | |
implementation. See policy :policy:`CMP0053`. | |
* The :command:`if` command no longer automatically dereferences | |
variables named in quoted or bracket arguments. See policy | |
:policy:`CMP0054`. | |
Commands | |
-------- | |
* The :command:`add_custom_command` command learned to interpret | |
:manual:`cmake-generator-expressions(7)` in arguments to ``DEPENDS``. | |
* The :command:`export(PACKAGE)` command learned to check the | |
:variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable to skip | |
exporting the package. | |
* The :command:`file(STRINGS)` command gained a new ``ENCODING`` | |
option to enable extraction of ``UTF-8`` strings. | |
* The :command:`find_package` command learned to check the | |
:variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` and | |
:variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` | |
variables to skip searching the package registries. | |
* The :command:`get_property` command learned a new ``INSTALL`` scope | |
for properties. | |
* The :command:`install` command learned a ``MESSAGE_NEVER`` option | |
to avoid output during installation. | |
* The :command:`set_property` command learned a new ``INSTALL`` scope | |
for properties. | |
* The :command:`string` command learned a new ``GENEX_STRIP`` subcommand | |
which removes | |
:manual:`generator expression <cmake-generator-expressions(7)>`. | |
* The :command:`string` command learned a new ``UUID`` subcommand | |
to generate a univerally unique identifier. | |
* New :command:`target_compile_features` command allows populating the | |
:prop_tgt:`COMPILE_FEATURES` target property, just like any other | |
build variable. | |
* The :command:`target_sources` command was added to add to the | |
:prop_tgt:`SOURCES` target property. | |
Variables | |
--------- | |
* The Visual Studio generators for versions 8 (2005) and above | |
learned to read the target platform name from a new | |
:variable:`CMAKE_GENERATOR_PLATFORM` variable when it is | |
not specified as part of the generator name. The platform | |
name may be specified on the :manual:`cmake(1)` command line | |
with the ``-A`` option, e.g. ``-G "Visual Studio 12 2013" -A x64``. | |
* The :variable:`CMAKE_GENERATOR_TOOLSET` variable may now be | |
initialized in a toolchain file specified by the | |
:variable:`CMAKE_TOOLCHAIN_FILE` variable. This is useful | |
when cross-compiling with the Xcode or Visual Studio | |
generators. | |
* The :variable:`CMAKE_INSTALL_MESSAGE` variable was introduced to | |
optionally reduce output installation. | |
Properties | |
---------- | |
* New :prop_tgt:`CXX_STANDARD` and :prop_tgt:`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 | |
:variable:`CMAKE_CXX_STANDARD` and :variable:`CMAKE_CXX_EXTENSIONS` | |
variables may be set to initialize the target properties. | |
* New :prop_tgt:`C_STANDARD` and :prop_tgt:`C_EXTENSIONS` target | |
properties may specify values which CMake uses to compute required | |
compile options such as ``-std=c11`` or ``-std=gnu11``. The | |
:variable:`CMAKE_C_STANDARD` and :variable:`CMAKE_C_EXTENSIONS` | |
variables may be set to initialize the target properties. | |
* New :prop_tgt:`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 :prop_tgt:`COMPILE_PDB_NAME` and | |
:prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY` target properties | |
were introduced to specify the MSVC compiler program database | |
file location (``cl /Fd``). This complements the existing | |
:prop_tgt:`PDB_NAME` and :prop_tgt:`PDB_OUTPUT_DIRECTORY` | |
target properties that specify the linker program database | |
file location (``link /pdb``). | |
* The :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property now supports | |
a ``$<LINK_ONLY:...>`` | |
:manual:`generator expression <cmake-generator-expressions(7)>`. | |
* A new :prop_tgt:`INTERFACE_SOURCES` target property was introduced. This is | |
consumed by dependent targets, which compile and link the listed sources. | |
* The :prop_tgt:`SOURCES` target property now contains | |
:manual:`generator expression <cmake-generator-expressions(7)>` | |
such as ``TARGET_OBJECTS`` when read at configure time, if | |
policy :policy:`CMP0051` is ``NEW``. | |
* The :prop_tgt:`SOURCES` target property now generally supports | |
:manual:`generator expression <cmake-generator-expressions(7)>`. The | |
generator expressions may be used in the :command:`add_library` and | |
:command:`add_executable` commands. | |
* It is now possible to write and append to the :prop_tgt:`SOURCES` target | |
property. The :variable:`CMAKE_DEBUG_TARGET_PROPERTIES` variable may be | |
used to trace the origin of sources. | |
* A :prop_sf:`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 :prop_sf:`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 :prop_tgt:`VS_WINRT_COMPONENT` target property was created to | |
tell Visual Studio generators to compile a shared library as a | |
Windows Runtime (WinRT) component. | |
* The :generator:`Xcode` generator learned to check source | |
file properties :prop_sf:`XCODE_EXPLICIT_FILE_TYPE` and | |
:prop_sf:`XCODE_LAST_KNOWN_FILE_TYPE` for a custom Xcode | |
file reference type. | |
Modules | |
------- | |
* The :module:`BundleUtilities` module learned to resolve and replace | |
``@rpath`` placeholders on OS X to correctly bundle applications | |
using them. | |
* The :module:`CMakePackageConfigHelpers` module | |
:command:`configure_package_config_file` command learned a new | |
``INSTALL_PREFIX`` option to generate package configuration files | |
meant for a prefix other than :variable:`CMAKE_INSTALL_PREFIX`. | |
* The :module:`CheckFortranSourceCompiles` module was added to | |
provide a ``CHECK_Fortran_SOURCE_COMPILES`` macro. | |
* The :module:`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 :module:`ExternalProject` module learned to support lzma-compressed | |
source tarballs with ``.7z``, ``.tar.xz``, and ``.txz`` extensions. | |
* The :module:`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 :module:`ExternalProject` module ``ExternalProject_Add`` command | |
learned a new ``EXCLUDE_FROM_ALL`` option to cause the external | |
project target to have the :prop_tgt:`EXCLUDE_FROM_ALL` target | |
property set. | |
* The :module:`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 :module:`ExternalProject` module ``ExternalProject_Add`` command | |
learned a new ``DOWNLOAD_NO_PROGRESS`` option to disable progress | |
output while downloading the source tarball. | |
* The :module:`FeatureSummary` module ``feature_summary`` API | |
learned to accept multiple values for the ``WHAT`` option and | |
combine them appropriately. | |
* The :module:`FindCUDA` module learned to support ``fatbin`` and ``cubin`` | |
modules. | |
* The :module:`FindGTest` module ``gtest_add_tests`` macro learned | |
a new ``AUTO`` option to automatically read the :prop_tgt:`SOURCES` | |
target property of the test executable and scan the source files | |
for tests to be added. | |
* The :module:`FindGLEW` module now provides imported targets. | |
* The :module:`FindGLUT` module now provides imported targets. | |
* The :module:`FindHg` module gained a new ``Hg_WC_INFO`` macro to | |
help run ``hg`` to extract information about a Mercurial work copy. | |
* The :module:`FindOpenCL` module was introduced. | |
* The :module:`FindOpenMP` module learned to support Fortran. | |
* The :module:`FindPkgConfig` module learned to use the ``PKG_CONFIG`` | |
environment variable value as the ``pkg-config`` executable, if set. | |
* The :module:`FindXercesC` module was introduced. | |
* The :module:`FindZLIB` module now provides imported targets. | |
* The :module:`GenerateExportHeader` module ``generate_export_header`` | |
function learned to allow use with :ref:`Object Libraries`. | |
* The :module:`InstallRequiredSystemLibraries` module gained a new | |
``CMAKE_INSTALL_OPENMP_LIBRARIES`` option to install MSVC OpenMP | |
runtime libraries. | |
* The :module:`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 :module:`WriteCompilerDetectionHeader` module was added to allow | |
creation of a portable header file for compiler optional feature detection. | |
Generator Expressions | |
--------------------- | |
* New ``COMPILE_FEATURES`` | |
:manual:`generator expression <cmake-generator-expressions(7)>` allows | |
setting build properties based on available compiler features. | |
CTest | |
----- | |
* The :command:`ctest_coverage` command learned to read variable | |
``CTEST_COVERAGE_EXTRA_FLAGS`` to set ``CoverageExtraFlags``. | |
* The :command:`ctest_coverage` command learned to support | |
Intel coverage files with the ``codecov`` tool. | |
* The :command:`ctest_memcheck` command learned to support sanitizer | |
modes, including ``AddressSanitizer``, ``MemorySanitizer``, | |
``ThreadSanitizer``, and ``UndefinedBehaviorSanitizer``. | |
Options may be set using the new | |
:variable:`CTEST_MEMORYCHECK_SANITIZER_OPTIONS` variable. | |
CPack | |
----- | |
* :manual:`cpack(1)` gained an ``IFW`` generator to package using | |
Qt Framework Installer tools. See the :module:`CPackIFW` module. | |
* :manual:`cpack(1)` gained ``7Z`` and ``TXZ`` generators supporting | |
lzma-compressed archives. | |
* The :module:`CPackDeb` module learned a new | |
:variable:`CPACK_DEBIAN_COMPRESSION_TYPE` variable to set the | |
tarball compression type. | |
* The :manual:`cpack(1)` ``WiX`` generator learned to support | |
a :prop_inst:`CPACK_WIX_ACL` installed file property to | |
specify an Access Control List. | |
Other | |
----- | |
* The :manual:`cmake(1)` ``-E`` option learned a new ``env`` command. | |
* The :manual:`cmake(1)` ``-E tar`` command learned to support | |
lzma-compressed files. | |
* :ref:`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 | |
:prop_sf:`VS_SHADER_TYPE`, :prop_sf:`VS_SHADER_MODEL`, and | |
:prop_sf:`VS_SHADER_ENTRYPOINT` were added added to specify the | |
shader type, model, and entry point name. | |
New Diagnostics | |
=============== | |
* Policy :policy:`CMP0052` introduced to control directories in the | |
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of exported targets. | |
Deprecated and Removed Features | |
=============================== | |
* In CMake 3.0 the :command:`target_link_libraries` command | |
accidentally began allowing unquoted arguments to use | |
:manual:`generator expressions <cmake-generator-expressions(7)>` | |
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 :variable:`CMAKE_VERSION` | |
variable value to make the workaround version-specific too. | |
* Callbacks established by the :command:`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 :module:`CMakeDetermineVSServicePack` module now warns that | |
it is deprecated and should not longer be used. Use the | |
:variable:`CMAKE_<LANG>_COMPILER_VERSION` variable instead. | |
* The :module:`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 :module:`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 :manual:`cmake-gui(1)` learned to capture output from child | |
processes started by the :command:`execute_process` command | |
and display it in the output window. | |
* The :manual:`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 :variable:`CMAKE_<LANG>_COMPILER_ID` is now ``OpenWatcom``, | |
and the :variable:`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. |