code:
CMake 3.17 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.16 include the following.

New Features
============

Generators
----------

* :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.

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

* :ref:`Visual Studio Generators` for VS 2010 and above now support
  specifying the ``VCTargetsPath`` value for project files in
  :variable:`CMAKE_GENERATOR_TOOLSET` setting.

* :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.

Languages
---------

* 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`.

Compilers
---------

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

Command-Line
------------

* :manual:`cmake(1)` gained a ``--debug-find`` command-line option to
  enable additional human-readable output on where ``find_*`` commands search.

* :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.

* :manual:`cmake(1)` gained a ``-E rm`` command-line tool that can be
  used to remove directories and files.  This supersedes the existing
  ``-E remove`` and ``-E remove_directory`` tools and has better semantics.

Commands
--------

* The :command:`add_custom_command` command learned to interpret paths in
  ``DEPENDS`` arguments that are specified relative to the current
  binary directory.

* The :command:`foreach` command learned a new ``ZIP_LISTS`` option to iterate
  over multiple lists simultaneously.

* The :command:`load_cache(READ_WITH_PREFIX)` command mode is now allowed
  when using ``cmake -P`` to :ref:`Run a Script <Script Processing Mode>`.

* 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 :command:`message` command gained new keywords ``CHECK_START``,
  ``CHECK_PASS`` and ``CHECK_FAIL``.

* The :command:`target_compile_options` command now honors the ``BEFORE``
  keyword more consistently.  See policy :policy:`CMP0101`.

Variables
---------

* 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.

* The following variables are now defined inside a :command:`function`:

  - :variable:`CMAKE_CURRENT_FUNCTION`
  - :variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR`
  - :variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE`
  - :variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE`

* 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 :variable:`CMAKE_FIND_DEBUG_MODE` variable 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.

* 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 :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable, if not set
  explicitly, now takes its initial value from the
  :envvar:`CMAKE_<LANG>_COMPILER_LAUNCHER` environment variable.

* 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 :variable:`CMAKE_XCODE_SCHEME_ENVIRONMENT` variable was added
  to initialize the :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` target property.

* The :variable:`CMAKE_XCODE_SCHEME_WORKING_DIRECTORY` variable and
  associated :prop_tgt:`XCODE_SCHEME_WORKING_DIRECTORY` target property
  were added to tell the :generator:`Xcode` generator to set the value of
  the ``Custom Working Directory`` schema option.

Properties
----------

* The :prop_tgt:`AIX_EXPORT_ALL_SYMBOLS` target property and associated
  :variable:`CMAKE_AIX_EXPORT_ALL_SYMBOLS` variable were created to
  optionally explicitly disable automatic export of symbols from shared
  libraries on AIX.

* The :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:`INSTALL_NAME_DIR` target property now supports
  :manual:`generator expressions <cmake-generator-expressions(7)>`.
  In particular, the :genex:`$<INSTALL_PREFIX>` generator expression can
  be used to set the directory relative to the install-time prefix.

* Target properties :prop_tgt:`MACHO_COMPATIBILITY_VERSION` and
  :prop_tgt:`MACHO_CURRENT_VERSION` were added to set the
  ``compatibility_version`` and ``curent_version``, respectively,
  for Mach-O binaries.  For backwards compatibility, if these properties
  are not set, :prop_tgt:`SOVERSION` and :prop_tgt:`VERSION`
  are used respectively as fallbacks.

* 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.

Modules
-------

* 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 :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 provides 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. Moreover, commands
  ``Python3_add_library()`` and ``Python_add_library()`` gained the option
  ``WITH_SOABI`` to prefix the library suffix with the value of ``SOABI``.

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

Autogen
-------

* :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` learned to process headers
  with a ``.hh`` extension.  See policy :policy:`CMP0100`.

CTest
-----

* 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)` tool 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.

CPack
-----

* 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.

* 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` gained support for a
  :variable:`CPACK_PRODUCTBUILD_BACKGROUND` variable to specify a background
  image for the macOS installer.

Other
-----

* :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.

Deprecated and Removed Features
===============================

* 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 CPack ``PackageMaker`` generator has been
  deprecated because Xcode no longer distributes the PackageMaker tools.
  The undocumented ``OSXX11`` generator has also been deprecated.

* The :manual:`cmake(1)` command-line ``-E remove`` and ``-E remove_directory``
  tools are deprecated in favor of the new ``-E rm`` tool.  The older tools
  always returned 0 if a named path did not exist even without the force
  option and cannot be fixed without breaking compatibility, and so have
  been superseded.

* The :cpack_gen:`CPack NSIS Generator` now requires NSIS 3.0 or later.

Other Changes
=============

* 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.

* Target link properties :prop_tgt:`INTERFACE_LINK_OPTIONS`,
  :prop_tgt:`INTERFACE_LINK_DIRECTORIES` and
  :prop_tgt:`INTERFACE_LINK_DEPENDS` are now transitive over private
  dependencies on static libraries.
  See policy :policy:`CMP0099`.

* 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``.

* 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.

* With SDCC the ``sdar`` tool is now preferred over ``sdcclib`` as librarian.
  The latter was deprecated by SDCC 3.2.0 and removed in SDCC 3.8.6.

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

* 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.

Updates
=======

Changes made since CMake 3.17.0 include the following.

3.17.1
------

* CMake 3.17.0 updated the :cpack_gen:`CPack NSIS Generator` with changes
  that require NSIS 3.0 or later.  CMake 3.17.1 now enforces the use
  of a sufficiently new version.

3.17.3
------

* Selection of the Objective C or C++ compiler now considers the
  :envvar:`CC` or :envvar:`CXX` environment variable if the
  :envvar:`OBJC` or :envvar:`OBJCXX` environment variable is not set.

* The :module:`FindPkgConfig` module now extracts include directories
  prefixed with ``-isystem`` into the ``*_INCLUDE_DIRS`` variables and
  :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target properties.
  Previously they would be places in ``*_CFLAGS_OTHER`` variables and
  :prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties.

3.17.5
------

* The default value of :variable:`CMAKE_AUTOMOC_PATH_PREFIX` was changed to
  ``OFF`` because this feature can break existing projects that have
  identically named header files in different include directories.
  This restores compatibility with behavior of CMake 3.15 and below.
  The default was also changed to ``OFF`` in 3.16.9.


code:
CMake 3.18 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.17 include the following.

New Features
============

Languages
---------

* The ``CUDA`` language can now be compiled using Clang on non-Windows
  platforms. Separable compilation is not yet supported on any platform.

Command-Line
------------

* :manual:`cmake(1)` gained support for profiling of CMake scripts through
  the parameters ``--profiling-output`` and ``--profiling-format``.

* :manual:`cmake(1)` gained a ``cat`` command line
  option that can be used to concatenate files and print them
  on standard output.

Commands
--------

* The :command:`add_library` and :command:`add_executable` commands
  learned to create :ref:`Alias Targets` referencing non-``GLOBAL``
  :ref:`Imported Targets`.

* 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.

* The :command:`execute_process` command gained the ``ECHO_OUTPUT_VARIABLE``
  and ``ECHO_ERROR_VARIABLE`` options.

* The :command:`export` command now raise an error if used multiple times with
  same ``FILE`` without ``APPEND``. See policy :policy:`CMP0103`.

* 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.

* 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``.
  The variable is used to initialize the new :prop_tgt:`CUDA_ARCHITECTURES`
  target property.  See policy :policy:`CMP0104`.

* 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.

Properties
----------

* 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 :prop_tgt:`Fortran_PREPROCESS` target property and
  :prop_sf:`Fortran_PREPROCESS` source-file property were added to
  control preprocessing of Fortran source files.

* 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_sf:`OBJECT_OUTPUTS` source file property now supports
  :manual:`generator expressions <cmake-generator-expressions(7)>`.

* The :prop_tgt:`PCH_WARN_INVALID` target property was added to allow the
  removal of the precompiled header invalid warning.

* The :prop_tgt:`UNITY_BUILD_MODE` target property was added to tell
  generators which algorithm to use for grouping included source
  files.

* 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 :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 :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 :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.

Modules
-------

* The :module:`CheckLinkerFlag` module has been added to provide a
  facility to check validity of link flags.

* 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:`FindCUDAToolkit` module:

  * gained the variable
    ``CUDAToolkit_LIBRARY_ROOT``, which is the directory containing the
    ``nvvm`` directory and ``version.txt``.

  * uses toolkit and library root found during ``CUDA`` compiler detection.

* The :module:`FindLAPACK` module now provides an imported target.

* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
  modules:

  * gained the possibility to create per-artifact cache variables for
    interactive editing in :manual:`cmake-gui(1)` and :manual:`ccmake(1)`.

  * gained sub-components ``Development.Module`` and
    ``Development.Embed`` under the ``Development`` component.

  * 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.
  Input variables of the old case will be honored if provided, and output
  variables of the old case are always provided.

* The :module:`FindSWIG` module now accepts target languages as  ``COMPONENTS``
  and ``OPTIONAL_COMPONENTS`` arguments to ``find_package``.

* 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.  A new
    ``CMAKE_GTEST_DISCOVER_TESTS_DISCOVERY_MODE`` variable can be used
    to change the default globally.

  * gained a new optional parameter ``XML_OUTPUT_DIR``. When set the
    JUnit XML test results are stored in that directory.

* 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 :genex:`$<DEVICE_LINK:...>` and :genex:`$<HOST_LINK:...>`
  generator expressions were added to manage device and host link steps.

* The :genex:`$<LINK_LANGUAGE:...>` and :genex:`$<LINK_LANG_AND_ID:...>`
  generator expressions were added.

CTest
-----

* :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>`.

* :manual:`ctest(1)` gained a ``--stop-on-failure`` option,
  which can be used to stop running the tests once one has failed.

* 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:`CTestCoverageCollectGCOV` module
  :command:`ctest_coverage_collect_gcov` command gained a
  ``TARBALL_COMPRESSION`` option to control compression of the
  tarball of collected results.

CPack
-----

* 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 RPM Generator` gained
  :variable:`CPACK_RPM_PRE_TRANS_SCRIPT_FILE` and
  :variable:`CPACK_RPM_POST_TRANS_SCRIPT_FILE`
  variables to specify pre- and post-transaction scripts.

Other
-----

* :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:`ccmake(1)` learned to read a :envvar:`CCMAKE_COLORS`
  environment variable to customize colors.

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
  is now aware of the availability of C11 features in MSVC 19.27 and 19.28,
  including support for the ``c_restrict``, ``c_static_assert`` features and
  the ``-std:c11`` flag.

Deprecated and Removed Features
===============================

* The :module:`Documentation` module has been deprecated via
  :policy:`CMP0106`. This module was essentially VTK code that CMake should
  not be shipping anymore.

* 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.

Other Changes
=============

* 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 :prop_tgt:`LINK_OPTIONS` and :prop_tgt:`INTERFACE_LINK_OPTIONS` target
  properties are now used for the device link step.
  See policy :policy:`CMP0105`.

* Creation of an ``ALIAS`` target overwriting an existing target now raises an
  error. See policy :policy:`CMP0107`.

* Linking a target to itself through an alias now raises an error.
  See policy :policy:`CMP0108`.

* The :module:`FindPackageHandleStandardArgs` module option ``REQUIRED_VARS``
  is now optional if ``HANDLE_COMPONENTS`` is specified.

* The :command:`source_group` command now also recognizes forward slashes
  as subgroup delimiters, not just backslashes.

* :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.

* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has
  been updated to 2.1.

* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object gained
  a new ``precompileHeaders`` field in the ``compileGroups`` objects.

Updates
=======

Changes made since CMake 3.18.0 include the following.

3.18.1
------

* The :generator:`Xcode` generator, when :variable:`CMAKE_OSX_ARCHITECTURES`
  is not defined, now selects ``$(NATIVE_ARCH_ACTUAL)`` as the default
  architecture (the Xcode ``ARCHS`` setting).  This is needed for Xcode 12
  to select the host's architecture, which older versions of Xcode did
  by default.

* In CMake 3.18.0 the :command:`add_test` command learned to support
  special characters in test names.  This was accidentally left out of
  its release notes.  Unfortunately the fix breaks existing projects
  that were using manual quoting or escaping to work around the prior
  limitation.  This fix has been reverted in 3.18.1, but may be
  re-introduced in future versions of CMake with a policy for compatibility.

3.18.2
------

* The default value of :variable:`CMAKE_AUTOMOC_PATH_PREFIX` was changed to
  ``OFF`` because this feature can break existing projects that have
  identically named header files in different include directories.
  This restores compatibility with behavior of CMake 3.15 and below.
  The default was also changed to ``OFF`` in 3.16.9 and 3.17.5.

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
  was updated for MSVC 19.27 as mentioned above (``c_restrict``).

3.18.3
------

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
  was updated for MSVC 19.28 as mentioned above (``c_static_assert``).

repo_name: lazytadpole/codenamesilverfish

license: mit


code:
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 (see
  :manual:`cmake-presets(7)`).

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.

* ``CUDA`` language support now works on QNX.

Platforms
---------

* Apple Silicon is now supported (since CMake 3.19.2):

  * The :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` is selected using ``uname -m``.
    Since this may vary based on CMake's own architecture and that of
    the invoking process tree, the :variable:`CMAKE_APPLE_SILICON_PROCESSOR`
    variable or :envvar:`CMAKE_APPLE_SILICON_PROCESSOR` environment
    variable may be set to specify a host architecture explicitly.

  * If :variable:`CMAKE_OSX_ARCHITECTURES` is not set, CMake adds explicit
    flags to tell the compiler to build for the
    :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` so the toolchain does not
    have to guess based on the process tree's architecture.

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:`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` command gained a new ``REAL_PATH`` sub-command to
  compute a path with symlinks resolved.

* The :command:`find_package` command learned to handle a version range.

* The :command:`separate_arguments` command gained a new ``PROGRAM`` option.
  It allows the arguments to be treated as a program invocation and will
  resolve the executable to a full path if it can be found.

* The ``DIRECTORY`` option of the :command:`set_property`,
  :command:`get_property`, and :command:`get_directory_property` commands
  now accepts references to binary directory paths, such as the value of
  :variable:`CMAKE_CURRENT_BINARY_DIR`.

* The :command:`string` command gained a set of new ``JSON`` sub commands
  that 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_PCH_INSTANTIATE_TEMPLATES` variable was added to
  initialize the new :prop_tgt:`PCH_INSTANTIATE_TEMPLATES` target property.

* 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 may significantly improve compile times. Currently only supported for
  Clang (version 11 or later).

* 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.

* The :module:`CMakePackageConfigHelpers` module gained support for version
  ranges.

* 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 ranges. 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 ability to handle a version range.

* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
  modules provide, respectively, the variable ``Python3_LINK_OPTIONS``,
  ``Python2_LINK_OPTIONS`` and ``Python_LINK_OPTIONS`` for link options.

* The :module:`FindSDL` module now provides:

  * An 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``.

* The :module:`FindSWIG` module gained the ability to handle 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.

* The :module:`UseSWIG` module gained support for new source file properties
  ``OUTPUT_DIR`` and ``OUTFILE_DIR`` to manage output directories on a
  per-source basis.

CTest
-----

* :manual:`ctest(1)` now supports the CUDA ``compute-sanitizer`` checker
  (previously known as ``cuda-memcheck``) as the ``CTEST_MEMORYCHECK_COMMAND``.
  The different tools (``memcheck``, ``racecheck``, ``synccheck`` and
  ``initcheck``) supported 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 missing its location property 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.

Updates
=======

Changes made since CMake 3.19.0 include the following.

3.19.1
------

* CMake 3.19.0 compiles source files with the :prop_sf:`LANGUAGE`
  property by passing an explicit language flag such as ``-x c``.
  This is consistent with the property's documented meaning that
  the source file is written in the specified language.  However,
  it can break projects that were using the property only to
  cause the specified language's compiler to be used.  This has
  been reverted to restore behavior from CMake 3.18 and below.

* CUDA 11.1 support for Clang.

3.19.2
------

* The precompiled macOS binary provided on ``cmake.org`` is now a
  universal binary with ``x86_64`` and ``arm64`` architectures.
  It requires macOS 10.10 or newer.
  The package file naming pattern has been changed from
  ``cmake-$ver-Darwin-x86_64`` to ``cmake-$ver-macos-universal``.

* Apple Silicon host architecture selection support was updated.
  CMake 3.19.0 and 3.19.1 always chose ``arm64`` as the host architecture.
  CMake 3.19.2 returns to using ``uname -m`` as CMake 3.18 and below did.
  Since this may vary based on CMake's own architecture and that of
  the invoking process tree, the :variable:`CMAKE_APPLE_SILICON_PROCESSOR`
  variable or :envvar:`CMAKE_APPLE_SILICON_PROCESSOR` environment
  variable may be set to specify a host architecture explicitly.

* The :variable:`CMAKE_ISPC_HEADER_SUFFIX` variable and corresponding
  :prop_tgt:`ISPC_HEADER_SUFFIX` target property were added to control
  the header suffix used by ``ISPC`` compiler generated headers.

3.19.3
------

* A precompiled Linux ``aarch64`` binary is now provided on ``cmake.org``.

* Two precompiled macOS binaries are now provided on ``cmake.org``:

  * The naming pattern ``cmake-$ver-macos-universal`` is a universal
    binary with ``x86_64`` and ``arm64`` architectures.  It requires
    macOS 10.13 or newer.

  * The naming pattern ``cmake-$ver-macos10.10-universal`` is a universal
    binary with ``x86_64`` and ``arm64`` architectures.  It requires
    macOS 10.10 or newer.

3.19.4
------

* The :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM`
  variable introduced in 3.19.0 previously worked only with the
  :generator:`Visual Studio 14 2015` generator.  It has now been fixed to
  work with :ref:`Visual Studio Generators` for later VS versions too.

3.19.5
------

* When :prop_tgt:`IOS_INSTALL_COMBINED` is enabled and the :generator:`Xcode`
  generator is used, it is now possible to initiate an install or package
  creation by running ``cmake --install`` or ``cpack`` from the command line.
  When using the Xcode new build system, these are the only supported methods
  due to a limitation of Xcode.  Initiating these operations by building the
  ``install`` or ``package`` targets in Xcode is only supported when using
  the legacy build system.

* The framework handling introduced in 3.19.0 as part of supporting Xcode's
  *Link Binaries With Libraries* build phase broke the ability to switch
  between device and simulator builds without reconfiguring.  That capability
  has now been restored.

3.19.6
------

* The :manual:`cmake-presets(7)` feature no longer allows comments in
  ``CMakePresets.json`` or ``CMakeUserPresets.json`` files.
  This was mistakenly allowed by the implementation in CMake 3.19.0 through
  CMake 3.19.5, and was not documented.

3.19.7
------

* With :ref:`Visual Studio Generators` for VS 2017 and higher, the
  :variable:`CMAKE_GENERATOR_TOOLSET` field ``version=`` now accepts
  three-component MSVC toolset versions such as ``14.28.29910``.
  See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_VERSION` variable.


code:
CMake 3.2 Release Notes
***********************

.. only:: html

  .. contents::

Changes made since CMake 3.1 include the following.

New Features
============

Syntax
------

* CMake learned to support unicode characters
  :ref:`encoded as UTF-8 <CMake Language Encoding>`
  on Windows.  This was already supported on platforms whose
  system APIs accept UTF-8 encoded strings.
  Unicode characters may now be used in CMake code, paths to
  source files, configured files such as ``.h.in`` files, and
  other files read and written by CMake.  Note that because CMake
  interoperates with many other tools, there may still be some
  limitations when using certain unicode characters.

Commands
--------

* The :command:`add_custom_command` and :command:`add_custom_target`
  commands learned a new ``BYPRODUCTS`` option to specify files
  produced as side effects of the custom commands.  These are not
  outputs because they do not always have to be newer than inputs.

* The :command:`add_custom_command` and :command:`add_custom_target`
  commands learned a new ``USES_TERMINAL`` option to request that
  the command be given direct access to the terminal if possible.
  The :generator:`Ninja` generator will places such commands in the
  ``console`` :prop_gbl:`pool <JOB_POOLS>`.  Build targets provided by CMake
  that are meant for individual interactive use, such as ``install``, are now
  placed in this pool.

* A new :command:`continue` command was added that can be called inside loop
  contexts to end the current iteration and start the next one at the top of
  the loop block.

* The :command:`file(LOCK)` subcommand was created to allow CMake
  processes to synchronize through file and directory locks.

* The :command:`file(STRINGS)` now supports UTF-16LE, UTF-16BE,
  UTF-32LE, UTF-32BE as ``ENCODING`` options.

* The :command:`install(EXPORT)` command now works with an absolute
  ``DESTINATION`` even if targets in the export set are installed
  with a destination or :ref:`usage requirements <Target Usage Requirements>`
  specified relative to the install prefix.  The value of the
  :variable:`CMAKE_INSTALL_PREFIX` variable is hard-coded into the installed
  export file as the base for relative references.

* The :command:`try_compile` command source file signature now honors
  link flags (e.g. :variable:`CMAKE_EXE_LINKER_FLAGS`) in the generated
  test project.  See policy :policy:`CMP0056`.

* The :command:`try_run` command learned to honor the ``LINK_LIBRARIES``
  option just as :command:`try_compile` already does.

* The :command:`file(GENERATE)` command now generates the output file with
  the same permissions as the input file if set.

* The :command:`file(GENERATE)` command can now generate files which are
  used as source files for buildsystem targets.  Generated files
  automatically get their :prop_sf:`GENERATED` property set to ``TRUE``.

Variables
---------

* The :variable:`CMAKE_MATCH_COUNT` variable was introduced to record the
  number of matches made in the last regular expression matched in an
  :command:`if` command or a :command:`string` command.

Properties
----------

* An :prop_tgt:`ANDROID_API_MIN` target property was introduced to
  specify the minimum version to be targeted by the toolchain.

* A :prop_sf:`VS_SHADER_FLAGS` source file property was added to specify
  additional shader flags to ``.hlsl`` files, for the Visual Studio
  generators.

Modules
-------

* The :module:`ExternalData` module learned to support
  :ref:`Custom Fetch Scripts <ExternalData Custom Fetch Scripts>`.
  This allows projects to specify custom ``.cmake`` scripts for
  fetching data objects during the build.

* The :module:`ExternalProject` module learned options to create
  independent external project step targets that do not depend
  on the builtin steps.

* The :module:`ExternalProject` module :command:`ExternalProject_Add`
  command learned a new ``CMAKE_CACHE_DEFAULT_ARGS`` option to
  initialize cache values in the external project without setting
  them on future builds.

* The :module:`ExternalProject` module :command:`ExternalProject_Add`
  command learned a new ``TEST_EXCLUDE_FROM_MAIN`` option to exclude
  tests from the main build.

* The :module:`ExternalProject` module :command:`ExternalProject_Add`
  command learned a new ``UPDATE_DISCONNECTED`` option to avoid
  automatically updating the source tree checkout from version control.

* The :module:`FindCUDA` module learned about the ``cusolver``
  library in CUDA 7.0.

* The :module:`FindGit` module learned to find the ``git`` command-line tool
  that comes with GitHub for Windows installed in user home directories.

* A :module:`FindGSL` module was introduced to find the
  GNU Scientific Library.

* A :module:`FindIntl` module was introduced to find the
  Gettext ``libintl`` library.

* The :module:`FindLATEX` module learned to support components.

* The :module:`FindMPI` module learned to find MS-MPI on Windows.

* The :module:`FindOpenSSL` module now reports ``crypto`` and ``ssl``
  libraries separately in ``OPENSSL_CRYPTO_LIBRARY`` and
  ``OPENSSL_SSL_LIBRARY``, respectively, to allow applications to
  link to one without the other.

* The :module:`WriteCompilerDetectionHeader` module learned to
  create a define for portability of the ``cxx_thread_local`` feature.
  The define expands to either the C++11 ``thread_local`` keyword, or a
  pre-standardization compiler-specific equivalent, as appropriate.

* The :module:`WriteCompilerDetectionHeader` module learned to create
  multiple output files per compiler and per language, instead of creating
  one large file.

CTest
-----

* The :command:`ctest_coverage` command learned to support Delphi coverage.

* The :command:`ctest_coverage` command learned to support Javascript coverage.

* The :module:`CTestCoverageCollectGCOV` module was introduced as an
  alternative to the :command:`ctest_coverage` command for collecting
  ``gcov`` results for submission to CDash.

CPack
-----

* The :cpack_gen:`CPack RPM Generator` learned options to set per-component
  descriptions and summaries.  See the
  :variable:`CPACK_RPM_<component>_PACKAGE_DESCRIPTION` and
  :variable:`CPACK_RPM_<component>_PACKAGE_SUMMARY` variables.

* The :cpack_gen:`CPack RPM Generator` learned options to specify
  requirements for pre- and post-install scripts.  See the
  :variable:`CPACK_RPM_PACKAGE_REQUIRES_PRE` and
  :variable:`CPACK_RPM_PACKAGE_REQUIRES_POST` variables.

* The :cpack_gen:`CPack RPM Generator` learned options to specify
  requirements for pre- and post-uninstall scripts.  See the
  :variable:`CPACK_RPM_PACKAGE_REQUIRES_PREUN` and
  :variable:`CPACK_RPM_PACKAGE_REQUIRES_POSTUN` variables.

* The :cpack_gen:`CPack RPM Generator` learned a new
  :variable:`CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX` variable to
  specify a component-specific value to use instead of
  :variable:`CPACK_PACKAGING_INSTALL_PREFIX`.

* The :cpack_gen:`CPack RPM Generator` learned a new
  :variable:`CPACK_RPM_RELOCATION_PATHS` variable to
  specify multiple relocation prefixes for a single rpm package.

Other
-----

* The :manual:`cmake(1)` ``-E tar`` command now supports creating
  ``.xz``-compressed archives with the ``J`` flag.

* The :manual:`cmake(1)` ``-E tar`` command learned a new
  ``--files-from=<file>`` option to specify file names using
  lines in a file to overcome command-line length limits.

* The :manual:`cmake(1)` ``-E tar`` command learned a new
  ``--mtime=<date>`` option to specify the modification time
  recorded in tarball entries.

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
  is now aware of features supported by more compilers, including:

  * Apple Clang (``AppleClang``) for Xcode versions 4.4 though 6.1.
  * GNU compiler versions 4.4 through 5.0 on UNIX and Apple (``GNU``).
  * Microsoft Visual Studio (``MSVC``) for versions 2010 through 2015.
  * Oracle SolarisStudio (``SunPro``) version 12.4.

* The :ref:`Qt AUTORCC` feature now tracks files listed in ``.qrc`` files
  as dependencies. If an input file to the ``rcc`` tool is changed, the tool
  is automatically re-run.

New Diagnostics
===============

* The :command:`break` command now rejects calls outside of a loop
  context or that pass arguments to the command.
  See policy :policy:`CMP0055`.

Deprecated and Removed Features
===============================

* Files written in the :manual:`cmake-language(7)`, such as
  ``CMakeLists.txt`` or ``*.cmake`` files, are now expected to be
  encoded as UTF-8.  If files are already ASCII, they will be
  compatible.  If files were in a different encoding, including
  Latin 1, they will need to be converted.

* The :module:`FindOpenGL` module no longer explicitly searches
  for any dependency on X11 libraries with the :module:`FindX11`
  module.  Such dependencies should not need to be explicit.
  Applications using X11 APIs themselves should find and link
  to X11 libraries explicitly.

* The implementation of CMake now relies on some C++ compiler features which
  are not supported by some older compilers.  As a result, those old compilers
  can no longer be used to build CMake itself.  CMake continues to be able to
  generate Makefiles and project files for users of those old compilers
  however.  Compilers known to no longer be capable of building CMake are:

  * Visual Studio 6 and 7.0 -- superseded by VisualStudio 7.1 and newer.
  * GCC 2.95 -- superseded by GCC 3 and newer compilers.
  * Borland compilers -- superseded by other Windows compilers.
  * Compaq compilers -- superseded by other compilers.
  * SGI compilers -- IRIX was dropped as a host platform.

Other Changes
=============

* On Windows and OS X, commands supporting network communication
  via ``https``, such as :command:`file(DOWNLOAD)`,
  :command:`file(UPLOAD)`, and :command:`ctest_submit`, now support
  SSL/TLS even when CMake is not built against OpenSSL.
  The Windows or OS X native SSL/TLS implementation is used by default.
  OS-configured certificate authorities will be trusted automatically.

  On other platforms, when CMake is built with OpenSSL, these
  commands now search for OS-configured certificate authorities
  in a few ``/etc`` paths to be trusted automatically.

* On OS X with Makefile and Ninja generators, when a compiler is found
  in ``/usr/bin`` it is now mapped to the corresponding compiler inside
  the Xcode application folder, if any.  This allows such build
  trees to continue to work with their original compiler even when
  ``xcode-select`` switches to a different Xcode installation.

* The Visual Studio generators now write solution and project
  files in UTF-8 instead of Windows-1252.  Windows-1252 supported
  Latin 1 languages such as those found in North and South America
  and Western Europe.  With UTF-8, additional languages are now
  supported.

* The :generator:`Xcode` generator no longer requires a value for
  the :variable:`CMAKE_MAKE_PROGRAM` variable to be located up front.
  It now locates ``xcodebuild`` when needed at build time.

* When building CMake itself using SolarisStudio 12, the default ``libCStd``
  standard library is not sufficient to build CMake.  The SolarisStudio
  distribution supports compiler options to use ``STLPort4`` or ``libstdc++``.
  An appropriate option to select the standard library is now added
  automatically when building CMake with SolarisStudio compilers.


code:
CMake 3.20 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.19 include the following.

New Features
============

Presets
-------

* :manual:`cmake-presets(7)` gained support for build and test presets.

Generators
----------

* :ref:`Makefile Generators`, for some toolchains, now use the compiler
  to extract implicit dependencies while compiling source files.

Languages
---------

* C++23 compiler modes may now be specified via the :prop_tgt:`CXX_STANDARD`,
  :prop_tgt:`CUDA_STANDARD`, or :prop_tgt:`OBJCXX_STANDARD` target properties,
  or via the :manual:`Compile Features <cmake-compile-features(7)>`
  functionality's ``cxx_std_23`` meta-feature.

* ``CUDA`` language support now works when ``nvcc`` is a symbolic link,
  for example due to a ``ccache`` or ``colornvcc`` wrapper script.

* The :envvar:`CUDAARCHS` environment variable was added for initializing
  :variable:`CMAKE_CUDA_ARCHITECTURES`. Useful in cases where the compiler
  default is unsuitable for the machine's GPU.

Compilers
---------

* The NVIDIA HPC SDK compilers are now supported with compiler id ``NVHPC``.

* The Intel oneAPI NextGen LLVM compilers are now supported with
  compiler id ``IntelLLVM``:

  * The ``icx``/``icpx`` C/C++ compilers on Linux, and the ``icx``
    C/C++ compiler on Windows, are fully supported as of oneAPI 2021.1.

  * The ``ifx`` Fortran compiler on Linux is supported as of oneAPI 2021.1.

  * The ``ifx`` Fortran compiler on Windows is not yet supported.

  The Intel oneAPI Classic compilers (``icc``, ``icpc``, and ``ifort``)
  continue to be supported with compiler id ``Intel``.

* Support was added for the IAR STM8 compiler.

Platforms
---------

* CMake's support for :ref:`Cross Compiling for Android`
  is now merged with the Android NDK's toolchain file.
  They now have similar behavior, though some variable names differ.
  User-facing changes include:

  - ``find_*`` functions will search NDK ABI / API specific paths by default.

  - The default :variable:`CMAKE_BUILD_TYPE` for Android is
    now ``RelWithDebInfo``.

  - The :variable:`CMAKE_ANDROID_NDK_VERSION` variable was added to
    report the version of the NDK.

File-Based API
--------------

* The :manual:`cmake-file-api(7)` gained a new "toolchains" object
  kind that describes the compiler used for each enabled language.

Commands
--------

* :command:`add_custom_command` and :command:`add_custom_target` now
  support :manual:`generator expressions <cmake-generator-expressions(7)>`
  in their ``OUTPUT`` and ``BYPRODUCTS`` options.

  Their ``COMMAND``, ``WORKING_DIRECTORY``, and ``DEPENDS`` options gained
  support for new generator expressions :genex:`$<COMMAND_CONFIG:...>` and
  :genex:`$<OUTPUT_CONFIG:...>` that control cross-config handling when using
  the :generator:`Ninja Multi-Config` generator.

* The :command:`add_custom_command` command gained ``DEPFILE`` support on
  :ref:`Makefile Generators`.

* The :command:`add_library` command previously prohibited imported object
  libraries when using potentially multi-architecture configurations.
  This mostly affected the :generator:`Xcode` generator, e.g. when targeting
  iOS or one of the other device platforms.  This restriction has now been
  removed.

* The :command:`cmake_path` command was added for operations on
  filesystem paths.

* The :command:`configure_file` command gained ``USE_SOURCE_PERMISSIONS``
  and ``FILE_PERMISSIONS`` options to support copying of permissions of the
  source file and using specified permissions respectively.

* The :command:`file(GENERATE)` command gained a ``NEWLINE_STYLE`` option to
  specify how newlines are handled for the generated file.

* The :command:`file(GENERATE)` command gained ``NO_SOURCE_PERMISSIONS``,
  ``USE_SOURCE_PERMISSIONS``, and ``FILE_PERMISSIONS`` options for controlling
  the permissions of the generated file.

* The :command:`install(FILES)` command ``RENAME`` option learned to
  support :manual:`generator expressions <cmake-generator-expressions(7)>`.

* The :command:`target_include_directories` command gained a new option
  ``AFTER``.

* The :command:`target_sources` command now supports targets created
  by the :command:`add_custom_target` command.

* The :command:`try_run` command gained a ``WORKING_DIRECTORY`` option to
  set the working directory in which to run the compiled check executable.

Variables
---------

* The :variable:`CMAKE_<LANG>_BYTE_ORDER` variable was added to provide the
  target architecture byte order detected from the toolchain.

* The :variable:`CMAKE_RUNTIME_OUTPUT_DIRECTORY`,
  :variable:`CMAKE_LIBRARY_OUTPUT_DIRECTORY`, and
  :variable:`CMAKE_ARCHIVE_OUTPUT_DIRECTORY` variables now support
  target-dependent generator expressions.

Properties
----------

* The :prop_tgt:`<LANG>_CLANG_TIDY` target property and the associated
  :variable:`CMAKE_<LANG>_CLANG_TIDY` variable learned to support
  the ``OBJC`` and ``OBJCXX`` languages.

* The :prop_tgt:`EXPORT_COMPILE_COMMANDS` target property was added
  for the associated :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable
  to allow for configuration of exporting compile commands per target.

* The :prop_sf:`GENERATED` source-file property is now visible
  from any directory scope, regardless of the scope in which it is set.
  See policy :policy:`CMP0118`.

* The :prop_tgt:`UNITY_BUILD_UNIQUE_ID` target property
  was added to support generation of an identifier that is
  unique per source file in unity builds.  It can help to
  resolve duplicate symbol problems with anonymous namespaces.

* The :prop_tgt:`WIN32_EXECUTABLE` target property now works with Clang
  on Windows.

* The :prop_tgt:`XCODE_EMBED_FRAMEWORKS <XCODE_EMBED_<type>>` target property
  was added to tell the :generator:`Xcode` generator to embed frameworks.
  Aspects of the embedding can be customized with the
  :prop_tgt:`XCODE_EMBED_FRAMEWORKS_PATH <XCODE_EMBED_<type>>`,
  :prop_tgt:`XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY`, and
  :prop_tgt:`XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY` target properties.

Modules
-------

* The :module:`ExternalData` module :command:`ExternalData_Add_Target`
  function gained a ``SHOW_PROGRESS <bool>`` option for controlling whether
  or not to show progress output during the build.

* The :module:`ExternalProject` module :command:`ExternalProject_Add` function
  gained a ``CONFIGURE_HANDLED_BY_BUILD`` option.  This can be used to make
  subsequent runs of the configure step be triggered by the build step when
  an external project dependency rebuilds instead of always re-running the
  configure step in such cases.

* The :module:`FindBoost` module gained a ``Boost_NO_WARN_NEW_VERSIONS``
  option to silence the warning about unknown dependencies for new
  Boost versions.

* The :module:`FindCUDAToolkit` module gained support for finding CUDA
  toolkits when ``nvcc`` is a symbolic link,
  for example due to a ``ccache`` or ``colornvcc`` wrapper script.

* The :module:`FindGDAL` module has been improved to document and mark as
  advanced its cache variables. There is a new ``FindGDAL_SKIP_GDAL_CONFIG``
  variable which may be used to skip over the ``gdal-config``-based search.
  Users may also set ``GDAL_ADDITIONAL_LIBRARY_VERSIONS`` to add additional
  versions to the library name search strategy.

* The :module:`FindIntl` module now provides an imported target.

* The :module:`FindOpenSSL` module learned to support a version range.

* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
  modules gained options controlling how unversioned interpreter names are
  searched.

* The :module:`UseJava` module ``add_jar()`` command's
  ``GENERATE_NATIVE_HEADERS`` feature gained options to export the
  generated target.

* The :module:`UseSWIG` module gained the capability, for
  :ref:`Makefile <Makefile Generators>` and :ref:`Ninja <Ninja Generators>`
  generators, to use the ``swig`` tool to generate implicit dependencies.

Autogen
-------

* The :ref:`Qt AUTOMOC` feature now works with per-config sources.

CTest
-----

* :manual:`ctest(1)` gained a :option:`--test-dir <ctest --test-dir>`
  option to specify the directory in which to look for tests.

CPack
-----

* :module:`CPack` gained the :variable:`CPACK_THREADS` variable to
  control the number of threads used for parallelized operations,
  such as compressing the installer package.

* The :cpack_gen:`CPack DEB Generator` learned a new
  :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS_PRIVATE_DIRS`
  variable to specify additional search directories for
  resolving private library dependencies when using
  ``dpkg-shlibdeps``.

* The :cpack_gen:`CPack IFW Generator` gained a new
  :variable:`CPACK_IFW_PACKAGE_WIZARD_SHOW_PAGE_LIST` variable to
  control visibility of the widget listing installer pages on the left side
  of the wizard. This feature available only since QtIFW 4.0.

* The :cpack_gen:`CPack NSIS Generator` gained new
  :variable:`CPACK_NSIS_BRANDING_TEXT` and
  :variable:`CPACK_NSIS_BRANDING_TEXT_TRIM_POSITION` variables to change
  the text at the bottom of the install window and change its trim position

* The :cpack_gen:`CPack NSIS Generator` now correctly handles Unicode
  characters.  If you want to have a :variable:`CPACK_RESOURCE_FILE_LICENSE`
  with UTF-8 characters, it needs to be encoded in UTF-8 BOM.

* The :cpack_gen:`CPack NuGet Generator` gained options:

  - :variable:`CPACK_NUGET_PACKAGE_ICON` and
    :variable:`CPACK_NUGET_<compName>_PACKAGE_ICON`
    allow package icons to be specified by local files.
  - :variable:`CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION` and
    :variable:`CPACK_NUGET_<compName>_PACKAGE_LICENSE_EXPRESSION` add
    support for specifying licenses recognized by the
    `Software Package Data Exchange`_ (SPDX).
  - :variable:`CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME` and
    :variable:`CPACK_NUGET_<compName>_PACKAGE_LICENSE_FILE_NAME` allow
    licenses to be specified by local files.
  - :variable:`CPACK_NUGET_PACKAGE_LANGUAGE` and
    :variable:`CPACK_NUGET_<compName>_PACKAGE_LANGUAGE` allow the locale
    for a package to be specified, for example ``en_CA``.

.. _Software Package Data Exchange: https://spdx.dev/

Deprecated and Removed Features
===============================

* The :manual:`cmake-server(7)` mode has been removed.
  Clients should use the :manual:`cmake-file-api(7)` instead.

* The :module:`WriteCompilerDetectionHeader` module has been deprecated
  via policy :policy:`CMP0120`.  Projects should be ported away from it.

* The :module:`TestBigEndian` module has been deprecated in favor
  of the :variable:`CMAKE_<LANG>_BYTE_ORDER` variable.

* The :module:`AddFileDependencies` module is deprecated.
  Port projects to use :command:`set_property` directly.

* The :cpack_gen:`CPack NuGet Generator` deprecated some variables to reflect
  changes in the NuGet specification:

  - :variable:`CPACK_NUGET_PACKAGE_ICONURL` and
    :variable:`CPACK_NUGET_<compName>_PACKAGE_ICONURL` have been deprecated;
    replace with a reference to a local icon file.
  - :variable:`CPACK_NUGET_PACKAGE_LICENSEURL` and
    :variable:`CPACK_NUGET_<compName>_PACKAGE_LICENSEURL` have been deprecated;
    replace with a reference to the project's license file or SPDX
    license expression.

Other Changes
=============

* When running :manual:`cmake(1)` to :ref:`Generate a Project Buildsystem`,
  unknown command-line arguments starting with a hyphen (``-``) are now
  rejected with an error.  Previously they were silently ignored.

* Source file extensions must now be explicit.
  See policy :policy:`CMP0115` for details.

* The :prop_sf:`LANGUAGE` source file property now forces compilation
  as the specified language.  See policy :policy:`CMP0119`.

* On AIX, installation of XCOFF executables and shared libraries
  no longer requires relinking to change the runtime search path
  from the build-tree RPATH to the install-tree RPATH.  CMake now
  edits the XCOFF binaries directly during installation, as has
  long been done on ELF platforms.

* With MSVC-like compilers the value of
  :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` no longer contains
  the ``/GR`` flag for runtime type information by default.
  See policy :policy:`CMP0117`.

* Ninja generators now transform the ``DEPFILE`` generated by an
  :command:`add_custom_command`. See policy :policy:`CMP0116` for details.

* The precompiled Linux binaries provided on
  `cmake.org <https://cmake.org/download/>`_ have changed their naming pattern
  to ``cmake-$ver-linux-$arch``, where ``$arch`` is either ``x86_64`` or
  ``aarch64``.

* The precompiled Windows binaries provided on
  `cmake.org <https://cmake.org/download/>`_ have changed their naming pattern
  to ``cmake-$ver-windows-$arch``, where ``$arch`` is either ``x86_64`` or
  ``i386``.

Updates
=======

Changes made since CMake 3.20.0 include the following.

3.20.1
------

* The :module:`FindIntl` module in CMake 3.20.0 added checks
  ``Intl_HAVE_GETTEXT_BUILTIN``, ``Intl_HAVE_DCGETTEXT_BUILTIN``,
  and ``Intl_IS_BUILTIN``, but they were not implemented correctly.
  These have been removed and replaced with a single ``Intl_IS_BUILT_IN``
  check, whose name is consistent with the :module:`FindIconv` module.

* The ``-rpath`` linker flag is now specified as supported on all Apple
  platforms, not just macOS.  The ``install_name_dir`` used for
  iOS, tvOS and watchOS should now default to ``@rpath`` instead of using
  a full absolute path and failing at runtime when the library or framework
  is embedded in an application bundle (see :prop_tgt:`XCODE_EMBED_<type>`).

3.20.2
------

* The Intel Classic 2021 compiler version numbers are now detected correctly
  as having major version 2021.  CMake 3.20.1 and below were not aware of a
  change to the identification macro version scheme made by Intel starting
  in version 2021, and detected the version as 20.2.

* The Intel oneAPI Fortran compiler is now identified as ``IntelLLVM``.
  The oneAPI 2021.1 Fortran compiler is missing an identification macro,
  so CMake 3.20.1 and below identified it as ``Intel``.  CMake now has
  a special case to recognize oneAPI 2021.1 Fortran as ``IntelLLVM``.
  The oneAPI 2021.2 Fortran compiler defines the proper identification
  macro and so is identified as ``IntelLLVM`` by all CMake 3.20 versions.

3.20.3, 3.20.4, 3.20.5, 3.20.6
------------------------------

These versions made no changes to documented features or interfaces.
Some implementation updates were made to support ecosystem changes
and/or fix regressions.


code:
CMake 3.21 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.20 include the following.

New Features
============

Presets
-------

* :manual:`cmake-presets(7)` gained support for specifying the install prefix
  in a configure preset.

* :manual:`cmake-presets(7)` gained support for conditional enabling of presets.

* :manual:`cmake-presets(7)` gained support for a ``${hostSystemName}`` macro.

* :manual:`cmake-presets(7)` gained support for omitting the ``generator`` and
  ``binaryDir`` fields.

Generators
----------

* The :generator:`Visual Studio 17 2022` generator was added.

* The :ref:`Makefile Generators` and the :generator:`Ninja` generator
  learned to add linker launcher tools along with the linker for ``C``,
  ``CXX``, ``OBJC``, and ``OBJCXX`` languages.
  See the :variable:`CMAKE_<LANG>_LINKER_LAUNCHER` variable
  and :prop_tgt:`<LANG>_LINKER_LAUNCHER` target property for details.

Languages
---------

* CMake learned to support ``HIP`` as a first-class language that can be
  enabled via the :command:`project` and :command:`enable_language` commands.

* :prop_tgt:`C_STANDARD`, :prop_tgt:`OBJC_STANDARD`, and the
  :manual:`Compile Features <cmake-compile-features(7)>` functionality gained
  support for C17 and C23.

* Source file extensions ``.ixx`` and ``.cppm`` are now treated as C++.

Command-Line
------------

* :manual:`cmake(1)` gained the :option:`--install-prefix <cmake --install-prefix>`
  command-line option to specify the location of the install prefix.

* :manual:`cmake(1)` gained the :option:`--toolchain <cmake --toolchain>`
  command-line option to specify a toolchain file.

* :manual:`cmake(1)` :option:`-E capabilities <cmake-E capabilities>` output,
  for some generators, may now contain a ``supportedPlatforms`` field listing
  platforms known to be supported in :variable:`CMAKE_GENERATOR_PLATFORM`.

* Messages printed to a terminal now may be colored by message type.

Compilers
---------

* The Fujitsu compiler is now supported using compiler id ``Fujitsu``
  in traditional (``Trad``) mode, and compiler id ``FujitsuClang``
  in ``Clang`` mode.

Platforms
---------

* CMake now supports the MSYS runtime environment, much like CYGWIN.

File-Based API
--------------

* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field
  has been updated to 2.3.

* The :manual:`cmake-file-api(7)` "codemodel" version 2 gained a
  new "directory" object containing directory-level information.
  This includes a list of installers generated by the :command:`install`
  command.

Commands
--------

* The :command:`add_custom_command` command ``DEPFILE`` option:

  * may now use
    :manual:`generator expressions <cmake-generator-expressions(7)>`,

  * is now supported by :ref:`Visual Studio Generators` for VS 2012
    and above, and

  * is now supported by the :generator:`Xcode` generator.

* The :command:`add_custom_command(TARGET)` command
  (for :ref:`Build Events <add_custom_command(TARGET)>`)
  gained support for resolving target-dependent generator expressions.

* The :command:`build_command` command gained a ``PARALLEL_LEVEL`` option.

* The :command:`file(COPY_FILE)` command was added to copy a single file.

* The :command:`file(GET_RUNTIME_DEPENDENCIES)` command gained new
  ``POST_INCLUDE_FILES`` and ``POST_EXCLUDE_FILES`` arguments.

* The :command:`file(REAL_PATH)` command gained the option ``EXPAND_TILDE`` to
  replace any leading tilde with the path to the user's home directory.

* The :command:`file(RENAME)` command learned to optionally capture
  failure in a result variable.  It also gained a ``NO_REPLACE``
  option to fail if the destination exists.

* The :command:`install` command gained a new ``IMPORTED_RUNTIME_ARTIFACTS``
  mode, which can be used to install the runtime artifacts of imported targets.

* The :command:`install` command gained a new ``RUNTIME_DEPENDENCY_SET`` mode,
  which can be used to install runtime dependencies using
  :command:`file(GET_RUNTIME_DEPENDENCIES)`.

* The :command:`install(TARGETS)` command gained new ``RUNTIME_DEPENDENCIES``
  and ``RUNTIME_DEPENDENCY_SET`` arguments, which can be used to install
  runtime dependencies using :command:`file(GET_RUNTIME_DEPENDENCIES)`.

* The :command:`install(SCRIPT|CODE)` command
  supports a new option ``ALL_COMPONENTS`` which allows
  the corresponding code to run for every component of
  a per component installation.

* The :command:`project` command now sets variables
  :variable:`PROJECT_IS_TOP_LEVEL` and :variable:`<PROJECT-NAME>_IS_TOP_LEVEL`
  to indicate whether it was called in a top-level ``CMakeLists.txt`` file.

Variables
---------

* The :envvar:`CMAKE_TOOLCHAIN_FILE` environment variable was added to
  provide a default value for the :variable:`CMAKE_TOOLCHAIN_FILE` variable.

Properties
----------

* The :prop_dir:`IMPORTED_TARGETS` directory property was added to
  get a list of :ref:`Imported Targets` created in the current
  directory.

* The :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS <XCODE_EMBED_<type>>` target property
  was added to tell the :generator:`Xcode` generator to embed app extensions
  such as iMessage sticker packs.
  Aspects of the embedding can be customized with the
  :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_PATH <XCODE_EMBED_<type>>`,
  :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_CODE_SIGN_ON_COPY <XCODE_EMBED_<type>_CODE_SIGN_ON_COPY>` and
  :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPY <XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY>`
  properties.

Modules
-------

* The :module:`FindBLAS` and :module:`FindLAPACK` modules learned to support
  the serial ``Fujitsu_SSL2`` and parallel ``Fujitsu_SSL2BLAMP`` libraries.

* The :module:`FindDevIL` module now provides imported targets.

* The :module:`FindIconv` module now has version support.

* The :module:`FindIntl` module now has version support.

* The :module:`FindMPI` module learned to support ``Fujitsu`` and
  ``FujitsuClang`` in both host and cross compiling modes.

* The :module:`FindMsys` module was added to find MSYS installations.
  Like :module:`FindCygwin`, it is used automatically by some other
  find modules to locate UNIX-style tools on Windows.

* The :module:`FindOpenMP` module learned to support ``Fujitsu`` and
  ``FujitsuClang``.

* The :module:`FindVulkan` module gained imported targets
  ``Vulkan::Headers`` and ``Vulkan::glslangValidator``.

* The :module:`UseJava` module command ``add_jar`` gained a ``RESOURCES``
  option to allow explicit naming of resources with non-optional namespace.

* The :module:`UseSWIG` module use now standard library naming conventions
  for the ``CSharp`` language. See policy :policy:`CMP0122`.

* The :module:`UseSWIG` module now supports using the ``swig`` tool to
  generate implicit dependencies with the :generator:`Xcode` generator.

Generator Expressions
---------------------

* A new :genex:`TARGET_RUNTIME_DLLS` generator expression was added.

CTest
-----

* :manual:`ctest(1)` gained documentation for its ability to capture
  :ref:`Additional Test Measurements`.

* :manual:`ctest(1)` learned to recognize files attached to a test at run time.
  Previously it was only possible to attach files to tests at configure time
  by using the :prop_test:`ATTACHED_FILES` or
  :prop_test:`ATTACHED_FILES_ON_FAIL` test properties.
  See :ref:`Additional Test Measurements` for more information.

* :manual:`ctest(1)` gained a :option:`--output-junit <ctest --output-junit>`
  option to write test results to a JUnit XML file.

* The :command:`ctest_build` command gained a ``PARALLEL_LEVEL`` option.

CPack
-----

* The :cpack_gen:`CPack DragNDrop Generator` gained option
  :variable:`CPACK_DMG_FILESYSTEM` to control the ``.dmg`` filesystem.

* The :cpack_gen:`CPack IFW Generator` now supports hyphens in names
  given to :command:`cpack_ifw_configure_component` or
  :command:`cpack_ifw_configure_component_group` as ``DEPENDS`` or
  ``DEPENDENCIES`` arguments.  This requires QtIFW 3.1 or later.

* The :cpack_gen:`CPack NSIS Generator` gained a new
  :variable:`CPACK_NSIS_EXECUTABLE` variable to specify the ``makensis``
  executable to use instead of the default one.

* The :variable:`CPACK_CUSTOM_INSTALL_VARIABLES` variable was added to set
  variables in ``cmake_install.cmake`` script invocations made by CPack.

Deprecated and Removed Features
===============================

* Undocumented :variable:`CMAKE_SYSTEM_NAME` version-stripping behavior has
  been removed entirely. If it is set by a ``-D`` flag or by a
  :manual:`toolchain file <cmake-toolchains(7)>`, it is left unaltered,
  even if it still contains a version number.
  Similar :variable:`CMAKE_HOST_SYSTEM_NAME` version-stripping behavior,
  also undocumented, has been moved earlier, before :command:`project` or
  :command:`enable_language` is called.

* ``ARMClang`` cpu/arch compile and link flags are no longer added
  automatically based on the :variable:`CMAKE_SYSTEM_PROCESSOR`
  variable or the undocumented ``CMAKE_SYSTEM_ARCH`` variable.
  They must be specified explicitly.  See policy :policy:`CMP0123`.

Other Changes
=============

* The :command:`find_file`, :command:`find_path`, :command:`find_program`,
  and :command:`find_library` commands handle cache variables in the same way
  regardless how they are defined. See policy :policy:`CMP0125` for details.

* The :command:`find_file`, :command:`find_path`, :command:`find_program`,
  and :command:`find_library` commands gained the option ``NO_CACHE`` to store
  find result in normal variable.

* The :command:`foreach` command now isolates loop variables in the loop scope.
  See policy :policy:`CMP0124` for details.

* The :command:`list` command's ``GET``, ``INSERT``, ``SUBLIST``, and
  ``REMOVE_AT`` subcommands now error with invalid (i.e., non-integer) values
  are given as any of their index arguments based on the setting of policy
  :policy:`CMP0121`.

* The :command:`set(CACHE)` command no longer removes a normal variable
  of the same name, if any. See policy :policy:`CMP0126`.

* :command:`target_link_libraries` calls referencing object libraries
  via the :genex:`TARGET_OBJECTS` generator expression now place the
  object files before all libraries on the link line, regardless of
  their specified order.  See documentation on
  :ref:`Linking Object Libraries via \$\<TARGET_OBJECTS\>` for details.

* The :ref:`Ninja Generators` now pass source files and include directories
  to the compiler using absolute paths.  This makes diagnostic messages and
  debug symbols more consistent, and matches the :ref:`Makefile Generators`.

* The :generator:`NMake Makefiles` generator now encodes the generated
  makefiles as UTF-8 with a BOM when using ``nmake`` from VS 9 or above.

* The :ref:`Visual Studio Generators` for VS 2010 and above now place
  per-source preprocessor definitions after target-wide preprocssor
  definitions.  This makes VS consistent with the :ref:`Ninja Generators`
  and the :ref:`Makefile Generators`.

* The precompiled binaries provided on
  `cmake.org <https://cmake.org/download/>`_ now support
  ``liblzma`` multi-threading.  See the :variable:`CPACK_THREADS` and
  :variable:`CPACK_ARCHIVE_THREADS` variables.

Updates
=======

Changes made since CMake 3.21.0 include the following.

3.21.1
------

* The :generator:`Visual Studio 17 2022` generator is now based on
  "Visual Studio 2022 Preview 2".  Previously it was based on "Preview 1.1".

3.21.2
------

* ``CUDA`` targets with :prop_tgt:`CUDA_SEPARABLE_COMPILATION` enabled are now
  correctly generated in non-root directories.

* The :generator:`Visual Studio 17 2022` generator is now based on
  "Visual Studio 2022 Preview 3.1".  Previously it was based on "Preview 2".

3.21.3
------

* The :generator:`Visual Studio 17 2022` generator is now based on
  "Visual Studio 2022 Preview 4".  Previously it was based on "Preview 3.1".

* The AMD ROCm Platform ``hipcc`` compiler was identified by CMake 3.21.0
  through 3.21.2 as a distinct compiler with id ``ROCMClang``.  This has
  been removed because it caused regressions.  Instead:

  * ``hipcc`` may no longer be used as a ``HIP`` compiler because it
    interferes with flags CMake needs to pass to Clang.  Use Clang directly.

  * ``hipcc`` may once again be used as a ``CXX`` compiler, and is treated as
    whatever compiler it selects underneath, as CMake 3.20 and below did.

3.21.4
------

* The :generator:`Visual Studio 17 2022` generator is now based on the
  "Visual Studio 2022" release candidates.  Previously it was based on
  preview versions.

3.21.5, 3.21.6, 3.21.7
----------------------

These versions made no changes to documented features or interfaces.
Some implementation updates were made to support ecosystem changes
and/or fix regressions.


code:
CMake 3.22 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.21 include the following.

New Features
============

Commands
--------

* The :command:`cmake_host_system_information` command can now query
  `OS identification variables`_ from the :file:`/etc/os-release` file.

* The :command:`string(TIMESTAMP)` command now supports the ``%V``
  specifier for ISO 8601 week numbers.

.. _`OS identification variables`: https://www.freedesktop.org/software/systemd/man/latest/os-release.html

Variables
---------

* The :envvar:`CMAKE_BUILD_TYPE` environment variable was added to
  provide a default value for the :variable:`CMAKE_BUILD_TYPE` variable.

* The :envvar:`CMAKE_CONFIGURATION_TYPES` environment variable was added to
  provide a default value for the :variable:`CMAKE_CONFIGURATION_TYPES`
  variable.

* The :envvar:`CMAKE_INSTALL_MODE` environment variable was added to
  tell :command:`install` rules (implemented by :command:`file(INSTALL)`)
  to install symbolic links instead of copying of files.

* The :variable:`CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG` and
  :variable:`CMAKE_LINK_WHAT_YOU_USE_CHECK` variables were added to
  control the linker flag and check used by the
  :prop_tgt:`LINK_WHAT_YOU_USE` target property.

* The :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable
  was added to turn a non-REQUIRED :command:`find_package` call into
  a REQUIRED one.

Properties
----------

* The :prop_tgt:`<LANG>_EXTENSIONS` target property is now initialized to
  :variable:`CMAKE_<LANG>_EXTENSIONS_DEFAULT`, detected from the compiler.
  See :policy:`CMP0128`.

* The :prop_sf:`VS_SETTINGS` source file property is now supported for
  all source file types.  Previously it worked only for non-built sources.

Modules
-------

* The :module:`CMakeDependentOption` module :command:`cmake_dependent_option`
  macro now supports full :ref:`Condition Syntax`.
  See policy :policy:`CMP0127`.

* The :module:`FetchContent` module now passes through the
  :variable:`CMAKE_TLS_VERIFY`, :variable:`CMAKE_TLS_CAINFO`,
  :variable:`CMAKE_NETRC` and :variable:`CMAKE_NETRC_FILE` variables (when
  defined) to the underlying :module:`ExternalProject` sub-build.
  Previously, those variables were silently ignored by :module:`FetchContent`.

* The :module:`FindBLAS` and :module:`FindLAPACK` modules gained
  a ``BLA_SIZEOF_INTEGER`` option to find a BLAS/LAPACK whose ABI
  uses a specific integer size.

* The :module:`FindJasper` module now provides an imported target.

* The :module:`FindMatlab` module now provides imported targets.

* The :module:`FindPkgConfig` module gained a :variable:`PKG_CONFIG_ARGN`
  variable to specify arguments to ``pkg-config`` calls.

* The :module:`GoogleTest` module :command:`gtest_discover_tests`
  function gained a ``TEST_FILTER`` option to filter tests using
  ``--gtest_filter`` during test discovery.

* The :module:`UseSWIG` module, for :ref:`Visual Studio Generators`,
  can now use the ``swig`` tool to generate implicit dependencies.

CTest
-----

* :manual:`ctest(1)` learned to recognize labels attached to a test at run time.
  Previously it was only possible to attach labels to tests at configure time
  by using the :prop_test:`LABELS` test property.
  See :ref:`Additional Test Measurements` for more information.

* :manual:`ctest(1)` learned to be able to modify the environment for a test
  through the :prop_test:`ENVIRONMENT_MODIFICATION` property. This is allows
  for updates to environment variables based on the environment present at
  test time.

* The :command:`ctest_memcheck` command now also generates a
  :file:`DynamicAnalysis-Test.xml` file which may be used to submit test
  results to CDash.

CPack
-----

* The :cpack_gen:`CPack DEB Generator` gained the
  option to set :variable:`CPACK_DEBIAN_COMPRESSION_TYPE` to ``zstd``,
  which enables Zstandard compression for deb packages.

* The :cpack_gen:`CPack NSIS Generator` gained a new
  :variable:`CPACK_NSIS_IGNORE_LICENSE_PAGE` variable to suppress
  the license page in the installer.

* The :cpack_gen:`CPack RPM Generator` gained the
  :variable:`CPACK_RPM_REQUIRES_EXCLUDE_FROM` option to avoid scanning
  specific paths for dependencies.

Deprecated and Removed Features
===============================

* The :generator:`Visual Studio 10 2010` generator is now deprecated
  and will be removed in a future version of CMake.

Other Changes
=============

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality now
  correctly disables or enables compiler extensions when no standard level is
  specified and avoids unnecessarily adding language standard flags if the
  requested settings match the compiler's defaults. See :policy:`CMP0128`.

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
  now ignores features for languages that are not enabled.

* The :ref:`Ninja Generators` now implement the ``edit_cache`` target
  using :manual:`ccmake(1)` if available.

* The :generator:`Ninja` and :generator:`NMake Makefiles` generators
  now use the MSVC ``-external:I`` flag for system includes.
  This became available as of VS 16.10 (toolchain version 14.29.30037).

* The :cpack_gen:`CPack NSIS Generator` now requires NSIS 3.03 or later.

Updates
=======

Changes made since CMake 3.22.0 include the following.

3.22.1
------

* This version made no changes to documented features or interfaces.
  Some implementation updates were made to support ecosystem changes
  and/or fix regressions.

3.22.2
------

* The ``OLD`` behavior of :policy:`CMP0128` was fixed to add flags even when
  the specified standard matches the compiler default.

3.22.3
------

* The :command:`while` command again ignores errors in condition evaluation
  as CMake 3.21 and below did.  This bug was fixed in 3.22.0, but exposed
  errors in existing projects.  The fix has been reverted to restore
  compatibility.  The fix may be restored in a future version of CMake
  via a policy.

3.22.4, 3.22.5, 3.22.6
----------------------

* These versions made no changes to documented features or interfaces.
  Some implementation updates were made to support ecosystem changes
  and/or fix regressions.