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_<LANG>_COMPILER_LAUNCHER` environment variable may now be
  used to initialize the :variable:`CMAKE_<LANG>_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, <language>.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 <cfg>``.

* 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 <mode>:<n>`` option
  to specify conditions in which to repeat tests.  This generalizes
  the existing ``--repeat-until-fail <n>`` option to add modes for
  ``until-pass`` and ``after-timeout``.

* The :command:`ctest_test` command gained a ``REPEAT <mode>:<n>`` option
  to specify conditions in which to repeat tests.

* The :manual:`Compile Features <cmake-compile-features(7)>` 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_<component>_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 <cmake-file-api(7)>` 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 <cmake-generator-expressions(7)>`.
  In particular, the ``$<INSTALL_PREFIX>`` 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 <Script Processing Mode>`.

* When using MinGW tools, the :command:`find_library` command no longer
  finds ``.dll`` files by default.  Instead it expects ``.dll.a`` import
  libraries to be available.

* The :generator:`MinGW Makefiles` generator no longer issues an error if
  ``sh.exe`` is present in the environment's ``PATH``.

* :manual:`cmake(1)` gained a :generator:`Ninja Multi-Config` generator,
  which is similar to the :generator:`Ninja` generator but can be used to build
  multiple configurations at once.

* The :command:`message` command gained new keywords ``CHECK_START``,
  ``CHECK_PASS`` and ``CHECK_FAIL``.

* The :generator:`Ninja` generator learned to perform some post-processing on
  the generated files for more consistent builds.

* The :generator:`Ninja` generator now prefers the first ninja build
  tool to appear in the ``PATH`` no matter whether it is called
  ``ninja-build``, ``ninja``, or ``samu``.  Previously the first
  of those names to appear anywhere in the ``PATH`` would be preferred.

* Target properties :prop_tgt:`OSX_COMPATIBILITY_VERSION` and
  :prop_tgt:`OSX_CURRENT_VERSION` were added to set the
  ``compatibility_version`` and ``curent_version`` respectively
  on macOS. For backwards compatibility, if these properties
  are not set, :prop_tgt:`SOVERSION` and :prop_tgt:`VERSION`
  are used respectively as fallbacks.

* Since sdcc 3.2.0, sdcclib has been deprecated in favor of sdar as librarian.
  Since sdcc 3.8.6, it has been removed from the distribution.
  Use sdar if found, else use sdcclib to keep older compatibility.

* The default flags used for SDCC no longer include any target-specific flags.
  Previously the default flags were hard-coded for 8051.

* :command:`target_compile_options` command learns to honor ``BEFORE`` keyword
  in all scopes. See policy :policy:`CMP0101`.

* The :prop_tgt:`VS_DOTNET_DOCUMENTATION_FILE` target property was added
  to tell :ref:`Visual Studio Generators` to generate a ``DocumentationFile``
  reference in ``.csproj`` files.

* :ref:`Visual Studio Generators` for VS 2010 and above learned to
  support .NET Standard and .NET Core.  See the
  :prop_tgt:`DOTNET_TARGET_FRAMEWORK` target property and
  associated :variable:`CMAKE_DOTNET_TARGET_FRAMEWORK` variable.

* :ref:`Visual Studio Generators` learned to support per-config sources.
  Previously only :ref:`Command-Line Build Tool Generators` supported them.

* With :ref:`Visual Studio Generators` for VS 2010 and above,
  the :variable:`CMAKE_GENERATOR_TOOLSET` setting gained an option
  to specify the ``VCTargetsPath`` value for project files.

* The :variable:`CMAKE_VS_GLOBALS` variable value now applies during
  compiler identification and in targets created by the
  :command:`add_custom_target` command.

* The :generator:`Xcode` generator no longer hard-codes ``-Wmost``,
  ``-Wno-four-char-constants``, and ``-Wno-unknown-pragmas`` warning flags.

* The :variable:`CMAKE_XCODE_SCHEME_ENVIRONMENT` variable was added
  to initialize the :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` target property.

* The Xcode generator learnt to set the value of the
  ``Custom Working Directory`` schema
  option with the :prop_tgt:`XCODE_SCHEME_WORKING_DIRECTORY`
  target property.

* The IBM XL Fortran compiler is now supported by the :generator:`Ninja`
  generator.

* The :module:`FindLibXml2` module now provides an imported target for the xmllint executable