diff options
author | Brad King <brad.king@kitware.com> | 2020-06-03 10:22:15 (GMT) |
---|---|---|
committer | Brad King <brad.king@kitware.com> | 2020-06-03 10:22:15 (GMT) |
commit | 389ca18289f49a9c1f8f6c412f8642d79d6a1720 (patch) | |
tree | da2cfc765dab7a03eab3ee3933b3afcc4643d80e /Help/release/3.18.rst | |
parent | ab6b5c01eaf2c88a9a477f40843947eb23084e20 (diff) | |
download | CMake-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.rst | 380 |
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. |