summaryrefslogtreecommitdiffstats
path: root/Help/release/3.18.rst
diff options
context:
space:
mode:
authorBrad King <brad.king@kitware.com>2020-06-03 10:22:15 (GMT)
committerBrad King <brad.king@kitware.com>2020-06-03 10:22:15 (GMT)
commit389ca18289f49a9c1f8f6c412f8642d79d6a1720 (patch)
treeda2cfc765dab7a03eab3ee3933b3afcc4643d80e /Help/release/3.18.rst
parentab6b5c01eaf2c88a9a477f40843947eb23084e20 (diff)
downloadCMake-389ca18289f49a9c1f8f6c412f8642d79d6a1720.zip
CMake-389ca18289f49a9c1f8f6c412f8642d79d6a1720.tar.gz
CMake-389ca18289f49a9c1f8f6c412f8642d79d6a1720.tar.bz2
Help: Organize and revise 3.18 release notes
Add section headers similar to the 3.18 release notes and move each individual bullet into an appropriate section. Revise a few bullets.
Diffstat (limited to 'Help/release/3.18.rst')
-rw-r--r--Help/release/3.18.rst380
1 files changed, 211 insertions, 169 deletions
diff --git a/Help/release/3.18.rst b/Help/release/3.18.rst
index ac10726..71f9d85 100644
--- a/Help/release/3.18.rst
+++ b/Help/release/3.18.rst
@@ -7,137 +7,168 @@ CMake 3.18 Release Notes
Changes made since CMake 3.17 include the following.
-* :command:`add_library` and :command:`add_executable` gain the capability
- to create an ``ALIAS`` to
- non-``GLOBAL`` :ref:`Imported Target <Imported Targets>`.
+New Features
+============
-* Creation of an ``ALIAS`` target overwriting an existing target now raise an
- error. See policy :policy:`CMP0107`.
+Languages
+---------
-* :manual:`ccmake(1)` learned to read a :envvar:`CCMAKE_COLORS`
- environment variable to customize colors.
+* The ``CUDA`` language can now be compiled using Clang.
-* New :module:`CheckLinkerFlag` module has been added to provide a facility to
- check validity of link flags.
+Command-Line
+------------
-* :manual:`cmake-gui(1)` now populates its generator selection
- widget default value from the :envvar:`CMAKE_GENERATOR` environment
- variable. Additionally, environment variables
- :envvar:`CMAKE_GENERATOR_PLATFORM` and :envvar:`CMAKE_GENERATOR_TOOLSET`
- are used to populate their respective widget defaults.
+* :manual:`cmake(1)` gained support for profiling of CMake scripts through
+ the parameters ``--profiling-output`` and ``--profiling-format``.
-* The :command:`cmake_language()` command was added for meta-operations on
- scripted or built-in commands, starting with a mode to ``CALL`` other
- commands, and ``EVAL CODE`` to inplace evaluate a CMake script.
* :manual:`cmake(1)` gained a ``cat`` command line
option that can be used to concatenate files and print them
on standard output.
-* The :cpack_gen:`CPack RPM Generator` gained
- :variable:`CPACK_RPM_PRE_TRANS_SCRIPT_FILE`
- :variable:`CPACK_RPM_POST_TRANS_SCRIPT_FILE`
- variables to specify pre- and post-trans scripts.
+Commands
+--------
-* The :module:`CTestCoverageCollectGCOV` module
- :command:`ctest_coverage_collect_gcov` function gained a
- ``TARBALL_COMPRESSION`` option to control compression of the
- tarball of collected results.
+* The :command:`add_library` and :command:`add_executable` commands
+ learned to create :ref:`Alias Targets` referencing non-``GLOBAL``
+ :ref:`Imported Targets`.
-* :manual:`ctest(1)` now logs environment variables that it sets for each test,
- either due to the :prop_test:`ENVIRONMENT` property or the
- :ref:`resource allocation <ctest-resource-allocation>` feature, and submits
- this log to CDash. It does not log environment variables that were set
- outside of CTest.
+* The :command:`cmake_language()` command was added for meta-operations on
+ scripted or built-in commands, starting with a mode to ``CALL`` other
+ commands, and ``EVAL CODE`` to inplace evaluate a CMake script.
-* :manual:`ctest(1)` gained a new :variable:`CTEST_RESOURCE_SPEC_FILE`
- variable, which can be used to specify a
- :ref:`resource specification file <ctest-resource-specification-file>`.
+* The :command:`execute_process` command gained the ``ECHO_OUTPUT_VARIABLE``
+ and ``ECHO_ERROR_VARIABLE`` options.
-* :manual:`ctest(1)` gained a ``--stop-on-failure`` option,
- which can be used to stop running the tests once one has failed.
+* The :command:`export` command now raise an error if used multiple times with
+ same ``FILE`` without ``APPEND``. See policy :policy:`CMP0103`.
-* The :command:`ctest_test` command gained a ``STOP_ON_FAILURE`` option
- which can be used to stop running the tests once one has failed.
+* The :command:`file` command gained the ``ARCHIVE_CREATE`` and
+ ``ARCHIVE_EXTRACT`` subcommands to expose the :manual:`cmake(1)` ``-E tar``
+ functionality to CMake scripting code.
+
+* The :command:`file(CONFIGURE)` subcommand was created in order to replicate
+ the :command:`configure_file` functionality without resorting to a
+ pre-existing file on disk as input. The content is instead passed as a
+ string.
+
+* The :command:`file(UPLOAD)` command gained ``TLS_VERIFY`` and ``TLS_CAINFO``
+ options to control server certificate verification.
+
+* The :command:`find_program`, :command:`find_library`, :command:`find_path`
+ and :command:`find_file` commands gained a new ``REQUIRED`` option that will
+ stop processing with an error message if nothing is found.
+
+* The :command:`get_property` command with ``SOURCE`` scope gained the
+ ``DIRECTORY`` and ``TARGET_DIRECTORY`` options to get a property
+ from the provided directory scope.
+
+* The :command:`get_source_file_property` command gained the ``DIRECTORY``
+ and ``TARGET_DIRECTORY`` options to get a property from the
+ provided directory scope.
+
+* The :command:`list` operation ``SORT`` gained the ``NATURAL`` sort
+ option to sort using natural order (see ``strverscmp(3)`` manual).
+
+* The :command:`set_property` command with the ``SOURCE`` scope gained the
+ ``DIRECTORY`` and ``TARGET_DIRECTORY`` options to set properties
+ in the provided directory scopes.
+
+* The :command:`set_source_files_properties` command gained the ``DIRECTORY``
+ and ``TARGET_DIRECTORY`` options to set properties in the provided
+ directory scopes.
-* :variable:`CMAKE_CUDA_ARCHITECTURES` is now initialized when
+* The :command:`string` command learned a new ``HEX`` sub-command, which
+ converts strings into their hexadecimal representation.
+
+Variables
+---------
+
+* A :variable:`CMAKE_CUDA_ARCHITECTURES` variable was added to specify
+ CUDA output architectures. Users are encouraged to use this instead of
+ specifying options manually, as this approach is compiler-agnostic.
+ The variable is initialized automatically when
:variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` is ``NVIDIA``.
- Empty :prop_tgt:`CUDA_ARCHITECTURES` raises an error. See policy
- :policy:`CMP0104`.
+ The variable is used to initialize the new :prop_tgt:`CUDA_ARCHITECTURES`
+ target property. See policy :policy:`CMP0104`.
-* Added :prop_tgt:`CUDA_ARCHITECTURES` target property for specifying CUDA
- output architectures. Users are encouraged to use this instead of specifying
- options manually, as this approach is compiler-agnostic.
+* The :variable:`CMAKE_PCH_WARN_INVALID` variable was added to initialize the
+ :prop_tgt:`PCH_WARN_INVALID` target property to allow the removal of the
+ precompiled header invalid warning.
-* The ``CUDA`` language now supports Clang as a compiler.
+Properties
+----------
-* When building CMake itself from source and not using a system-provided
- libcurl, HTTP/2 support is now enabled for commands supporting
- network communication via ``http(s)``, such as :command:`file(DOWNLOAD)`,
- :command:`file(UPLOAD)`, and :command:`ctest_submit`.
- The precompiled binaries provided on ``cmake.org`` now support HTTP/2.
+* The :prop_tgt:`CUDA_ARCHITECTURES` target property was added to specify
+ CUDA output architectures. Users are encouraged to use this instead of
+ specifying options manually, as this approach is compiler-agnostic.
+ The property is initialized by the new :variable:`CMAKE_CUDA_ARCHITECTURES`
+ variable. See policy :policy:`CMP0104`.
-* The :module:`Documentation` module has been deprecated via
- :policy:`CMP0106`. This module was essentially VTK code that CMake should
- not be shipping anymore.
+* The :prop_tgt:`Fortran_PREPROCESS` target property and
+ :prop_sf:`Fortran_PREPROCESS` source-file property were added to
+ control preprocessing of Fortran source files.
-* An explicit deprecation diagnostic was added for policy ``CMP0070``
- and policy ``CMP0071`` (``CMP0069`` 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.
+* The :prop_tgt:`FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>` target property
+ and associated :variable:`CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>`
+ variable were created to allow adding a postfix to the name of a
+ framework file name when using a multi-config generator.
-* the :prop_tgt:`LINK_OPTIONS` and :prop_tgt:`INTERFACE_LINK_OPTIONS` target
- properties are now used for the device link step. See policy :policy:`CMP0105`.
+* The :prop_sf:`OBJECT_OUTPUTS` source file property now supports
+ :manual:`generator expressions <cmake-generator-expressions(7)>`.
-* The :command:`execute_process` command gained the ``ECHO_OUTPUT_VARIABLE``
- and ``ECHO_ERROR_VARIABLE`` options.
+* The :prop_tgt:`UNITY_BUILD_MODE` target property was added to tell
+ generators which algorithm to use for grouping included source
+ files.
-* The :command:`export` command now raise an error if used multiple times with
- same ``FILE`` without ``APPEND``. See policy :policy:`CMP0103`.
+* The :prop_tgt:`VS_SOURCE_SETTINGS_<tool>` target property was added
+ to tell :ref:`Visual Studio Generators` for VS 2010 and above to add
+ metadata to non-built source files using ``<tool>``.
-* The :command:`ExternalProject_Add` command gained a new
- ``GIT_REMOTE_UPDATE_STRATEGY`` keyword. This can be used to specify how
- failed rebase operations during a git update should be handled.
- The ``CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY`` variable was also added as a
- global default and is honored by both the :module:`ExternalProject` and
- :module:`FetchContent` modules.
+* The :prop_sf:`VS_SETTINGS` source file property was added to tell
+ :ref:`Visual Studio Generators` for VS 2010 and above to add
+ metadata to a non-built source file.
-* The :command:`FetchContent_Declare` command now supports a ``SOURCE_SUBDIR``
- option. It can be used to direct :command:`FetchContent_MakeAvailable`
- to look in a different location for the ``CMakeLists.txt`` file.
+* The :prop_tgt:`VS_PLATFORM_TOOLSET` target property was added to tell
+ :ref:`Visual Studio Generators` for VS 2010 and above to override
+ the platform toolset.
-* The :command:`file` command gained the ``ARCHIVE_{CREATE|EXTRACT}`` subcommands.
+* The :prop_tgt:`VS_SOLUTION_DEPLOY` target property was added to tell
+ :ref:`Visual Studio Generators` for VS 2010 and above to mark a
+ target for deployment even when not building for Windows Phone/Store/CE.
- These subcommands will replicate the :manual:`cmake(1)` ``-E tar`` functionality in
- CMake scripting code.
+Modules
+-------
-* The :command:`file(CONFIGURE)` subcommand was created in order replicate the
- :command:`configure_file` functionality without resorting to a pre-existing
- file on disk as input. The content is instead passed as a string.
+* The :module:`CheckLinkerFlag` module has been added to provide a
+ facility to check validity of link flags.
-* The :command:`file(UPLOAD)` command gained ``TLS_VERIFY`` and ``TLS_CAINFO``
- options to control server certificate verification.
+* The :module:`ExternalProject` module :command:`ExternalProject_Add` command
+ gained a new ``GIT_REMOTE_UPDATE_STRATEGY`` keyword. This can be used to
+ specify how failed rebase operations during a git update should be handled.
+ The ``CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY`` variable was also added as a
+ global default and is honored by both the :module:`ExternalProject` and
+ :module:`FetchContent` modules.
+
+* The :module:`FetchContent` module :command:`FetchContent_Declare` command
+ now supports a ``SOURCE_SUBDIR`` option. It can be used to direct
+ :command:`FetchContent_MakeAvailable` to look in a different location
+ for the ``CMakeLists.txt`` file.
* The :module:`FindBLAS` module now provides an imported target.
* The :module:`FindLAPACK` module now provides an imported target.
* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
- modules gained the possibility to create artifacts cache variables for
- interactive edition.
+ modules:
-* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
- modules gained sub-components ``Development.Module`` and
- ``Development.Embed`` for ``Development`` component.
+ * gained the possibility to create per-artifact cache variables for
+ interactive editing in :manual:`cmake-gui(1)` and :manual:`ccmake(1)`.
-* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
- modules gained the capability to specify which implementations to search for.
-
-* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
- modules support now the ``IronPython`` implementation on all platforms.
+ * gained sub-components ``Development.Module`` and
+ ``Development.Embed`` under the ``Development`` component.
-* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
- modules gained the capability to handle ``PyPy`` product.
+ * gained the capability to specify which Python implementations to find,
+ including ``IronPython`` and ``PyPy``.
* The :module:`FindRuby` module input and output variables were all renamed
from ``RUBY_`` to ``Ruby_`` for consistency with other find modules.
@@ -147,112 +178,123 @@ Changes made since CMake 3.17 include the following.
* The :module:`FindSWIG` module now accepts target languages as ``COMPONENTS``
and ``OPTIONAL_COMPONENTS`` arguments to ``find_package``.
-* The :prop_tgt:`Fortran_PREPROCESS` target property and
- :prop_sf:`Fortran_PREPROCESS` source-file property were added to
- control preprocessing of Fortran source files.
+* The :module:`GoogleTest` module :command:`gtest_discover_tests` command:
-* The :module:`FindPackageHandleStandardArgs` module option ``REQUIRED_VARS``
- is now optional if ``HANDLE_COMPONENTS`` is specified.
+ * gained a new ``DISCOVERY_MODE`` option to control when the test
+ discovery step is run. It offers a new ``PRE_TEST`` setting to
+ run the discovery at test time instead of build time.
-* The :prop_tgt:`FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>` target property
- and associated :variable:`CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>`
- variable were created to allow adding a postfix to the name of a
- framework file name when using a multi-config generator.
+ * gained a new optional parameter ``XML_OUTPUT_DIR``. When set the
+ JUnit XML test results are stored in that directory.
-* To manage device and host link steps, the ``$<DEVICE_LINK:...>`` and
- ``$<HOST_LINK:...>``
- :manual:`generator expressions <cmake-generator-expressions(7)>` were added.
+* The :module:`FindLibXslt` module now provides imported targets.
+
+* The :module:`UseSWIG` module now supports Fortran as a target language if
+ the ``SWIG_EXECUTABLE`` is SWIG-Fortran_.
+
+.. _`SWIG-Fortran`: https://github.com/swig-fortran/swig
+
+Generator Expressions
+---------------------
+
+* The ``$<DEVICE_LINK:...>`` and ``$<HOST_LINK:...>``
+ :manual:`generator expressions <cmake-generator-expressions(7)>` were added
+ to manage device and host link steps.
* The ``$<LINK_LANGUAGE:...>`` and ``$<LINK_LANG_AND_ID:...>``
:manual:`generator expressions <cmake-generator-expressions(7)>` were added.
-* :prop_sf:`OBJECT_OUTPUTS` now support :manual:`generator expressions <cmake-generator-expressions(7)>`.
+CTest
+-----
-* The :module:`GoogleTest` module :command:`gtest_discover_tests` command
- gained a new ``DISCOVERY_MODE`` option to control when the test
- discovery step is run. It offers a new ``PRE_TEST`` setting to
- run the discovery at test time instead of build time.
+* :manual:`ctest(1)` gained a new :variable:`CTEST_RESOURCE_SPEC_FILE`
+ variable, which can be used to specify a
+ :ref:`resource specification file <ctest-resource-specification-file>`.
-* The :module:`GoogleTest` module :command:`gtest_discover_tests` command
- gained a new optional parameter ``XML_OUTPUT_DIR``. When set the JUnit XML
- test results are stored in that directory.
+* :manual:`ctest(1)` gained a ``--stop-on-failure`` option,
+ which can be used to stop running the tests once one has failed.
-* The :prop_tgt:`UNITY_BUILD_MODE` target property was added to tell
- generators which algorithm to use for grouping included source
- files.
+* The :command:`ctest_test` command gained a ``STOP_ON_FAILURE`` option
+ which can be used to stop running the tests once one has failed.
-* The :module:`FindLibXslt` module now provides imported targets.
+* The :module:`CTestCoverageCollectGCOV` module
+ :command:`ctest_coverage_collect_gcov` command gained a
+ ``TARBALL_COMPRESSION`` option to control compression of the
+ tarball of collected results.
-* The :command:`list` operation ``SORT`` gained the ``NATURAL`` sort
- option to sort using natural order (see ``strverscmp(3)`` manual).
+CPack
+-----
-* On Windows, the :generator:`Ninja` and :generator:`Ninja Multi-Config`
- generators, when a compiler is not explicitly specified, now select
- the first compiler (of any name) found in directories listed by the
- ``PATH`` environment variable.
+* The :cpack_gen:`CPack Archive Generator`'s ``TXZ`` format learned the
+ :variable:`CPACK_ARCHIVE_THREADS` variable to enable parallel compression.
+ Requires support in the ``liblzma`` used by CMake.
* The :cpack_gen:`CPack NSIS Generator` gained a new variable
:variable:`CPACK_NSIS_MANIFEST_DPI_AWARE` to declare that the
installer is DPI-aware.
-* The :cpack_gen:`CPack Archive Generator`'s ``TXZ`` format learned the
- :variable:`CPACK_ARCHIVE_THREADS` variable to enable parallel compression.
- Requires support in the ``liblzma`` used by CMake.
+* The :cpack_gen:`CPack RPM Generator` gained
+ :variable:`CPACK_RPM_PRE_TRANS_SCRIPT_FILE`
+ :variable:`CPACK_RPM_POST_TRANS_SCRIPT_FILE`
+ variables to specify pre- and post-trans scripts.
-* The :variable:`CMAKE_PCH_WARN_INVALID` variable was added to initialize the
- :prop_tgt:`PCH_WARN_INVALID` target property to allow the removal of the
- precompiled header invalid warning.
+Other
+-----
-* Add support for profiling of CMake scripts through the parameters
- ``--profiling-output`` and ``--profiling-format``. These options can
- be used by users to gain insight into the performance of their scripts.
+* :manual:`cmake-gui(1)` now populates its generator selection
+ widget default value from the :envvar:`CMAKE_GENERATOR` environment
+ variable. Additionally, environment variables
+ :envvar:`CMAKE_GENERATOR_PLATFORM` and :envvar:`CMAKE_GENERATOR_TOOLSET`
+ are used to populate their respective widget defaults.
- The first supported output format is ``google-trace`` which is a format
- supported by Google Chrome's ``about:tracing`` tab.
+* :manual:`ccmake(1)` learned to read a :envvar:`CCMAKE_COLORS`
+ environment variable to customize colors.
-* The :command:`find_program`, :command:`find_library`, :command:`find_path`
- and :command:`find_file` commands gained a new ``REQUIRED`` option that will
- stop processing with an error message if nothing is found.
+Deprecated and Removed Features
+===============================
-* Linking a target to itself through an alias now raise an error.
- See policy :policy:`CMP0108`.
+* The :module:`Documentation` module has been deprecated via
+ :policy:`CMP0106`. This module was essentially VTK code that CMake should
+ not be shipping anymore.
-* The :command:`set_property` with the ``SOURCE`` scope gained the
- ``DIRECTORY`` and ``TARGET_DIRECTORY`` options to set properties
- in the provided directory scopes.
-* The :command:`set_source_files_properties` gained the ``DIRECTORY``
- and ``TARGET_DIRECTORY`` options to set properties in the provided
- directory scopes.
-* The :command:`get_property` with ``SOURCE`` scope gained the
- ``DIRECTORY`` and ``TARGET_DIRECTORY`` options to get a property
- from the provided directory scope.
-* The :command:`get_source_file_property` gained the ``DIRECTORY``
- and ``TARGET_DIRECTORY`` options to get a property from the
- provided directory scope.
+* An explicit deprecation diagnostic was added for policy ``CMP0070``
+ and policy ``CMP0071`` (``CMP0069`` 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.
-* The :command:`source_group` command now also recognizes forward slashes
- as subgroup delimiters, not just backslashes.
+Other Changes
+=============
-* The :command:`string` command learned a new ``HEX`` sub-command, which
- converts strings into their hexadecimal representation.
+* On Windows, the :generator:`Ninja` and :generator:`Ninja Multi-Config`
+ generators, when a compiler is not explicitly specified, now select
+ the first compiler (of any name) found in directories listed by the
+ ``PATH`` environment variable.
-* The :module:`UseSWIG` module now supports Fortran as a target language if
- the ``SWIG_EXECUTABLE`` is SWIG-Fortran_.
+* The :prop_tgt:`LINK_OPTIONS` and :prop_tgt:`INTERFACE_LINK_OPTIONS` target
+ properties are now used for the device link step.
+ See policy :policy:`CMP0105`.
-.. _`SWIG-Fortran`: https://github.com/swig-fortran/swig
+* Creation of an ``ALIAS`` target overwriting an existing target now raises an
+ error. See policy :policy:`CMP0107`.
-* The :prop_tgt:`VS_SOURCE_SETTINGS_<tool>` target property was added
- to tell :ref:`Visual Studio Generators` for VS 2010 and above to add
- metadata to non-built source files using ``<tool>``.
+* Linking a target to itself through an alias now raises an error.
+ See policy :policy:`CMP0108`.
-* The :prop_sf:`VS_SETTINGS` source file property was added to tell
- :ref:`Visual Studio Generators` for VS 2010 and above to add
- metadata to a non-built source file.
+* The :module:`FindPackageHandleStandardArgs` module option ``REQUIRED_VARS``
+ is now optional if ``HANDLE_COMPONENTS`` is specified.
-* The :prop_tgt:`VS_PLATFORM_TOOLSET` target property was added to tell
- :ref:`Visual Studio Generators` for VS 2010 and above to override
- the platform toolset.
+* The :command:`source_group` command now also recognizes forward slashes
+ as subgroup delimiters, not just backslashes.
-* The :prop_tgt:`VS_SOLUTION_DEPLOY` target property was added to tell
- :ref:`Visual Studio Generators` for VS 2010 and above to mark a
- target for deployment even when not building for Windows Phone/Store/CE.
+* :manual:`ctest(1)` now logs environment variables that it sets for each test,
+ either due to the :prop_test:`ENVIRONMENT` property or the
+ :ref:`resource allocation <ctest-resource-allocation>` feature, and submits
+ this log to CDash. It does not log environment variables that were set
+ outside of CTest.
+
+* When building CMake itself from source and not using a system-provided
+ libcurl, HTTP/2 support is now enabled for commands supporting
+ network communication via ``http(s)``, such as :command:`file(DOWNLOAD)`,
+ :command:`file(UPLOAD)`, and :command:`ctest_submit`.
+ The precompiled binaries provided on ``cmake.org`` now support HTTP/2.