code:
CMake 3.14 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.13 include the following.

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

Generators
----------

* The :generator:`Visual Studio 16 2019` generator was added.  This is
  experimental and based on "Visual Studio 2019 Preview 4" because this
  version of VS has not been released.

  The VS 2019 generator differs from generators for earlier versions
  in that it does not provide variants that specify the target platform
  in the generator name.  Instead :variable:`CMAKE_GENERATOR_PLATFORM`
  must be used, e.g. through the ``-A`` command-line option.  Furthermore,
  the default target platform (architecture) is now based on the *host*
  platform.  The VS host toolset selection is now based on the host
  architecture as well.

* The :generator:`Green Hills MULTI` generator has been updated:

  * Now supports :ref:`Object Libraries`.

  * Now warns on unsupported project types such as shared libraries.

  * Now generates a top-level ``<PROJECT-NAME>.top.gpj`` for each directory
    calling the :command:`project` command.  The top-level project file
    ``default.gpj`` is no longer created.

  * Now honors target renaming and destination output control properties
    such as :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` and :prop_tgt:`OUTPUT_NAME`.
    This also fixes support for installation rules generated by
    :command:`install`.

  * Now honors source file properties :prop_sf:`INCLUDE_DIRECTORIES`,
    :prop_sf:`COMPILE_DEFINITIONS`, and :prop_sf:`COMPILE_OPTIONS`.

  * Now supports Dynamic Download Integrity Applications which did not include
    Integrate Files via :prop_tgt:`GHS_INTEGRITY_APP` and setting a target
    link flag of ``-dynamic``.

  * The contents of project files now sorts sources groups and files by name.
    Set the :prop_tgt:`GHS_NO_SOURCE_GROUP_FILE` target property to ``ON`` to
    generate a single project file for the target instead of a project file for
    each source group.  Set the :variable:`CMAKE_GHS_NO_SOURCE_GROUP_FILE`
    variable to enable this for all targets.

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

* A file-based api for clients to get semantic buildsystem information
  has been added.  See the :manual:`cmake-file-api(7)` manual.
  This is intended to replace the :manual:`cmake-server(7)` mode for IDEs.

Platforms
---------

* CMake now supports
  :ref:`Cross Compiling for iOS, tvOS, or watchOS <Cross Compiling for iOS, tvOS, visionOS, or watchOS>`
  using simple toolchain files.

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

* The :manual:`cmake(1)` :ref:`Build Tool Mode <Build Tool Mode>`
  (``cmake --build``) gained ``--verbose`` and ``-v`` options to
  specify verbose build output. Some generators such as Xcode don't
  support this option currently.

* The :manual:`cmake(1)` ``-E compare_files`` command learned a new
  ``--ignore-eol`` option to specify that end-of-line differences
  (e.g. LF vs CRLF) should be ignored when comparing files.

* The :manual:`cmake-gui(1)` dialog gained new ``-S`` and ``-B`` arguments to
  explicitly specify source and build directories.

Commands
--------

* The :command:`file` command learned a new sub-command, ``CREATE_LINK``,
  which can be used to create hard or symbolic links.

* The :command:`file` command learned a new sub-command, ``READ_SYMLINK``,
  which can be used to determine the path that a symlink points to.

* The :command:`file` command gained a ``SIZE`` mode to get the size
  of a file on disk.

* The :command:`find_package` command learned to optionally resolve
  symbolic links in the paths to package configuration files.
  See the :variable:`CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS` variable.

* The :command:`get_filename_component` command gained new
  ``LAST_EXT`` and ``NAME_WLE`` variants to work with the
  extension after the last ``.`` in the name.

* The :command:`if` command gained support for checking if cache variables
  are defined with the  ``DEFINED CACHE{VAR}`` syntax.

* The :command:`install(CODE)` and :command:`install(SCRIPT)` commands
  learned to support generator expressions.  See policy :policy:`CMP0087`.

* The :command:`install(TARGETS)` command learned how to install to an
  appropriate default directory for a given target type, based on
  variables from the :module:`GNUInstallDirs` module and built-in defaults,
  in lieu of a ``DESTINATION`` argument.

* The :command:`install(FILES)` and :command:`install(DIRECTORY)` commands
  learned a new set of parameters for installing files as a file type,
  setting the destination based on the appropriate variables from
  :module:`GNUInstallDirs` and built-in defaults, in lieu of a
  ``DESTINATION`` argument.

* The :command:`list` operations ``REMOVE_ITEM``, ``REMOVE_DUPLICATES``,
  ``SORT``, ``REVERSE``, and ``FILTER`` all now accept a non-existent variable
  as the list since these operations on empty lists is also the empty list.

* The :command:`list` operation ``REMOVE_AT`` now indicates that the given
  indices are invalid for a non-existent variable or empty list.

* The :command:`try_compile` and :command:`try_run` commands gained a new
  ``LINK_OPTIONS`` option.

Variables
---------

* A :variable:`CMAKE_BUILD_RPATH_USE_ORIGIN` variable and corresponding
  :prop_tgt:`BUILD_RPATH_USE_ORIGIN` target property were added to
  enable use of relative runtime paths (RPATHs). This helps achieving
  relocatable and reproducible builds that are invariant of the build
  directory.

* A :variable:`CMAKE_VS_PLATFORM_NAME_DEFAULT` variable was added for
  :ref:`Visual Studio Generators` to report their default platform used
  when :variable:`CMAKE_GENERATOR_PLATFORM` is not set explicitly.

Properties
----------

* A :prop_gbl:`CMAKE_ROLE` global property was added to allow scripts to
  determine whether they're running in project mode, script mode,
  find-package mode, CTest, or CPack.

* The :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` target property is now supported
  on shared library, module library, and executable targets.  Previously it was
  only honored on static libraries.

* The :prop_tgt:`EXCLUDE_FROM_ALL` target property was created to override
  the setting of its directory. A target will now be built as part of "all"
  if its :prop_tgt:`EXCLUDE_FROM_ALL` property is set to ``OFF``, even if its
  containing directory is marked as :prop_dir:`EXCLUDE_FROM_ALL`.

* :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE` target property gains the
  support of :manual:`generator expressions <cmake-generator-expressions(7)>`.

Modules
-------

* The family of modules to check capabilities (like
  :module:`CheckCSourceCompiles`) gain capability to manage ``LINK_OPTIONS``.

* A :module:`CheckFortranSourceRuns` module was added to provide a
  :command:`check_fortran_source_runs` command to check if a Fortran
  source snippet compiles and runs.

* The :module:`CMakePackageConfigHelpers` module's
  :command:`write_basic_package_version_file` command gained a new
  ``ARCH_INDEPENDENT`` option for supporting architecture-independent
  packages.

* The :module:`ExternalProject` module :command:`ExternalProject_Add` command
  gained ``LOG_DIR`` and ``LOG_MERGED_STDOUTERR`` options to control logging.

* The :module:`ExternalProject` module :command:`ExternalProject_Add` command
  gained ``LOG_PATCH`` to optionally log the patch step.

* The :module:`ExternalProject` module :command:`ExternalProject_Add` command
  learned to apply ``SOURCE_SUBDIR`` when ``BUILD_IN_SOURCE`` is also used.
  The ``BUILD_COMMAND`` is run in the given ``SOURCE_SUBDIR`` of the
  ``SOURCE_DIR``.

* The :module:`FetchContent` module gained a new
  :command:`FetchContent_MakeAvailable` command.  It accepts a list of
  dependency names, which it then iterates over, populating and adding
  each one to the main build using the canonical pattern.  This
  significantly reduces the amount of boilerplate needed in a project.

* The :module:`FindBISON` module's ``BISON_TARGET`` command now runs ``bison``
  with :variable:`CMAKE_CURRENT_BINARY_DIR` as the working directory.
  See policy :policy:`CMP0088`.

* The :module:`FindCURL` module gained support for requesting
  protocols as package components.

* The :module:`FindFontconfig` module was added to find `fontconfig`_.

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

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

* The :module:`FindGit` module now provides an imported target for the
  Git executable.

* The :module:`FindIce` module learned to find ``slice2confluence``
  and ``slice2matlab``.

* The :module:`FindLibinput` module was added to find `libinput`_.

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

* The :module:`FindMatlab` module gained new options ``R2017b`` and
  ``R2018a`` to specify the MEX API version to use; these options
  mirror the new options to the ``mex`` command in MATLAB R2018a.
  The option ``MX_LIBRARY`` is no longer needed.

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

* The :module:`FindPython`, :module:`FindPython2`, and :module:`FindPython3`
  modules gained support for ``NumPy`` component.

* The :module:`FindPython2`, :module:`FindPython3`, and :module:`FindPython`
  modules now support running in script mode by skipping the creation of
  imported targets and helper functions.

* The :module:`FindSQLite3` module was added to find the SQLite v3.x library.

* The :module:`FindX11` had the following variables renamed in order to match
  their library names rather than header names. The old variables are provided
  for compatibility:

    - ``X11_Xxf86misc_INCLUDE_PATH`` instead of ``X11_xf86misc_INCLUDE_PATH``
    - ``X11_Xxf86misc_LIB`` instead of ``X11_xf86misc_LIB``
    - ``X11_Xxf86misc_FOUND`` instead of ``X11_xf86misc_FOUND``
    - ``X11_Xxf86vm_INCLUDE_PATH`` instead of ``X11_xf86vmode_INCLUDE_PATH``
    - ``X11_Xxf86vm_LIB`` instead of ``X11_xf86vmode_LIB``
    - ``X11_Xxf86vm_FOUND`` instead of ``X11_xf86vmode_FOUND``
    - ``X11_xkbfile_INCLUDE_PATH`` instead of ``X11_Xkbfile_INCLUDE_PATH``
    - ``X11_xkbfile_LIB`` instead of ``X11_Xkbfile_LIB``
    - ``X11_xkbfile_FOUND`` instead of ``X11_Xkbfile_FOUND``
    - ``X11_Xtst_INCLUDE_PATH`` instead of ``X11_XTest_INCLUDE_PATH``
    - ``X11_Xtst_LIB`` instead of ``X11_XTest_LIB``
    - ``X11_Xtst_FOUND`` instead of ``X11_XTest_FOUND``
    - ``X11_Xss_INCLUDE_PATH`` instead of ``X11_Xscreensaver_INCLUDE_PATH``
    - ``X11_Xss_LIB`` instead of ``X11_Xscreensaver_LIB``
    - ``X11_Xss_FOUND`` instead of ``X11_Xscreensaver_FOUND``

  The following variables are deprecated completely since they were
  essentially duplicates:

    - ``X11_Xinput_INCLUDE_PATH`` (use ``X11_Xi_INCLUDE_PATH``)
    - ``X11_Xinput_LIB`` (use ``X11_Xi_LIB``)
    - ``X11_Xinput_FOUND`` (use ``X11_Xi_FOUND``)

* The :module:`FindX11` now provides ``X11_Xext_INCLUDE_PATH``.

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

* The :module:`UseSWIG` module learned to pass ``-module <module_name>`` to
  the ``SWIG`` compiler if the file property ``SWIG_MODULE_NAME`` is defined.
  See policy :policy:`CMP0086`.

* The :module:`UseSWIG` module gained an option to specify
  ``SWIG`` source file extensions.

.. _`fontconfig`: https://www.freedesktop.org/wiki/Software/fontconfig/
.. _`libinput`: https://www.freedesktop.org/wiki/Software/libinput/

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

* The ``$<Fortran_COMPILER_ID:...>`` and ``$<Fortran_COMPILER_VERSION:...>``
  :manual:`generator expressions <cmake-generator-expressions(7)>` were added.

* The ``$<IN_LIST:...>`` generator expression now correctly handles an
  empty argument. See :policy:`CMP0085` for details.

Autogen
-------

* The :prop_tgt:`AUTOMOC_EXECUTABLE`, :prop_tgt:`AUTORCC_EXECUTABLE`, and
  :prop_tgt:`AUTOUIC_EXECUTABLE` target properties were added.  They all
  take a path to an executable and force automoc/autorcc/autouic to use
  this executable.

  Setting these will also prevent the configure time testing for these
  executables. This is mainly useful when you build these tools yourself.

* The new variables :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET`,
  :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET_NAME`,
  :variable:`CMAKE_GLOBAL_AUTORCC_TARGET` and
  :variable:`CMAKE_GLOBAL_AUTORCC_TARGET_NAME` control the generation
  of global ``autogen`` and ``autorcc`` targets.

* A new :variable:`CMAKE_AUTOGEN_ORIGIN_DEPENDS` variable and
  :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` target property may be set to enable or
  disable forwarding of the origin target dependencies to the corresponding
  :ref:`<ORIGIN>_autogen` target.

CTest
-----

* :manual:`ctest(1)` gained a ``--show-only=json-v1`` option to show the
  list of tests in a machine-readable JSON format.
  See the :ref:`Show as JSON Object Model` section of the manual.

* The :command:`ctest_submit` command learned a new ``Done`` part that can be used
  to inform CDash that a build is complete and that no more parts will be uploaded.

* CTest learned to accept the dashboard server submission URL from a single
  variable.  See the ``SubmitURL`` setting in :manual:`ctest(1)`,
  the :variable:`CTEST_SUBMIT_URL` variable, and the ``SUBMIT_URL``
  argument of the :command:`ctest_submit` command.

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

* An explicit deprecation diagnostic was added for policies ``CMP0064``
  and ``CMP0065`` (``CMP0063`` 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 :generator:`Xcode` generator deprecated support for Xcode
  versions prior to Xcode 5.  Support for those will be dropped in a
  future version of CMake.

* The :module:`FindQt` module is no longer used by the :command:`find_package`
  command as a find module.  This allows the Qt Project upstream to optionally
  provide its own ``QtConfig.cmake`` package configuration file and have
  applications use it via ``find_package(Qt)`` rather than
  ``find_package(Qt CONFIG)``.  See policy :policy:`CMP0084`.

* Support for running CMake on Windows XP and Windows Vista has been dropped.
  The precompiled Windows binaries provided on ``cmake.org`` now require
  Windows 7 or higher.

* CTest no longer supports submissions via ``ftp``, ``scp``, ``cp``, and
  ``xmlrpc``.  CDash is the only maintained testing dashboard for CTest,
  and it only supports submissions over ``http`` and ``https``.

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

* Object library linking has been fixed to propagate private link libraries
  of object libraries to consuming targets.

* Install rules under :command:`add_subdirectory` now interleave with those in
  the calling directory. See policy :policy:`CMP0082` for details.

* CMake now imposes a maximum recursion limit to prevent a stack overflow on
  scripts that recurse infinitely. The limit can be adjusted at runtime with
  :variable:`CMAKE_MAXIMUM_RECURSION_DEPTH`.

* When using cppcheck via the :variable:`CMAKE_<LANG>_CPPCHECK` variable
  or :prop_tgt:`<LANG>_CPPCHECK` property, the build will now fail if
  ``cppcheck`` returns non-zero as configured by its command-line options.

* Required link options to manage Position Independent Executable are now
  added when :prop_tgt:`POSITION_INDEPENDENT_CODE` is set.  The project is
  responsible for using the :module:`CheckPIESupported` module to check for
  ``PIE`` support to ensure that the :prop_tgt:`POSITION_INDEPENDENT_CODE`
  target property will be honored at link time for executables.  This behavior
  is controlled by policy :policy:`CMP0083`.

* :ref:`Visual Studio Generators` for VS 2010 and above learned
  to support the ``VS_DEBUGGER_*`` properties on targets created
  via :command:`add_custom_target`.

* The :module:`CPack` module no longer defaults to the ``paxr`` value in the
  :variable:`CPACK_DEBIAN_ARCHIVE_TYPE` variable, because ``dpkg`` has
  never supported the PAX tar format. The ``paxr`` value will be mapped
  to ``gnutar`` and a deprecation message emitted.

* CMake no longer issues a warning if a target listed in an
  :command:`install(TARGETS)` command has its :prop_tgt:`EXCLUDE_FROM_ALL`
  property set to true.

Updates
=======

Changes made since CMake 3.14.0 include the following.

3.14.1
------

* The :module:`FindFontconfig` module added by 3.14.0 accidentally
  used uppercase ``FONTCONFIG_*`` variable names that do not match
  our conventions.  3.14.1 revises the module to use ``Fontconfig_*``
  variable names.  This is incompatible with 3.14.0 but since the
  module is new in the 3.14 series usage should not yet be widespread.

3.14.3
------

* The :variable:`CMAKE_VS_PLATFORM_NAME_DEFAULT` variable was added
  to help toolchain files work with the :generator:`Visual Studio 16 2019`
  generator where the default platform now depends on the host platform.

3.14.4
------

* In CMake 3.14.0 through 3.14.3, calling :command:`target_link_libraries`
  to add ``PRIVATE`` dependencies to a static library created in another
  directory (under policy :policy:`CMP0079` ``NEW`` behavior) would
  incorrectly propagate usage requirements of those dependencies to
  dependents that link the static library.  This has been fixed.
  The bug also existed in 3.13.0 through 3.13.4 and is fixed in 3.13.5.

3.14.5
------

* Entries of the ``CPATH`` environment variable are no longer excluded
  from explicit use via :command:`include_directories` and
  :command:`target_include_directories` as they were in CMake 3.14.0
  through 3.14.4.

3.14.6
------

* In CMake 3.14.0 through 3.14.5, the :module:`FindBISON` module
  policy :policy:`CMP0088` ``NEW`` behavior accidentally interpreted
  a relative path to the ``.y`` input as relative to the build tree
  directory instead of the source tree directory.  This has been fixed.

3.14.7
------

* In CMake 3.14.0 through 3.14.6, the :prop_dir:`EXCLUDE_FROM_ALL`
  directory property was regressed from pre-3.14 behavior and caused
  targets within the directory to be excluded even from its own "all".
  This has been fixed.


code:
CMake 3.15 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.14 include the following.

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

Generators
----------

* The :generator:`Xcode` generator now supports per-target schemes.
  See the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable and
  :prop_tgt:`XCODE_GENERATE_SCHEME` target property.

* The :generator:`Green Hills MULTI` generator has been updated:

  * It now supports the :command:`add_custom_command` and
    :command:`add_custom_target` commands.

  * It is now available on Linux.

Languages
---------

* Preliminary support for the ``Swift`` language was added to the
  :generator:`Ninja` generator:

  * Use the :envvar:`SWIFTC` environment variable to specify a compiler.

  * The :prop_tgt:`Swift_DEPENDENCIES_FILE` target property and
    :prop_sf:`Swift_DEPENDENCIES_FILE` source file property were added
    to customize dependency files.

  * The :prop_tgt:`Swift_MODULE_NAME` target property was added to
    customize the Swift module name.

  * The :prop_sf:`Swift_DIAGNOSTICS_FILE` source property was added to
    indicate where to write the serialized Swift diagnostics.

  The Swift support is experimental, not considered stable, and may change
  in future releases of CMake.

Compilers
---------

* The ``Clang`` compiler variant on Windows that targets the MSVC ABI
  but has a GNU-like command line is now supported.

* Support for the Clang-based ARM compiler was added with compiler id
  ``ARMClang``.

* Support was added for the IAR compiler architectures Renesas RX,
  RL78, RH850 and Texas Instruments MSP430.

* Support was added for the IAR compilers built for Linux (IAR BuildLx).

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

* The :envvar:`CMAKE_GENERATOR` environment variable was added
  to specify a default generator to use when :manual:`cmake(1)` is
  run without a ``-G`` option.  Additionally, environment variables
  :envvar:`CMAKE_GENERATOR_PLATFORM`, :envvar:`CMAKE_GENERATOR_TOOLSET`,
  and :envvar:`CMAKE_GENERATOR_INSTANCE` were created to configure
  the generator.

* The :manual:`cmake(1)` ``--build`` tool ``--target`` parameter gained support
  for multiple targets, e.g. ``cmake --build . --target Library1 Library2``.
  It now also has a short form ``-t`` alias, e.g.
  ``cmake --build . -t Library1 Library2``.

* The :manual:`cmake(1)` command gained a new ``--install`` option.
  This may be used after building a project to run installation without
  using the generated build system or the native build tool.

* The :manual:`cmake(1)` command learned a new CLI option ``--loglevel``.

* The :manual:`cmake(1)` ``-E remove_directory`` command-line tool learned
  to support removing multiple directories.

* The :manual:`cmake(1)` ``-E tar`` tool has been improved:

  * It now continues adding files to an archive even if some of the files
    are not readable.  This behavior is more consistent with the
    classic ``tar`` tool.

  * It now parses all flags, and if an invalid flag was provided, a
    warning is issued.

  * It now displays an error if no action flag was specified, along with a
    list of possible actions: ``t`` (list), ``c`` (create) or ``x`` (extract).

  * It now supports extracting (``-x``) or listing (``-t``) only specific
    files or directories.

  * It now supports Zstandard compression with a ``--zstd`` option.
    Zstandard was designed to give a compression ratio comparable to that
    of the DEFLATE (zip) algorithm, but faster, especially for decompression.

Commands
--------

* The :command:`add_custom_command` and :command:`add_custom_target` commands
  gained a new ``JOB_POOL`` option that works with the :generator:`Ninja`
  generator to set the pool variable on the build statement.

* The :command:`add_library` command ``ALIAS`` option learned to support
  import libraries of the ``UNKNOWN`` type.

* The :command:`cmake_parse_arguments` command gained an additional
  ``<prefix>_KEYWORDS_MISSING_VALUES`` output variable to report
  keyword arguments that were given by the caller with no values.

* The :command:`execute_process` command gained a ``COMMAND_ECHO`` option
  and supporting :variable:`CMAKE_EXECUTE_PROCESS_COMMAND_ECHO` variable
  to enable echoing of the command-line string before execution.

* The :command:`file(INSTALL)` command learned a new argument,
  ``FOLLOW_SYMLINK_CHAIN``, which can be used to recursively resolve and
  install symlinks.

* :command:`list` learned new sub-commands:
  ``PREPEND``, ``POP_FRONT`` and ``POP_BACK``.

* The :command:`message` command learned new types:
  ``NOTICE``, ``VERBOSE``, ``DEBUG`` and ``TRACE``.

* The :command:`string` learned a new sub-command ``REPEAT``.

Variables
---------

* The :variable:`CMAKE_CROSSCOMPILING_EMULATOR` variable and corresponding
  :prop_tgt:`CROSSCOMPILING_EMULATOR` target property learned to support
  arguments to the emulator.

* The :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` variable was added to tell
  :command:`find_package` calls to look for a package configuration
  file first even if a find module is available.

* The :variable:`CMAKE_FRAMEWORK` variable was added to initialize the
  :prop_tgt:`FRAMEWORK` property on all targets.

* The :variable:`CMAKE_VS_JUST_MY_CODE_DEBUGGING` variable and
  :prop_tgt:`VS_JUST_MY_CODE_DEBUGGING` target property were added to
  enable the Just My Code feature of the Visual Studio Debugger when
  compiling with MSVC cl 19.05 and higher.

* The :variable:`CMAKE_MSVC_RUNTIME_LIBRARY` variable and
  :prop_tgt:`MSVC_RUNTIME_LIBRARY` target property were introduced to
  select the runtime library used by compilers targeting the MSVC ABI.
  See policy :policy:`CMP0091`.

* The :variable:`CMAKE_PROJECT_INCLUDE` and
  :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables were added to allow
  injection of custom code at the sites of :command:`project` calls
  without knowing the project name a priori.

Properties
----------

* The :prop_tgt:`ADDITIONAL_CLEAN_FILES` target property and
  :prop_dir:`ADDITIONAL_CLEAN_FILES` directory property were added.
  They allow to register additional files that should be removed during
  the clean stage.

* The :prop_tgt:`PUBLIC_HEADER` and :prop_tgt:`PRIVATE_HEADER` properties
  may now be set on :ref:`Interface Libraries`. The headers specified by those
  properties can be installed using the :command:`install(TARGETS)` command by
  passing the ``PUBLIC_HEADER`` and ``PRIVATE_HEADER`` arguments respectively.

* The :prop_tgt:`VS_PACKAGE_REFERENCES` target property was added to
  tell :ref:`Visual Studio Generators` to add references to ``nuget``
  packages.

* The :prop_tgt:`VS_PROJECT_IMPORT` target property was added to allow
  managed Visual Studio project files to import external ``.props`` files.

* The :prop_tgt:`VS_NO_SOLUTION_DEPLOY` target property was added to
  tell :ref:`Visual Studio Generators` whether to deploy an artifact
  to the WinCE or Windows Phone target device.

Modules
-------

* The :module:`FindBoost` module was reworked to expose a more consistent
  user experience between its "Config" and "Module" modes and with other
  find modules in general.

  * A new imported target ``Boost::headers`` is now defined (same
    as ``Boost::boost``).

  * New output variables ``Boost_VERSION_MACRO``,
    ``Boost_VERSION_MAJOR``, ``Boost_VERSION_MINOR``,
    ``Boost_VERSION_PATCH``, and ``Boost_VERSION_COUNT``
    were added.

  * The ``QUIET`` argument passed to :command:`find_package` is no
    longer ignored in config mode.  Note that the CMake package shipped with
    Boost ``1.70.0`` ignores the ``QUIET`` argument passed to
    :command:`find_package`.  This is fixed in the next Boost release.

  * The input switch ``Boost_DETAILED_FAILURE_MSG`` was removed.

  * ``Boost_VERSION`` now reports the version in ``x.y.z``
    format in module mode.  See policy :policy:`CMP0093`.

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

* The :module:`FindEnvModules` module was added to use Lua- and TCL-based
  environment modules in :ref:`CTest Scripts <CTest Script>`.

* The :module:`FindGLEW` module now provides an interface more consistent
  with what upstream GLEW provides in its own CMake package files.

* The :module:`FindPkgConfig` now populates :prop_tgt:`INTERFACE_LINK_OPTIONS`
  property of imported targets with other (non-library) linker flags.

* The :module:`FindPostgreSQL` module learned to find debug and release
  variants separately.

* Modules :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
  gained additional lookup strategies and controls, and a new default.
  See policy :policy:`CMP0094`.

* Modules :module:`FindPython`, :module:`FindPython2` and :module:`FindPython3`
  gain a new target (respectively ``Python::Module``, ``Python2::Module``
  and ``Python3::Module``) which can be used to develop Python modules.

* Modules :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
  gain capability to control how virtual environments are handled.

* The :module:`UseSWIG` module learned to manage alternate library names
  by passing ``-interface <library_name>`` for ``python`` language or
  ``-dllimport <library_name>`` for ``CSharp`` language to the ``SWIG``
  compiler.

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

* The generator expressions :genex:`$<C_COMPILER_ID>`,
  :genex:`$<CXX_COMPILER_ID>`, :genex:`$<CUDA_COMPILER_ID>`,
  :genex:`$<Fortran_COMPILER_ID>`, :genex:`$<COMPILE_LANGUAGE>`,
  :genex:`$<COMPILE_LANG_AND_ID>`, and :genex:`$<PLATFORM_ID>` learned to
  support matching one value from a comma-separated list.

* The :genex:`$<CUDA_COMPILER_ID:...>` and :genex:`$<CUDA_COMPILER_VERSION:...>`
  generator expressions were added.

* The :genex:`$<COMPILE_LANG_AND_ID:...>` generator expression was introduced to
  allow specification of compile options for target files based on the
  :variable:`CMAKE_<LANG>_COMPILER_ID` and :prop_sf:`LANGUAGE` of
  each source file.

* A :genex:`$<FILTER:list,INCLUDE|EXCLUDE,regex>` generator expression has
  been added.

* A :genex:`$<REMOVE_DUPLICATES:list>` generator expression has been added.

* The :genex:`$<SHELL_PATH:...>` generator expression gained support for a
  list of paths.

* New ``$<TARGET_FILE*>`` :manual:`generator expressions
  <cmake-generator-expressions(7)>` were added to retrieve the prefix, base
  name, and suffix of the file names of various artifacts:

  * :genex:`$<TARGET_FILE_PREFIX:...>`
  * :genex:`$<TARGET_FILE_BASE_NAME:...>`
  * :genex:`$<TARGET_FILE_SUFFIX:...>`
  * :genex:`$<TARGET_LINKER_FILE_PREFIX:...>`
  * :genex:`$<TARGET_LINKER_FILE_BASE_NAME:...>`
  * :genex:`$<TARGET_LINKER_FILE_SUFFIX:...>`
  * :genex:`$<TARGET_PDB_FILE_BASE_NAME:...>`

* The :genex:`$<TARGET_OBJECTS:...>` generator expression is now supported
  on ``SHARED``, ``STATIC``, ``MODULE`` libraries and executables.

CTest
-----

* The :command:`ctest_submit` command learned a new option: ``BUILD_ID``.
  This can be used to store the ID assigned to this build by CDash to a
  variable.

* The :command:`ctest_update` command learned to honor a new variable:
  :variable:`CTEST_UPDATE_VERSION_OVERRIDE`. This can be used to specify
  the current version of your source tree rather than using the update
  command to discover the current version that is checked out.

CPack
-----

* The :cpack_gen:`CPack IFW Generator` gained a new
  :variable:`CPACK_IFW_PACKAGE_STYLE_SHEET` variable to customize the
  installer stylesheet.

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

* The :manual:`cmake-server(7)` mode has been deprecated and will be
  removed from a future version of CMake.  Please port clients to use
  the :manual:`cmake-file-api(7)` instead.

* The :prop_dir:`ADDITIONAL_MAKE_CLEAN_FILES` directory property is now
  deprecated.  Use the :prop_dir:`ADDITIONAL_CLEAN_FILES` directory property
  instead.

* The variable :variable:`CMAKE_AUTOMOC_RELAXED_MODE` is considered
  deprecated.  Support still exists but will be removed in future versions.

* The :command:`export(PACKAGE)` command now does nothing unless
  enabled via :variable:`CMAKE_EXPORT_PACKAGE_REGISTRY`.
  See policy :policy:`CMP0090`.

* The :generator:`Xcode` generator now requires at least Xcode 5.

* An explicit deprecation diagnostic was added for policy ``CMP0066``
  (``CMP0065`` 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
=============

* If a feature specified by :command:`target_compile_features` is available
  in the compiler's default standard level, CMake 3.14 and below incorrectly
  added unnecessary ``-std=`` flags that could lower the standard level.
  This bug has been fixed in CMake 3.15.  This behavior change may expose
  bugs in existing projects that were relying on undocumented implementation
  details.  Specifying compile features only ensures that the compiler runs
  in a mode that has those features, not that any specific standard level is
  used or explicit ``-std=`` flag passed.

* CMake learned how to compile C++14 with the IBM AIX XL compiler
  and the SunPro compiler and to compile C++20 with the AppleClang compiler.

* With MSVC-like compilers the value of :variable:`CMAKE_<LANG>_FLAGS`
  no longer contains warning flags like ``/W3`` by default.
  See policy :policy:`CMP0092`.

* IBM Clang-based XL compilers that define ``__ibmxl__`` now use the
  compiler id ``XLClang`` instead of ``XL``.  See policy :policy:`CMP0089`.

* The :command:`file(REMOVE)` and :command:`file(REMOVE_RECURSE)` commands
  were changed to ignore empty arguments with a warning instead of treating
  them as a relative path and removing the contents of the current directory.

Updates
=======

Changes made since CMake 3.15.0 include the following.

3.15.1
------

* In CMake 3.15.0 support for the GNU-like ``Clang`` compiler targeting the
  MSVC ABI implemented :variable:`CMAKE_CXX_STANDARD` values 98 and 11 using
  the corresponding ``-std=`` flags.  However, these modes do not work with
  the MSVC standard library.  Therefore CMake 3.15.1 passes C++14 standard
  flags even for C++98 and C++11.  This is consistent with MSVC itself which
  always runs in a mode aware of C++14.

* Preliminary Swift support added in 3.15.0 has been updated.

3.15.2
------

* In CMake 3.15.0 and 3.15.1 the :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG`
  variable caused the :command:`find_package` command to fail on a missing
  package even without the ``REQUIRED`` option.  This has been fixed.

3.15.3
------

* ``CrayPrgEnv`` compiler wrapper support has been updated for the 19.06
  release of the Cray Programming Environment for which the default linking
  mode on XC Cray systems is now dynamic instead of static.

3.15.4
------

* In CMake 3.15.0 through 3.15.3, the :prop_dir:`EXCLUDE_FROM_ALL`
  directory property was regressed from pre-3.14 behavior and caused
  targets within the directory to be excluded even from its own "all".
  This has been fixed.
  The bug also existed in 3.14.0 through 3.14.6 and is fixed in 3.14.7.

repo_name: lazytadpole/codenamesilverfish

license: mit


code:
CMake 3.16 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.15 include the following.

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

Languages
---------

* CMake learned to support the Objective C (``OBJC``) and Objective C++
  (``OBJCXX``) languages.  They may be enabled via the :command:`project`
  and :command:`enable_language` commands.  When ``OBJC`` or ``OBJCXX``
  is enabled, source files with the ``.m`` or ``.mm``, respectively,
  will be compiled as Objective C or C++.  Otherwise they will be treated
  as plain C++ sources as they were before.

Compilers
---------

* The ``Clang`` compiler is now supported on ``Solaris``.

Platforms
---------

* On AIX, executables using the :prop_tgt:`ENABLE_EXPORTS` target property
  now produce a linker import file with a ``.imp`` extension in addition
  to the executable file.  Plugins (created via :command:`add_library` with
  the ``MODULE`` option) that use :command:`target_link_libraries` to link
  to the executable for its symbols are now linked using the import file.
  The :command:`install(TARGETS)` command now installs the import file as
  an ``ARCHIVE`` artifact.

* On AIX, runtime linking is no longer enabled by default.  CMake provides
  the linker enough information to resolve all symbols up front.
  One may manually enable runtime linking for shared libraries and/or
  loadable modules by adding ``-Wl,-G`` to their link flags
  (e.g. in the :variable:`CMAKE_SHARED_LINKER_FLAGS` or
  :variable:`CMAKE_MODULE_LINKER_FLAGS` variable).
  One may manually enable runtime linking for executables by adding
  ``-Wl,-brtl`` to their link flags (e.g. in the
  :variable:`CMAKE_EXE_LINKER_FLAGS` variable).

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

* :manual:`cmake(1)` ``-E`` now supports ``true`` and ``false`` commands,
  which do nothing while returning exit codes of 0 and 1, respectively.

* :manual:`cmake(1)` gained a ``--trace-redirect=<file>`` command line
  option that can be used to redirect ``--trace`` output to a file instead
  of ``stderr``.

* The :manual:`cmake(1)` ``--loglevel`` command line option has been
  renamed to ``--log-level`` to make it consistent with the naming of other
  command line options.  The ``--loglevel`` option is still supported to
  preserve backward compatibility.

Commands
--------

* The :command:`add_test` command learned the option ``COMMAND_EXPAND_LISTS``
  which causes lists in the ``COMMAND`` argument to be expanded, including
  lists created by generator expressions.

* The :command:`file` command learned a new sub-command,
  ``GET_RUNTIME_DEPENDENCIES``, which allows you to recursively get the list of
  libraries linked by an executable or library. This sub-command is intended as
  a replacement for :module:`GetPrerequisites`.

* The :command:`find_file`, :command:`find_library`, :command:`find_path`,
  :command:`find_package`, and :command:`find_program` commands have learned to
  check the following variables to control the default behavior for groups of
  search locations:

  * :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` - Controls the default
    behavior of searching the :variable:`<PackageName>_ROOT` variables.

  * :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` - Controls the default
    behavior of searching the CMake-specific environment variables.

  * :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` - Controls the default
    behavior of searching the standard system environment variables.

  * :variable:`CMAKE_FIND_USE_CMAKE_PATH` - Controls the default behavior of
    searching the CMake-specific cache variables.

  * :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` - Controls the default
    behavior of searching the platform-specific CMake variables.

* The :command:`find_package` command has learned to check the
  :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` variable to control the default
  behavior of searching the CMake user package registry and to check the
  :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` variable to control
  the default behavior of searching the CMake system package registry.

* The :command:`message` command learned indentation control with the new
  :variable:`CMAKE_MESSAGE_INDENT` variable.

* The :command:`target_precompile_headers` command was added to specify
  a list of headers to precompile for faster compilation times.

Variables
---------

* The :variable:`CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS` variable has been
  introduced to optionally initialize the
  :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` target property.

* The :variable:`CMAKE_ECLIPSE_RESOURCE_ENCODING` variable was added to
  specify the resource encoding for the the :generator:`Eclipse CDT4` extra
  generator.

* The :variable:`CMAKE_UNITY_BUILD` variable was added to initialize the
  :prop_tgt:`UNITY_BUILD` target property to tell generators to batch
  include source files for faster compilation times.

Properties
----------

* The :prop_tgt:`BUILD_RPATH` and :prop_tgt:`INSTALL_RPATH` target properties
  now support :manual:`generator expressions <cmake-generator-expressions(7)>`.

* The :prop_tgt:`INSTALL_REMOVE_ENVIRONMENT_RPATH` target property was
  added to remove compiler-defined ``RPATH`` entries from a target.
  This property is initialized by the
  :variable:`CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH` variable.

* The :prop_tgt:`PRECOMPILE_HEADERS` target property was added to specify
  a list of headers to precompile for faster compilation times.
  Set it using the :command:`target_precompile_headers` command.

* The :prop_tgt:`UNITY_BUILD` target property was added to tell
  generators to batch include source files for faster compilation
  times.

* The :prop_tgt:`VS_CONFIGURATION_TYPE` target property now supports
  :manual:`generator expressions <cmake-generator-expressions(7)>`.

* The :prop_tgt:`VS_DPI_AWARE` target property was added to tell
  :ref:`Visual Studio Generators` to set the ``EnableDpiAwareness``
  property in ``.vcxproj`` files.

* The :prop_tgt:`XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING` target property was
  added to tell the :generator:`Xcode` generator to set the value of the
  ``Allow debugging when using document Versions Browser`` schema option.

Modules
-------

* The :module:`FindDoxygen` module :command:`doxygen_add_docs` command
  gained a new ``USE_STAMP_FILE`` option.  When this option present,
  the custom target created by the command will only re-run Doxygen if
  any of the source files have changed since the last successful run.

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

* The :module:`FindPackageHandleStandardArgs` module
  :command:`find_package_handle_standard_args` command gained
  a new ``REASON_FAILURE_MESSAGE`` option to specify a message
  giving the reason for the failure.

* The :module:`FindPkgConfig` module :command:`pkg_search_module` macro
  now defines a ``<prefix>_MODULE_NAME`` result variable containing the
  first matching module name.

* The :module:`FindPython3` and :module:`FindPython` modules gained
  options to control which ``ABIs`` will be searched.

* The :module:`FindPython3`, :module:`FindPython2`, and :module:`FindPython`
  modules now support direct specification of artifacts via cache entries.

Autogen
-------

* When using :prop_tgt:`AUTOMOC`, the new :variable:`CMAKE_AUTOMOC_PATH_PREFIX`
  variable or :prop_tgt:`AUTOMOC_PATH_PREFIX` target property may be enabled
  to generate the ``-p`` path prefix
  option for ``moc``.  This ensures that ``moc`` output files are identical
  on different build setups (given, that the headers compiled by ``moc`` are
  in an :command:`include directory <target_include_directories>`).
  Also it ensures that ``moc`` output files will compile correctly when the
  source and/or build directory is a symbolic link.

CTest
-----

* :manual:`ctest(1)` now has the ability to schedule tests based on resource
  requirements for each test. See :ref:`ctest-resource-allocation` for
  details.

* A new test property, :prop_test:`SKIP_REGULAR_EXPRESSION`, has been added.
  This property is similar to :prop_test:`FAIL_REGULAR_EXPRESSION` and
  :prop_test:`PASS_REGULAR_EXPRESSION`, but with the same meaning as
  :prop_test:`SKIP_RETURN_CODE`. This is useful, for example, in cases where
  the user has no control over the return code of the test. For example, in
  Catch2, the return value is the number of assertion failed, therefore it is
  impossible to use it for :prop_test:`SKIP_RETURN_CODE`.

CPack
-----

* :manual:`cpack(1)` learned support for multiple configurations for ``-C``
  option.

* The :cpack_gen:`CPack DEB Generator` is now able to format generic text
  (usually used as the description for multiple CPack generators) according
  to the `Debian Policy Manual`_.  See the
  :variable:`CPACK_PACKAGE_DESCRIPTION_FILE` and
  :variable:`CPACK_DEBIAN_<COMPONENT>_DESCRIPTION` variables.

* The :cpack_gen:`CPack Archive Generator` learned to generate ``.tar.zst``
  packages with Zstandard compression.

.. _`Debian Policy Manual`: https://www.debian.org/doc/debian-policy/ch-controlfields.html#description

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

* An explicit deprecation diagnostic was added for policy ``CMP0067``
  (``CMP0066`` 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_FIND_PACKAGE_NO_PACKAGE_REGISTRY` variable has been
  deprecated.  Use the :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` variable
  instead.

* The :module:`GetPrerequisites` module has been deprecated, as it has been
  superseded by :command:`file(GET_RUNTIME_DEPENDENCIES)`.

* The ``CPACK_INSTALL_SCRIPT`` variable has been deprecated in favor of the
  new, more accurately named :variable:`CPACK_INSTALL_SCRIPTS` variable.

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

* The :manual:`cmake(1)` ``-C <initial-cache>`` option now evaluates the
  initial cache script with :variable:`CMAKE_SOURCE_DIR` and
  :variable:`CMAKE_BINARY_DIR` set to the top-level source and build trees.

* The :manual:`cmake(1)` ``-E remove_directory`` command-line tool,
  when given the path to a symlink to a directory, now removes just
  the symlink.  It no longer removes content of the linked directory.

* The :manual:`ctest(1)`  ``--build-makeprogram`` command-line option now
  specifies the make program used when configuring a project with the
  :generator:`Ninja` generator or the :ref:`Makefile Generators`.

* The :module:`ExternalProject` module :command:`ExternalProject_Add` command
  has been updated so that ``GIT_SUBMODULES ""`` initializes no submodules.
  See policy :policy:`CMP0097`.

* The :module:`FindGTest` module has been updated to recognize
  MSVC build trees generated by GTest 1.8.1.

* The :command:`project` command no longer strips leading zeros in version
  components.  See policy :policy:`CMP0096`.

* The Qt Compressed Help file is now named ``CMake.qch``, which no longer
  contains the release version in the file name.  When CMake is upgraded
  in-place, the name and location of this file will remain constant.
  Tools such as IDEs, help viewers, etc. should now be able to refer to this
  file at a fixed location that remains valid across CMake upgrades.

* ``RPATH`` entries are properly escaped in the generated CMake scripts
  used for installation.  See policy :policy:`CMP0095`.

* When using :variable:`CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS` on Windows the
  auto-generated exports are now updated only when the object files
  providing the symbols are updated.

Updates
=======

Changes made since CMake 3.16.0 include the following.

3.16.2
------

* CMake 3.16.0 and 3.16.1 processed ``.hh`` files with :prop_tgt:`AUTOMOC`.
  This was a behavior change from CMake 3.15 and below that can break
  existing projects, so it has been reverted as of 3.16.2.

3.16.5
------

* The :module:`FindPython`, :module:`FindPython2`, and :module:`FindPython3`
  modules no longer create cache entries for ``Python{,2,3}_LIBRARY_RELEASE``
  and ``Python{,2,3}_LIBRARY_DEBUG``.  Those values are always computed from
  other results and so should not be cached.  The entries were created by
  CMake 3.16.0 through 3.16.4 but were always ``FORCE``-set and could not
  be meaningfully edited by users.

  Additionally, the modules no longer expose their internal ``_Python*``
  cache entries publicly.  CMake 3.16.0 through 3.16.4 accidentally
  made them visible as advanced cache entries.

3.16.7
------

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

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


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


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.