426 lines
16 KiB
ReStructuredText
426 lines
16 KiB
ReStructuredText
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.
|