diff --git a/Help/release/3.17.rst b/Help/release/3.17.rst new file mode 100644 index 0000000000..9176181e67 --- /dev/null +++ b/Help/release/3.17.rst @@ -0,0 +1,282 @@ +CMake 3.17 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.16 include the following. + +* The :command:`add_custom_command` command learned to detect paths in + ``DEPENDS`` arguments and convert them to paths relative to the current + binary directory. This only applies to paths which contain a ``/`` or ``\\`` + in them because names like ``filename.txt`` could also be target names and + cannot be coverted into absolute paths blindly. + +* A :prop_tgt:`DEPRECATION` target property was added to mark + a target as deprecated. If a linked target is marked as + deprecated, a warning with the deprecation message is issued + at generate time. + +* The :prop_tgt:`AIX_EXPORT_ALL_SYMBOLS` target property and associated + :variable:`CMAKE_AIX_EXPORT_ALL_SYMBOLS` variable were created to + optionally explicitly disbale automatic export of symbols from shared + libraries on AIX. + +* :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` learned to process headers with + a ``.hh`` extension. The new behavior is enabled by policy + :policy:`CMP0100`. + +* :manual:`ccmake(1)` now displays cache values using colors + based on the entry type if the terminal supports color. + +* :manual:`ccmake(1)` now displays messages and a progress bar during + configure and generate. It will keep the output displayed if any + errors or warnings occurred. + +* A :variable:`CMAKE_CTEST_ARGUMENTS` variable was added to specify a list + of command-line arguments passed to CTest when running through the + ``test`` (or ``RUN_TESTS``) target of the generated build system. + +* Define the following variables inside a function: + + - :variable:`CMAKE_CURRENT_FUNCTION` + - :variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR` + - :variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE` + - :variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE` + +* :manual:`cmake(1)` gained a ``--debug-find`` command line + option that can be used to provide information on where find + commands searched. + +* Variable :variable:`CMAKE_FIND_DEBUG_MODE` was introduced to + print extra find call information during the cmake run to standard + error. Output is designed for human consumption and not for parsing. + +* :manual:`cmake(1)` gained a ``rm`` command line + option that can be used to remove directories (with ``-r`` or ``-R`` flag) + and files. + If the ``-f`` flag is not specified, attempting to remove a file that + doesn't exist returns an non-zero error code. + This command deprecates ``remove`` and ``remove_directory``. + The ``remove`` implementation was buggy and always returned 0 when ``force`` + flag was not present and a file didn't exist. It cannot be fixed without + breaking backwards compatibility so we introduced ``rm``. + +* The :envvar:`CMAKE__COMPILER_LAUNCHER` environment variable may now be + used to initialize the :variable:`CMAKE__COMPILER_LAUNCHER` variable. + +* The :cpack_gen:`CPack PackageMaker Generator` generator has been + deprecated because Xcode no longer distributes the PackageMaker tools. + The undocumented ``OSXX11`` generator has also been deprecated. + +* The :cpack_gen:`CPack DragNDrop Generator` learned to handle + RTF formatted license files. When :variable:`CPACK_DMG_SLA_DIR` + variable is set, .license.rtf is considered, but + only as a fallback when the plaintext (.txt) file is not found + in order to maintain backwards compatibility. + +* The :cpack_gen:`CPack NSIS Generator` gained a new variable + :variable:`CPACK_NSIS_MUI_HEADERIMAGE` to set the header image. + To not break existing setups, it still defaults to + :variable:`CPACK_PACKAGE_ICON` if the new variable is not set. + +* The :cpack_gen:`CPack NSIS Generator` now supports + :variable:`CPACK_NSIS_UNINSTALL_NAME`. + This can be used to specify the name of the Uninstall program. + +* The :cpack_gen:`CPack NSIS Generator` now supports + :variable:`CPACK_NSIS_WELCOME_TITLE` and :variable:`CPACK_NSIS_WELCOME_TITLE_3LINES`. + These can be used to specify the welcome page title and display it in 3 lines. + +* The :cpack_gen:`CPack NSIS Generator` now supports + :variable:`CPACK_NSIS_FINISH_TITLE` and :variable:`CPACK_NSIS_FINISH_TITLE_3LINES`. + These can be used to specify the finish page title and display it in 3 lines. + +* The :cpack_gen:`CPack productbuild Generator` and + :cpack_gen:`CPack PackageMaker Generator` gained options + :variable:`CPACK_PRODUCTBUILD_BACKGROUND` and + :variable:`CPACK_PACKAGEMAKER_BACKGROUND`, respectively, + to specify a background image for the macOS installer. + +* The :variable:`CTEST_CONFIGURATION_TYPE` variable is now set from the command + line when :manual:`ctest(1)` is invoked with ``-C ``. + +* The :manual:`ctest(1)` gained support for Dr. Memory to run + memcheck runs. + +* The :manual:`ctest(1)` tool gained a ``--no-tests=<[error|ignore]>`` option + to explicitly set and unify the behavior between direct invocation and + script mode if no tests were found. + +* The :manual:`ctest(1)` tool gained a ``--repeat :`` option + to specify conditions in which to repeat tests. This generalizes + the existing ``--repeat-until-fail `` option to add modes for + ``until-pass`` and ``after-timeout``. + +* The :command:`ctest_test` command gained a ``REPEAT :`` option + to specify conditions in which to repeat tests. + +* The :manual:`Compile Features ` functionality + now offers meta-features for the CUDA language standard levels + (e.g. ``cuda_std_03``, ``cuda_std_14``). See + :prop_gbl:`CMAKE_CUDA_KNOWN_FEATURES`. + +* The :variable:`CMAKE_CUDA_RUNTIME_LIBRARY` variable and + :prop_tgt:`CUDA_RUNTIME_LIBRARY` target property were introduced to + select the CUDA runtime library used when linking targets that + use CUDA. + +* The :cpack_gen:`CPack DragNDrop Generator` learned to use + the :variable:`CPACK_DMG__FILE_NAME` variable + to set a custom filename when packaging components into + their own DMGs. + +* An explicit deprecation diagnostic was added for policy ``CMP0068`` + and policy ``CMP0069`` (``CMP0067`` 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 :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable now takes its + initial value from the :envvar:`CMAKE_EXPORT_COMPILE_COMMANDS` environment + variable if no explicit configuration is given. + +* The :module:`ExternalProject` module :command:`ExternalProject_Add` + command gained a ``GIT_SUBMODULES_RECURSE`` option to specify whether + Git submodules should be updated recursively. The default is on to + preserve existing behavior. + +* The :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable can now be used + to persist a log level between CMake runs, unlike the ``--log-level`` + command line option which only applies to that particular run. + +* The :command:`message` command learned to output context provided in + the :variable:`CMAKE_MESSAGE_CONTEXT` variable for log levels + ``NOTICE`` and below. Enable this output with the new ``--log-context`` + command-line option or :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` variable. + +* The :manual:`file API ` index file now emits a + ``multiConfig`` flag specifying whether or not the generator supports + multiple output configurations. + +* The :module:`FindCUDAToolkit` module was added to find the CUDA Toolkit without enabling CUDA as a language. + +* The :module:`FindCURL` module learned to find CURL using + the ``CURLConfig.cmake`` package configuration file generated by + CURL's cmake buildsystem. It also gained a new ``CURL_NO_CURL_CMAKE`` + option to disable this behavior. + +* The :module:`FindFLEX` module's ``FLEX_TARGET`` command now runs ``flex`` + with :variable:`CMAKE_CURRENT_BINARY_DIR` as the working directory. + See policy :policy:`CMP0098`. + +* The :module:`FindLibArchive` module now returns an ``IMPORTED`` target + for libarchive. + +* The :module:`FindPython` module has learned to find Python components in active + virtual environments managed by ``conda``. + +* The :module:`FindPython3` and :module:`FindPython` modules gained, + respectively, variable ``Python3_SOABI`` and ``Python_SOABI`` giving + the standard extension suffix for modules. + +* The :command:`foreach` learned a new option ``ZIP_LISTS`` to iterate + over multiple lists simultaneously. + +* The :module:`FindPackageHandleStandardArgs` module learned to check the + package name passed in for typo mistakes. + +* The :prop_tgt:`INSTALL_NAME_DIR` target property now supports + :manual:`generator expressions `. + In particular, the ``$`` generator expression can + be used to set the directory relative to the install-time prefix. + +* :manual:`cmake(1)` gained a ``--trace-format`` command line option that + can be used to set the ``--trace`` output format. Currently, the old + human readable and the new JSON format are supported. The new JSON format + is easier to parse automatically, than the existing format. + +* Target link properties :prop_tgt:`INTERFACE_LINK_OPTIONS`, + :prop_tgt:`INTERFACE_LINK_DIRECTORIES` and + :prop_tgt:`INTERFACE_LINK_DEPENDS` are now transitive over private + dependency on static libraries. + See policy :policy:`CMP0099`. + +* The :command:`load_cache(READ_WITH_PREFIX)` command mode is now allowed + when using ``cmake -P`` to :ref:`Run a Script