Commit 85c2bb72 authored by Brad King's avatar Brad King Committed by Kitware Robot
Browse files

Merge topic 'doc-3.19-relnotes'

e1ab55b4 Help: Update Sphinx versionadded directives for 3.19 release
1b6c0b37 Help: Organize and revise 3.19 release notes
b81cb27f

 Help: Consolidate 3.19 release notes
Acked-by: Kitware Robot's avatarKitware Robot <kwrobot@kitware.com>
Merge-request: !5345
parents 8f2ba9a3 e1ab55b4
Pipeline #193423 canceled with stages
in 9 minutes and 52 seconds
CMP0110
-------
.. versionadded:: 3.19
:command:`add_test` supports arbitrary characters in test names.
:command:`add_test` can now (officially) create tests with whitespace and
......
OPTIMIZE_DEPENDENCIES
---------------------
.. versionadded:: 3.19
Activates dependency optimization of static and object libraries.
When this property is set to true, some dependencies for a static or object
......
XCODE_LINK_BUILD_PHASE_MODE
---------------------------
.. versionadded:: 3.19
When using the :generator:`Xcode` generator, libraries to be linked will be
specified in the Xcode project file using either the "Link Binary With
Libraries" build phase or directly as linker flags. The former allows Xcode
......
CMake 3.19 Release Notes
************************
.. only:: html
.. contents::
Changes made since CMake 3.18 include the following.
New Features
============
Presets
-------
* :manual:`cmake(1)` and :manual:`cmake-gui(1)` now recognize
``CMakePresets.json`` and ``CMakeUserPresets.json`` files.
Generators
----------
* The :generator:`Xcode` generator now uses the Xcode "new build system"
when generating for Xcode 12.0 or higher.
See the :variable:`CMAKE_XCODE_BUILD_SYSTEM` variable.
One may use ``-T buildsystem=1`` to switch to the legacy build system.
* The :generator:`Xcode` generator gained support for linking libraries and
frameworks via the *Link Binaries With Libraries* build phase instead of
always by embedding linker flags directly. This behavior is controlled by
a new :prop_tgt:`XCODE_LINK_BUILD_PHASE_MODE` target property, which is
initialized by a new :variable:`CMAKE_XCODE_LINK_BUILD_PHASE_MODE`
variable.
* The :ref:`Visual Studio Generators` for VS 2015 and above gained support
for the Visual Studio Tools for Android. One may now set
:variable:`CMAKE_SYSTEM_NAME` to ``Android`` to generate ``.vcxproj`` files
for the Android tools.
Languages
---------
* CMake learned to support ``ISPC`` as a first-class language that can be
enabled via the :command:`project` and :command:`enable_language` commands.
``ISPC`` is currently supported by the :ref:`Makefile Generators`
and the :generator:`Ninja` generator on Linux, macOS, and Windows
using the Intel ISPC compiler.
* ``CUDA`` language support for Clang now includes:
- separable compilation (:prop_tgt:`CUDA_SEPARABLE_COMPILATION`), and
- finding scattered toolkit installations when cross-compiling.
File-Based API
--------------
* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has
been updated to 2.2.
* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object
gained a new ``languageStandard`` field in the ``compileGroups`` objects.
Command-Line
------------
* The :manual:`cmake(1)` command-line tool's ``--install`` mode gained a
``--default-directory-permissions`` option.
* :manual:`cmake(1)` gained a ``-E create_hardlink`` command-line tool
that can be used to create hardlinks between files.
GUI
---
* The :manual:`CMake GUI <cmake-gui(1)>` now has an environment variable
editor.
Commands
--------
* The :command:`add_test` command now (officially) supports whitespace and
other special characters in the name for the test it creates.
See policy :policy:`CMP0110`.
* The :command:`cmake_language` command gained a ``DEFER`` mode to
schedule command calls to occur at the end of processing a directory.
* The :command:`cmake_path` command was added for operations on
filesystem paths.
* The :command:`configure_file` command gained a ``NO_SOURCE_PERMISSIONS``
option to suppress copying the input file's permissions to the output file.
* The :command:`execute_process` command gained a ``COMMAND_ERROR_IS_FATAL``
option to specify a fatal error.
* The :command:`file(ARCHIVE_CREATE)` command gained a ``COMPRESSION_LEVEL``
option to specify the compression level.
* The :command:`file(CHMOD)` and :command:`file(CHMOD_RECURSE)` subcommands
were added to set permissions of files and directories.
* The :command:`file(DOWNLOAD)` command ``<file>`` argument is now
optional. If it is not specified, the file is not saved.
* The :command:`file(GENERATE)` command gained a new ``TARGET`` keyword to
support resolving target-dependent generator expressions.
* The :command:`file` gained sub-command `REAL_PATH` to compute a path with
symlinks resolved.
* The :command:`find_package` command learned to handle a version range.
* The :command:`separate_arguments` command gained new ``PROGRAM`` option to
search program.
* The :command:`set_property`, :command:`get_property`,
and :command:`get_directory_property` commands' ``DIRECTORY``
options now accept references to binary directory paths,
such as the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
* The :command:`string` command gained set of new ``JSON`` sub commands
to provide JSON parsing capabilities.
Variables
---------
* The :variable:`CMAKE_CLANG_VFS_OVERLAY` variable was added to tell
Clang to use a VFS overlay to support the Windows SDK when
cross-compiling from hosts with case-sensitive filesystems.
* The :variable:`CMAKE_MFC_FLAG` variable now supports generator expressions.
* The :variable:`CMAKE_OPTIMIZE_DEPENDENCIES` variable was added to
initialize the new :prop_tgt:`OPTIMIZE_DEPENDENCIES` target property and
avoid unnecessarily building dependencies for a static library.
* The :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` variable
was added to tell the :ref:`Visual Studio Generators` what maximum
version of the Windows SDK to choose.
Properties
----------
* The :prop_tgt:`EXCLUDE_FROM_ALL` target property now supports
:manual:`generator expressions <cmake-generator-expressions(7)>`.
* The :prop_tgt:`OPTIMIZE_DEPENDENCIES` target property was added to
avoid unnecessarily building dependencies for a static library.
* The :prop_tgt:`PCH_INSTANTIATE_TEMPLATES` target property was added to enable
template instantiation in the precompiled header. This is enabled by default
and offers a roughly 20% compile time improvement. Currently only supported
by Clang 11.
* The :prop_tgt:`WIN32_EXECUTABLE` target property now supports
:manual:`generator expressions <cmake-generator-expressions(7)>`.
Modules
-------
* The :module:`CheckCompilerFlag` module has been added to
generalize :module:`CheckCCompilerFlag` and
:module:`CheckCXXCompilerFlag` to more languages.
It also supports the ``CUDA`` and ``ISPC`` languages.
* The :module:`CheckLinkerFlag` module now supports the ``CUDA`` language.
* The :module:`CheckSourceCompiles` module has been added to
generalize :module:`CheckCSourceCompiles` and
:module:`CheckCXXSourceCompiles` to more languages.
It also supports the ``CUDA`` and ``ISPC`` languages.
* The :module:`CheckSourceRuns` module has been added to
generalize :module:`CheckCSourceRuns` and
:module:`CheckCXXSourceRuns` to more languages.
It also supports the ``CUDA`` language.
* :module:`CMakePackageConfigHelpers` module learned to manage version range.
* The :module:`FindCUDAToolkit` module gained support for finding CUDA
toolkits that do not contain ``nvcc``, as well as for finding scattered
toolkit installations when cross-compiling.
* The :module:`FindPackageHandleStandardArgs` module learned to handle
version range. It also gained the ``find_package_check_version()`` command to
check the validity of a version against version-related arguments of
:command:`find_package` command.
* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
modules gained the capability to manage a version range.
* The :module:`FindSDL` module now provides:
* imported target ``SDL::SDL``,
* result variables ``SDL_LIBRARIES`` and ``SDL_INCLUDE_DIRS``,
* version variables ``SDL_VERSION``, ``SDL_VERSION_MAJOR``
``SDL_VERSION_MINOR``, and ``SDL_VERSION_PATCH``.
* :module:`FindSWIG` module gains the capability to manage a version range.
* The :module:`FindTIFF` module gained a ``CXX`` component to
find the ``tiffxx`` library containing C++ bindings.
* The :module:`FindVulkan` module now provides a ``Vulkan::glslc`` imported
target and associated ``Vulkan_GLSLC_EXECUTABLE`` variable which contain
the path to the GLSL SPIR-V compiler.
* :module:`UseSWIG` module gains new source file properties ``OUTPUT_DIR`` and
``OUTFILE_DIR`` to manage output directories on per source basis.
CTest
-----
* :manual:`ctest(1)` now supports ``compute-sanitizer`` (``cuda-memcheck``) as
``CTEST_MEMORYCHECK_COMMAND``. The different tools (memcheck, racecheck,
synccheck, initcheck) supplied by ``compute-sanitizer`` can be selected by
adding appropriate flags to the ``CTEST_MEMORYCHECK_COMMAND_OPTIONS``
variable. The default flags are ``--tool memcheck --leak-check full``.
CPack
-----
* CPack gained the :variable:`CPACK_PRE_BUILD_SCRIPTS`,
:variable:`CPACK_POST_BUILD_SCRIPTS`, and :variable:`CPACK_PACKAGE_FILES`
variables.
* The :cpack_gen:`CPack External Generator` gained the
:variable:`CPACK_EXTERNAL_BUILT_PACKAGES` variable.
* The :cpack_gen:`CPack WIX Generator` gained a
:variable:`CPACK_WIX_CUSTOM_XMLNS` option to specify custom XML namespaces.
Other
-----
* :ref:`Interface Libraries` may now have source files added via
:command:`add_library` or :command:`target_sources`. Those
with sources will be generated as part of the build system.
Deprecated and Removed Features
===============================
* Compatibility with versions of CMake older than 2.8.12 is now deprecated
and will be removed from a future version. Calls to
:command:`cmake_minimum_required` or :command:`cmake_policy` that set
the policy version to an older value now issue a deprecation diagnostic.
* An explicit deprecation diagnostic was added for policy ``CMP0071``
(``CMP0071`` and below were already deprecated).
The :manual:`cmake-policies(7)` manual explains that the OLD behaviors
of all policies are deprecated and that projects should port to the
NEW behaviors.
* macOS SDKs older than 10.5 are no longer supported.
* :manual:`cmake-gui(1)` now requires Qt5.
Support for compiling with Qt4 has been removed.
* The :manual:`cmake(1)` command-line option ``--warn-unused-vars`` has
been removed and is now silently ignored. The option has not worked
correctly since CMake 3.3.
Documentation
=============
The following guides have been added:
* :guide:`IDE Integration Guide`
* :guide:`Importing and Exporting Guide`
Other Changes
=============
* Building for macOS will now use the latest SDK available on the system,
unless the user has explicitly chosen a SDK using
:variable:`CMAKE_OSX_SYSROOT`. The deployment target or system macOS
version will not affect the choice of SDK.
* The :variable:`CMAKE_<LANG>_COMPILER` variable may now be used to
store "mandatory" compiler flags like the :envvar:`CC` and other environment
variables.
* The :variable:`CMAKE_<LANG>_FLAGS_INIT` variable will now be considered
during the compiler identification check if other sources like
:variable:`CMAKE_<LANG>_FLAGS` or :envvar:`CFLAGS` are not set.
* The :command:`find_program` command now requires permission to execute
but not to read the file found. See policy :policy:`CMP0109`.
* An imported target with a missing location now fails during generation
if the location is used. See policy :policy:`CMP0111`.
* The following target-based generator expressions that query for directory or
file name components no longer add a dependency on the evaluated target.
See policy :policy:`CMP0112`.
- ``TARGET_FILE_DIR``
- ``TARGET_LINKER_FILE_BASE_NAME``
- ``TARGET_LINKER_FILE_NAME``
- ``TARGET_LINKER_FILE_DIR``
- ``TARGET_SONAME_FILE_NAME``
- ``TARGET_SONAME_FILE_DIR``
- ``TARGET_PDB_FILE_NAME``
- ``TARGET_PDB_FILE_DIR``
- ``TARGET_BUNDLE_DIR``
- ``TARGET_BUNDLE_CONTENT_DIR``
* :ref:`Makefile Generators` no longer repeat custom commands from target
dependencies. See policy :policy:`CMP0113`.
* The :module:`ExternalProject` module handling of step target dependencies
has been revised. See policy :policy:`CMP0114`.
* The :prop_tgt:`OSX_ARCHITECTURES` target property is now respected
for the ``ASM`` language.
* If ``CUDA`` compiler detection fails with user-specified
:variable:`CMAKE_CUDA_ARCHITECTURES` or
:variable:`CMAKE_CUDA_HOST_COMPILER`, an error is raised.
CMakePackageConfigHelpers-version_range
---------------------------------------
* :module:`CMakePackageConfigHelpers` module learned to manage version range.
CPACK_EXTERNAL_BUILT_PACKAGES
-----------------------------
* :cpack_gen:`CPack External Generator` learned the :variable:`CPACK_EXTERNAL_BUILT_PACKAGES` variable.
EXCLUDE_FROM_ALL-genex
----------------------
* The :prop_tgt:`EXCLUDE_FROM_ALL` target property gained support for
:manual:`generator expressions <cmake-generator-expressions(7)>`.
ExternalProject-steps-refinement
--------------------------------
* The :module:`ExternalProject` module handling of step target dependencies
has been revised. See policy :policy:`CMP0114`.
FPHSA-version_range
-------------------
* The :module:`FindPackageHandleStandardArgs` module learned to handle
version range. It also gained the ``find_package_check_version()`` command to
check the validity of a version against version-related arguments of
:command:`find_package` command.
FindCUDAToolkit-no-nvcc
-----------------------
* The :module:`FindCUDAToolkit` module gained support for finding CUDA toolkits
that do not contain ``nvcc``.
FindPython-version_range
------------------------
* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
modules gained the capability to manage a version range.
FindSDL-update
--------------
* The :module:`FindSDL` module now provides:
* imported target ``SDL::SDL``,
* result variables ``SDL_LIBRARIES`` and ``SDL_INCLUDE_DIRS``,
* version variables ``SDL_VERSION``, ``SDL_VERSION_MAJOR``
``SDL_VERSION_MINOR``, and ``SDL_VERSION_PATCH``.
FindSWIG-version-range
----------------------
* :module:`FindSWIG` module gains the capability to manage a version range.
FindTIFF-tiffxx
---------------
* The :module:`FindTIFF` module gained a ``CXX`` component to
find the ``tiffxx`` library containing C++ bindings.
FindVulkan-glslc
----------------
* The :module:`FindVulkan` module gained a new output variable
``Vulkan_GLSLC_EXECUTABLE`` which contains the path to the
GLSL SPIR-V compiler.
* The :module:`FindVulkan` module gained a new target
``Vulkan::glslc`` which contains the path to the
GLSL SPIR-V compiler.
PCH_INSTANTIATE_TEMPLATES
-------------------------
* The :prop_tgt:`PCH_INSTANTIATE_TEMPLATES` target property was added to enable
template instantiation in the precompiled header. This is enabled by default
and offers a roughly 20% compile time improvement. Currently only supported
by Clang 11.
UseSwig-output-source-properties
--------------------------------
* :module:`UseSWIG` module gains new source file properties ``OUTPUT_DIR`` and
``OUTFILE_DIR`` to manage output directories on per source basis.
add_test-special-chars-in-name
------------------------------
* The :command:`add_test` command now (officially) supports whitespace and
other special characters in the name for the test it creates.
See policy :policy:`CMP0110`.
asm-osx-architectures
---------------------
* The :prop_tgt:`OSX_ARCHITECTURES` target property is now respected for the
``ASM`` language.
binary-dir-props
----------------
* The :command:`set_property`, :command:`get_property`,
and :command:`get_directory_property` commands' ``DIRECTORY``
options now accept references to binary directory paths,
such as the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment