code:
CMake 3.10 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.9 include the following.

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

Platforms
---------

* The `flang`_ Fortran compiler is now supported, with compiler id ``Flang``.

* A new minimal platform file for ``Midipix`` was added.

* Support for the MSVC ARM64 architecture was added.
  Visual Studio 2017 Update 4 and above offer an ARM64 toolchain.

* Support for the IAR ARM Compiler was improved.

.. _`flang`: https://github.com/flang-compiler/flang

Generators
----------

* The :ref:`Makefile Generators` and the :generator:`Ninja` generator learned
  to add compiler launcher tools like ccache along with the compiler for the
  ``CUDA`` language (``C`` and ``CXX`` were supported previously).  See the
  :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable and
  :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property for details.

* The :generator:`CodeBlocks` extra generator learned to optionally exclude
  files from outside the project root directory from the generated project.
  See the :variable:`CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES` variable.

Commands
--------

* The :command:`cmake_host_system_information` command learned more keys
  to get information about the processor capabilities and the host OS
  version.

* The :command:`configure_file` command learned to support indented
  ``#  cmakedefine`` and ``#  cmakedefine01``. Spaces and/or tabs between
  the ``#`` character and the ``cmakedefine``/``cmakedefine01`` words
  are now understood and preserved in the output.

* The :command:`execute_process` command gained a ``RESULTS_VARIABLE``
  option to collect a list of results from all children in a pipeline
  of processes when multiple ``COMMAND`` arguments are given.

* The :command:`include_guard` command was introduced to allow guarding
  CMake scripts from being included more than once. The command supports
  ``DIRECTORY`` and ``GLOBAL`` options to adjust the corresponding include guard
  scope. If no options given, include guard is similar to basic variable-based
  check.

* The :command:`string` command learned a new ``PREPEND`` subcommand.

* The :command:`string(TIMESTAMP)` command now supports ``%A``
  for full weekday name and ``%B`` for full month name.

Variables
---------

* A :variable:`CMAKE_DIRECTORY_LABELS` variable was added to specify
  labels for all tests in a directory.

Properties
----------

* A :prop_tgt:`<LANG>_CPPCHECK` target property and supporting
  :variable:`CMAKE_<LANG>_CPPCHECK` variable were introduced to tell
  the :ref:`Makefile Generators` and the :generator:`Ninja` generator to
  run ``cppcheck`` with the compiler for ``C`` and ``CXX`` languages.

* A :prop_dir:`LABELS` directory property was added to specify labels
  for all targets and tests in a directory.

* A :prop_dir:`TEST_INCLUDE_FILES` directory property was added to
  list any number of files to be included when running tests with
  :manual:`ctest(1)`.  This generalizes the :prop_dir:`TEST_INCLUDE_FILE`
  property.

* The :prop_tgt:`VS_DOTNET_REFERENCEPROP_<refname>_TAG_<tagname>`
  target property was added to support custom XML tags for reference
  assemblies in C# targets.

* Source file properties :prop_sf:`VS_SHADER_OUTPUT_HEADER_FILE` and
  :prop_sf:`VS_SHADER_VARIABLE_NAME` have been added to specify more
  details of ``.hlsl`` sources with :ref:`Visual Studio Generators`.

Modules
-------

* The :module:`FindCurses` module gained a ``CURSES_NEED_WIDE`` option
  to request the wide-character variant.

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

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

* :module:`FindMPI` gained a number of new features, including:

  * Language-specific components have been added to the module.
  * Many more MPI environments are now supported.
  * The environmental support for Fortran has been improved.
  * A user now has fine-grained control over the MPI selection process,
    including passing custom parameters to the MPI compiler.
  * The version of the implemented MPI standard is now being exposed.
  * MPI-2 C++ bindings can now be detected and also suppressed if so desired.
  * The available Fortran bindings are now being detected and verified.
  * Various MPI-3 information can be requested, including the library version
    and Fortran capabilities of the individual bindings.
  * Statically linked MPI implementations are supported.

* A :module:`FindOpenACC` module was added to detect compiler support
  for OpenACC.  Currently only supports PGI, GNU and Cray compilers.

* The :module:`FindOpenGL` module gained support for GLVND on Linux.

* The :module:`FindOpenMP` module gained support for
  language-specific components.

* A :module:`FindPatch` module was added to find the ``patch``
  command-line executable.

* The :module:`FindProtobuf` module :command:`protobuf_generate_cpp` command
  gained a ``DESCRIPTORS`` option to generate descriptor files.

* The :module:`GoogleTest` module gained a new command
  :command:`gtest_discover_tests` implementing dynamic (build-time) test
  discovery.  Unlike the source parsing approach, dynamic discovery executes
  the test (in 'list available tests' mode) at build time to discover tests.
  This is robust against unusual ways of labeling tests, provides much better
  support for advanced features such as parameterized tests, and does not
  require re-running CMake to discover added or removed tests within a test
  executable.  Note that a breaking change was made in CMake 3.10.3 to address
  an ambiguity of the ``TIMEOUT`` keyword (see :ref:`Release Notes 3.10.3`).

* The :module:`InstallRequiredSystemLibraries` module gained support
  for installing Intel compiler runtimes.

Autogen
-------

* When using :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` with a
  multi configuration generator (e.g. :generator:`Xcode`),
  included ``*.moc``,  ``moc_*.cpp`` and ``ui_*.h`` files are generated in
  ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>`` instead of
  ``<AUTOGEN_BUILD_DIR>/include``.

* When using :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC`,
  source files that are :prop_sf:`GENERATED` will be processed as well.
  They were ignored by :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`
  in earlier releases.
  See policy :policy:`CMP0071`.

* When using :prop_tgt:`AUTOMOC`, CMake searches for the strings ``Q_OBJECT``,
  ``Q_GADGET`` or ``Q_NAMESPACE`` in a source file to determine if it needs
  to be ``moc`` processed.  The new :variable:`CMAKE_AUTOMOC_MACRO_NAMES`
  variable and :prop_tgt:`AUTOMOC_MACRO_NAMES` target property may be set
  to register additional strings (macro names) to search for.

* When using :prop_tgt:`AUTOMOC`, the new
  :variable:`CMAKE_AUTOMOC_COMPILER_PREDEFINES` variable and
  :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES` target property specify whether
  to enable or disable the generation of the compiler pre definitions file
  ``moc_predefs.h``.

CTest
-----

* A :variable:`CTEST_LABELS_FOR_SUBPROJECTS` CTest module variable and CTest
  script variable were added to specify a list of labels that should be
  treated as subprojects by CDash. To use this value in both the CTest module
  and the ctest command line :ref:`Dashboard Client` mode (e.g. ``ctest -S``)
  set it in the ``CTestConfig.cmake`` config file.

CPack
-----

* A :cpack_gen:`CPack FreeBSD Generator` was added for FreeBSD ``pkg(8)``.

* The :cpack_gen:`CPack DEB Generator` was enabled on Windows.  While not
  fully featured (due to the lack of external UNIX tools) this will allow
  building basic cross-platform Debian packages.

* The :cpack_gen:`CPack DEB Generator` learned to set package release
  version in ``Version`` info property.
  See the :variable:`CPACK_DEBIAN_PACKAGE_RELEASE` variable.

* The :cpack_gen:`CPack DEB Generator` learned more strict package
  version checking that complies with Debian rules.

* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and
  :command:`cpack_ifw_configure_component_group` commands gained a new
  ``REPLACES`` and ``CHECKABLE`` options.

* The :cpack_gen:`CPack IFW Generator` gained new
  :variable:`CPACK_IFW_PACKAGE_FILE_EXTENSION` variable to customize
  target binary format.

* The :cpack_gen:`CPack IFW Generator` gained new
  :variable:`CPACK_IFW_REPOSITORIES_DIRECTORIES` variable to specify
  additional repositories dirs that will be used to resolve and
  repack dependent components. This feature is only available when
  using QtIFW 3.1 or later.

* The :cpack_gen:`CPack RPM Generator` and :cpack_gen:`CPack DEB Generator`
  learned to set the package epoch version.
  See :variable:`CPACK_RPM_PACKAGE_EPOCH` and
  :variable:`CPACK_DEBIAN_PACKAGE_EPOCH` variables.

Other
-----

* The :manual:`cmake(1)` ``-E`` mode gained support for ``sha1sum``,
  ``sha224sum``, ``sha256sum``, ``sha384sum``, and ``sha512sum``.

* The graphviz output now distinguishes among the different dependency types
  ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` and represents them in the output
  graph as solid, dashed and dotted edges.

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

* Support for building CMake itself with C++98 compilers was dropped.
  CMake is now implemented using C++11.

* Support for building CMake on HP-UX has been dropped pending better
  support for C++11 and a port of libuv.  See `CMake Issue 17137`_.
  Use CMake 3.9 or lower instead for HP-UX support.

.. _`CMake Issue 17137`: https://gitlab.kitware.com/cmake/cmake/-/issues/17137

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

* On FreeBSD the C++ compiler named ``c++`` is now the preferred default.

* The :command:`file(GENERATE)` command now interprets relative paths
  given to its ``OUTPUT`` and ``INPUT`` arguments with respect to the
  caller's current binary and source directories, respectively.
  See policy :policy:`CMP0070`.

* The :command:`get_filename_component` ``PROGRAM`` mode semantics
  have been revised to not tolerate unquoted spaces in the path
  to the program while also accepting arguments.  While technically
  incompatible with the old behavior, it is expected that behavior
  under typical use cases with properly-quoted command-lines has
  not changed.

Updates
=======

Changes made since CMake 3.10.0 include the following.

3.10.1
------

* The :manual:`cmake-server(7)` ``codemodel`` response cross-references
  field added by 3.10.0 has been dropped due to excessive memory usage.
  Another approach will be needed to provide backtrace information.

.. _`Release Notes 3.10.3`:

3.10.3
------

* CMake 3.10.1 added a ``TIMEOUT`` option to :command:`gtest_discover_tests`
  from the :module:`GoogleTest` module.  That keyword clashed with the
  ``TIMEOUT`` test property, which is one of the common properties that
  would be set with the command's ``PROPERTIES`` keyword, usually leading
  to legal but unintended behavior.  The keyword was changed to
  ``DISCOVERY_TIMEOUT`` in CMake 3.10.3 to address this problem.  The
  ambiguous behavior of the :command:`gtest_discover_tests` command's
  ``TIMEOUT`` keyword in 3.10.1 and 3.10.2 has not been preserved.


code:
CMake 3.11 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.10 include the following.

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

Platforms
---------

* TI C/C++ compilers are now supported by the :generator:`Ninja` generator.

Generators
----------

* The :generator:`CodeBlocks` extra generator learned to check a
  :variable:`CMAKE_CODEBLOCKS_COMPILER_ID` variable for a custom
  compiler identification value to place in the project file.

* The :ref:`Makefile Generators` and the :generator:`Ninja` generator learned
  to add compiler launcher tools along with the compiler for the ``Fortran``
  language (``C``, ``CXX``, and ``CUDA`` were supported previously).
  See the :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable and
  :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property for details.

* :ref:`Visual Studio Generators` learned to support the ``COMPILE_LANGUAGE``
  :manual:`generator expression <cmake-generator-expressions(7)>` in
  target-wide :prop_tgt:`COMPILE_DEFINITIONS`,
  :prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_OPTIONS`, and
  :command:`file(GENERATE)`.  See generator expression documentation
  for caveats.

* The :generator:`Xcode` generator learned to support the ``COMPILE_LANGUAGE``
  :manual:`generator expression <cmake-generator-expressions(7)>` in
  target-wide :prop_tgt:`COMPILE_DEFINITIONS` and
  :prop_tgt:`INCLUDE_DIRECTORIES`.  It previously supported only
  :prop_tgt:`COMPILE_OPTIONS` and :command:`file(GENERATE)`.
  See generator expression documentation for caveats.

Commands
--------

* :command:`add_library` and :command:`add_executable` commands can now be
  called without any sources and will not complain as long as sources are
  added later via the :command:`target_sources` command.

* The :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands
  gained ``NETRC`` and ``NETRC_FILE`` options to specify use of a
  ``.netrc`` file.

* The :command:`target_compile_definitions` command learned to set the
  :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` property on
  :ref:`Imported Targets`.

* The :command:`target_compile_features` command learned to set the
  :prop_tgt:`INTERFACE_COMPILE_FEATURES` property on :ref:`Imported Targets`.

* The :command:`target_compile_options` command learned to set the
  :prop_tgt:`INTERFACE_COMPILE_OPTIONS` property on :ref:`Imported Targets`.

* The :command:`target_include_directories` command learned to set the
  :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` property on
  :ref:`Imported Targets`.

* The :command:`target_sources` command learned to set the
  :prop_tgt:`INTERFACE_SOURCES` property on :ref:`Imported Targets`.

* The :command:`target_link_libraries` command learned to set the
  :prop_tgt:`INTERFACE_LINK_LIBRARIES` property on :ref:`Imported Targets`.

Variables
---------

* A :variable:`CMAKE_GENERATOR_INSTANCE` variable was introduced
  to hold the selected instance of the generator's corresponding
  native tools if multiple are available.  This is used by the
  :generator:`Visual Studio 15 2017` generator to hold the
  selected instance of Visual Studio persistently.

* A :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable was added
  to enable setting of default permissions for directories created implicitly
  during installation of files by :command:`install` and
  :command:`file(INSTALL)`, e.g. during ``make install``.

* A :variable:`CMAKE_JOB_POOLS` variable was added specify a value to use for
  the :prop_gbl:`JOB_POOLS` property. This enables control over build
  parallelism with command line configuration parameters when using the Ninja
  generator.

* The :variable:`CMAKE_NETRC` and :variable:`CMAKE_NETRC_FILE` variables
  were added to specify use of a ``.netrc`` file by the
  :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands and
  the :module:`ExternalProject` module.

* A :variable:`CMAKE_CUDA_SEPARABLE_COMPILATION` variable was added to
  initialize the :prop_tgt:`CUDA_SEPARABLE_COMPILATION` target property
  on targets when they are created.

Properties
----------

* The :prop_sf:`COMPILE_DEFINITIONS` source file property learned to support
  :manual:`generator expressions <cmake-generator-expressions(7)>`.

* A :prop_sf:`COMPILE_OPTIONS` source file property was added to manage list
  of options to pass to the compiler.

* An :prop_tgt:`IMPORTED_GLOBAL` target property was added to indicate
  whether an :ref:`IMPORTED target <Imported Targets>` is globally visible.
  It is automatically set to a true value for targets created with the
  ``GLOBAL`` option to :command:`add_library` or :command:`add_executable`.
  Additionally, project code may now *promote* a local imported target
  to be globally visible by setting this property to ``TRUE``.

* An :prop_sf:`INCLUDE_DIRECTORIES` source file property was added to specify
  list of preprocessor include file search directories.

* Source file properties :prop_sf:`VS_SHADER_DISABLE_OPTIMIZATIONS` and
  :prop_sf:`VS_SHADER_ENABLE_DEBUG` have been added to specify more
  details of ``.hlsl`` sources with :ref:`Visual Studio Generators`.

Modules
-------

* The :module:`CheckIncludeFiles` module :command:`CHECK_INCLUDE_FILES`
  command gained a ``LANGUAGE`` option to specify whether to check using the
  ``C`` or ``CXX`` compiler.

* The :module:`CMakePackageConfigHelpers` module
  :command:`write_basic_package_version_file` command learned a new
  ``SameMinorVersion`` mode for the ``COMPATIBILITY`` argument.

* The :module:`ExternalProject` module learned to substitute ``<DOWNLOAD_DIR>``
  in comments, commands, working directory and byproducts.

* The :module:`ExternalProject` module gained ``NETRC`` and ``NETRC_FILE``
  options to specify use of a ``.netrc`` file.

* A new :module:`FetchContent` module was added which supports populating
  content at configure time using any of the download/update methods
  supported by :command:`ExternalProject_Add`.  This allows the content
  to be used immediately during the configure stage, such as with
  :command:`add_subdirectory`, etc.  Hierarchical project structures are
  well supported, allowing parent projects to override the content details
  of child projects and ensuring content is not populated multiple times
  throughout the whole project tree.

* The :module:`FindBLAS` and :module:`FindLAPACK` modules learned to support
  `FLAME`_ ``blis`` and ``libflame``.

* The :module:`FindDoxygen` module :command:`doxygen_add_docs` function
  now supports a new ``DOXYGEN_VERBATIM_VARS`` list variable.  Any
  ``DOXYGEN_...`` variable contained in that list will bypass the automatic
  quoting logic, leaving its contents untouched when transferring them to the
  output ``Doxyfile``.

* A :module:`FindIconv` module was added to locate iconv support.

* The :module:`GenerateExportHeader` module ``GENERATE_EXPORT_HEADER`` command
  gained an ``INCLUDE_GUARD_NAME`` option to change the name of the include
  guard symbol written to the generated export header.
  Additionally, it now adds a comment after the closing ``#endif`` on the
  generated export header's include guard.

* The :module:`UseJava` module ``add_jar`` command gained a
  ``GENERATE_NATIVE_HEADERS`` option to generate native header files
  using ``javac -h`` for ``javac`` 1.8 or above.  This supersedes
  ``create_javah``, which no longer works with JDK 1.10 and above due
  to removal of the ``javah`` tool by `JEP 313`_.

.. _`FLAME`: https://github.com/flame
.. _`JEP 313`: https://openjdk.org/jeps/313

Autogen
-------

* When using :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC`, CMake now starts
  multiple parallel ``moc`` or ``uic`` processes to reduce the build time.
  A new :variable:`CMAKE_AUTOGEN_PARALLEL` variable and
  :prop_tgt:`AUTOGEN_PARALLEL` target property may be set to specify the
  number of parallel ``moc`` or ``uic`` processes to start.  The default
  is derived from the number of CPUs on the host.

CTest
-----

* The :command:`ctest_start` command no longer sets
  :variable:`CTEST_RUN_CURRENT_SCRIPT` due to issues with scoping if it is
  called from inside a function. Instead, it sets an internal variable in
  CTest. However, setting :variable:`CTEST_RUN_CURRENT_SCRIPT` to 0 at the
  global scope still prevents the script from being re-run at the end.

CPack
-----

* :manual:`cpack(1)` gained ``--trace`` and ``--trace-expand`` options.

* The :cpack_gen:`CPack IFW Generator` gained new
  :variable:`CPACK_IFW_PACKAGE_REMOVE_TARGET_DIR` variable to control
  if the target directory should not be deleted when uninstalling.

* The :cpack_gen:`CPack RPM Generator` learned to enable enforcing of execute
  privileges on programs and shared libraries.
  See :variable:`CPACK_RPM_INSTALL_WITH_EXEC` variable.

* A :variable:`CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable was added
  which serves the same purpose during packaging (e.g. ``make package``) as the
  :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable serves during
  installation (e.g. ``make install``).

Other
-----

* :ref:`Alias Targets` may now alias :ref:`Imported Targets` that are
  created with the ``GLOBAL`` option to :command:`add_library`.

* :ref:`Interface Libraries` may now have custom properties set on them if
  they start with either an underscore (``_``) or a lowercase ASCII character.
  The original intention was to only allow properties which made sense for
  ``INTERFACE`` libraries, but it also blocked usage of custom properties.

* The :manual:`cmake(1)` ``--open <dir>`` command-line option was added
  to open generated IDE projects like Visual Studio solutions or Xcode
  projects.

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

* An explicit deprecation diagnostic was added for policies ``CMP0037``
  through ``CMP0054`` (``CMP0036`` 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 ``KDevelop3`` generator has been removed.

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

* Policy :policy:`CMP0037` no longer reserves target names associated
  with optional features, such as ``test`` and ``package``, unless
  the corresponding feature is enabled.

* The :module:`FindOpenGL` module now prefers GLVND libraries if available.
  See policy :policy:`CMP0072`.

* The minimum deployment target set in the
  :variable:`CMAKE_OSX_DEPLOYMENT_TARGET` variable used to be only
  applied for macOS regardless of the selected SDK.  It is now properly
  set for the target platform selected by :variable:`CMAKE_OSX_SYSROOT`.
  For example, if the sysroot variable specifies an iOS SDK then the
  value in ``CMAKE_OSX_DEPLOYMENT_TARGET`` is interpreted as minimum
  iOS version.

* The :generator:`Xcode` generator behavior of generating one project
  file per :command:`project()` command may now be controlled with the
  :variable:`CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY` variable.
  This could be useful to speed up the CMake generation step for
  large projects and to work-around a bug in the ``ZERO_CHECK`` logic.

* Since the ``CMakeCache.txt`` format does not support newlines in values,
  values containing newlines are now truncated before writing to the file.
  In addition, a warning comment is written to the cache file, and a warning
  message is displayed to the user on the console.

Updates
=======

Changes made since CMake 3.11.0 include the following.

3.11.1
------

* The :module:`CheckIncludeFile` module ``check_include_file`` macro,
  :module:`CheckIncludeFileCXX` module ``check_include_file_cxx`` macro,
  and :module:`CheckIncludeFiles` module ``check_include_files`` macro
  were taught to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable in
  CMake 3.11.0.  This has been reverted due to changing behavior of
  checks for existing projects.  It may be restored in the future
  with a policy for compatibility.

3.11.2
------

* Calling :command:`add_library` to create an alias of an imported
  target that is not globally visible now causes an error again as
  it did prior to 3.11.0.  This diagnostic was accidentally dropped
  from CMake 3.11.0 and 3.11.1 by the change to allow globally visible
  imported targets to be aliased.

* The :module:`FindQt4` module ``qt4_wrap_cpp``, ``qt4_wrap_ui`` and
  ``qt4_add_resources`` macros now set :prop_sf:`SKIP_AUTOMOC` and
  :prop_sf:`SKIP_AUTOUIC` on their generated files.  These files never
  need to be processed by moc or uic, and we must say so explicitly to
  account for policy :policy:`CMP0071`.

3.11.3
------

* CMake 3.11.0 introduced support for resolving symbolic links on
  Windows in code paths that typically do so on UNIX.  This has been
  reverted due to breakage on ``subst`` drives.

repo_name: lazytadpole/codenamesilverfish

license: mit


code:
CMake 3.12 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.11 include the following.

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

Generators
----------

* The :ref:`Visual Studio Generators` for VS 2017 learned to support a
  ``version=14.##`` option in the :variable:`CMAKE_GENERATOR_TOOLSET`
  value (e.g. via the :manual:`cmake(1)` ``-T`` option) to specify a
  toolset version number.

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

* The :manual:`cmake(1)` :ref:`Build Tool Mode` (``cmake --build``) gained
  ``--parallel [<jobs>]`` and ``-j [<jobs>]`` options to specify a parallel
  build level.  They map to corresponding options of the native build tool.

Commands
--------

* The :command:`add_compile_definitions` command was added to set preprocessor
  definitions at directory level.  This supersedes :command:`add_definitions`.

* The :command:`cmake_minimum_required` and :command:`cmake_policy(VERSION)`
  commands now accept a version range using the form ``<min>[...<max>]``.
  The ``<min>`` version is required but policies are set based on the
  older of the running CMake version and the version specified by
  ``<max>``.  This allows projects to specify a range of versions
  for which they have been updated and avoid explicit policy settings.

* The :command:`file(GLOB)` and :command:`file(GLOB_RECURSE)` commands
  learned a new flag ``CONFIGURE_DEPENDS`` which enables expression of
  build system dependency on globbed directory's contents.

* The :command:`file(TOUCH)` and :command:`file(TOUCH_NOCREATE)` commands
  were added to expose ``TOUCH`` functionality without having to use
  CMake's command-line tool mode with :command:`execute_process`.

* The :command:`find_package` command now searches prefixes specified by
  the :variable:`<PackageName>_ROOT` CMake variable and the
  :envvar:`<PackageName>_ROOT` environment variable.  Package roots are
  maintained as a stack so nested calls to all ``find_*`` commands inside
  find modules also search the roots as prefixes.
  See policy :policy:`CMP0074`.

* The :command:`install` command learned an optional ``NAMELINK_COMPONENT``
  parameter, which allows you to change the component for a shared library's
  namelink. If none is specified, the value of ``COMPONENT`` is used by
  default.

* The :command:`list` command learned a ``JOIN`` sub-command
  to concatenate list's elements separated by a glue string.

* The :command:`list` command learned a ``SUBLIST`` sub-command
  to get a sublist of the list.

* The :command:`list` command learned a ``TRANSFORM`` sub-command
  to apply various string transformation to list's elements.

* The :command:`project` command learned an optional ``HOMEPAGE_URL``
  parameter which has the effect of setting variables like
  :variable:`PROJECT_HOMEPAGE_URL`, :variable:`<PROJECT-NAME>_HOMEPAGE_URL`
  and :variable:`CMAKE_PROJECT_HOMEPAGE_URL`.

* The :command:`string` command learned a ``JOIN`` sub-command
  to concatenate input strings separated by a glue string.

* :command:`target_compile_options` and :command:`add_compile_options`
  commands gained a ``SHELL:`` prefix to specify a group of related
  options using shell-like quoting.

* The :command:`target_link_libraries` command now supports
  :ref:`Object Libraries`.  Linking to an object library uses its object
  files in direct dependents and also propagates usage requirements.

Variables
---------

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

* The :variable:`CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION` variable
  was defined to initialize all
  :prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` target properties.

* ``CMAKE_PROJECT_VERSION*`` variables have been introduced:

  - :variable:`CMAKE_PROJECT_VERSION`
  - :variable:`CMAKE_PROJECT_VERSION_MAJOR`
  - :variable:`CMAKE_PROJECT_VERSION_MINOR`
  - :variable:`CMAKE_PROJECT_VERSION_PATCH`
  - :variable:`CMAKE_PROJECT_VERSION_TWEAK`

* The :variable:`CMAKE_SUPPRESS_REGENERATION` variable was extended to
  support the :generator:`Ninja` and :ref:`Makefile Generators`.
  It is also now documented.

* ``CMAKE_VS_SDK_*_DIRECTORIES`` variables were defined to tell
  :ref:`Visual Studio Generators` for VS 2010 and above how to populate
  fields in ``.vcxproj`` files that specify SDK directories.  The
  variables are:

  - :variable:`CMAKE_VS_SDK_EXCLUDE_DIRECTORIES`
  - :variable:`CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES`
  - :variable:`CMAKE_VS_SDK_INCLUDE_DIRECTORIES`
  - :variable:`CMAKE_VS_SDK_LIBRARY_DIRECTORIES`
  - :variable:`CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES`
  - :variable:`CMAKE_VS_SDK_REFERENCE_DIRECTORIES`
  - :variable:`CMAKE_VS_SDK_SOURCE_DIRECTORIES`

* A :variable:`MSVC_TOOLSET_VERSION` variable was added to provide the
  MSVC toolset version associated with the current MSVC compiler version
  in :variable:`MSVC_VERSION`.

Properties
----------

* The :prop_tgt:`COMMON_LANGUAGE_RUNTIME` target property was introduced
  to configure the use of managed C++ for :ref:`Visual Studio Generators`
  for VS 2010 and above.
  A corresponding :prop_tgt:`IMPORTED_COMMON_LANGUAGE_RUNTIME` target
  property was added to support ``C++/CLI`` for imported targets.

* The :prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` target property
  was introduced as replacement for
  :prop_tgt:`VS_DOTNET_TARGET_FRAMEWORK_VERSION`, which is considered
  deprecated now.

* An :prop_tgt:`EXPORT_PROPERTIES` target property was added to specify a
  custom list of target properties to include in targets exported by the
  :command:`install(EXPORT)` and :command:`export` commands.

* The :prop_tgt:`PDB_OUTPUT_DIRECTORY` property learned to support
  :manual:`generator expressions <cmake-generator-expressions(7)>`.

* A :prop_dir:`TESTS` directory property was added to hold the list of
  tests defined by the :command:`add_test` command.

* A :prop_tgt:`VS_DEBUGGER_COMMAND` target property was created to set the
  debugging command line with :ref:`Visual Studio Generators` for VS 2010
  and above.

* HLSL source file properties :prop_sf:`VS_SHADER_DISABLE_OPTIMIZATIONS`
  and :prop_sf:`VS_SHADER_ENABLE_DEBUG` gained support for generator
  expressions.

* HLSL source file property :prop_sf:`VS_SHADER_OBJECT_FILE_NAME` has been
  added to the :ref:`Visual Studio Generators` for VS 2010 and above.
  The property specifies the file name of the compiled shader object.

Modules
-------

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

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

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

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

* The :module:`FindMatlab` module now supports the Matlab Runtime
  Compiler (MCR) for compiling and linking matlab extensions.

* A :module:`FindODBC` module was added to find an Open Database Connectivity
  (ODBC) library.

* The :module:`FindPkgConfig` module has learned to export the found
  libraries with full path for direct consumption with the
  :command:`target_link_libraries` command.

* New :module:`FindPython3` and :module:`FindPython2` modules, as well as
  a new :module:`FindPython` module, have been added to provide a new way
  to locate python environments.

* The :module:`UseSWIG` module gained a whole refresh and is now more
  consistent with standard CMake commands to generate libraries and is
  fully configurable through properties.

* The :module:`UseSWIG` module learned to manage multiple behaviors through
  ``UseSWIG_MODULE_VERSION`` variable to ensure legacy support as well as more
  robust handling of ``SWIG`` advanced features (like ``%template``).

* The :module:`UseSWIG` module learned to support CSHARP variant
  wrapper files.

* The :module:`WriteCompilerDetectionHeader` module gained a ``BARE_FEATURES``
  option to add a compatibility define for the exact keyword of a new language
  feature.

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

* A new ``$<GENEX_EVAL:...>`` and ``$<TARGET_GENEX_EVAL:target,...>``
  :manual:`generator expression <cmake-generator-expressions(7)>`
  has been added to enable consumption of generator expressions whose
  evaluation results itself in generator expressions.

* A new ``$<IN_LIST:...>``
  :manual:`generator expression <cmake-generator-expressions(7)>`
  has been added.

* A new ``$<TARGET_EXISTS:...>``
  :manual:`generator expression <cmake-generator-expressions(7)>`
  has been added.

* A new ``$<TARGET_NAME_IF_EXISTS:...>``
  :manual:`generator expression <cmake-generator-expressions(7)>`
  has been added.

CTest
-----

* The :command:`ctest_start` command has been reworked so that you can simply
  call ``ctest_start(APPEND)`` and it will read all the needed information from
  the TAG file. The argument parsing has also been relaxed so that the order of
  the arguments is less significant.

* A :prop_test:`PROCESSOR_AFFINITY` test property was added to request
  that CTest run a test with CPU affinity for a set of processors
  disjoint from other concurrently running tests with the property set.

CPack
-----

* The :module:`CPack` module now uses variables
  :variable:`CMAKE_PROJECT_VERSION_MAJOR`,
  :variable:`CMAKE_PROJECT_VERSION_MINOR` and
  :variable:`CMAKE_PROJECT_VERSION_PATCH`
  to initialize corresponding CPack variables.

* A :cpack_gen:`CPack NuGet Generator` was was added with basic
  support for `NuGet`_.

.. _NuGet: https://learn.microsoft.com/en-us/nuget/what-is-nuget

Other
-----

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
  is now aware of C++ 20.  No specific features are yet enumerated besides
  the ``cxx_std_20`` meta-feature.

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
  is now aware of the availability of C features in MSVC since VS 2010.

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
  is now aware of C language standards supported by Texas Instruments C
  compilers.

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

* The :generator:`Visual Studio 8 2005` generator has been removed.

* CMake no longer produces ``<tgt>_LIB_DEPENDS`` cache entries
  for library targets.  See policy :policy:`CMP0073`.

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

* Include flags for directories marked as ``SYSTEM`` are now moved after
  non-system directories.  The ``-isystem`` flag does this automatically,
  so moving them explicitly to the end makes the behavior consistent on
  compilers that do not have any ``-isystem`` flag.

* Fortran dependency scanning now supports dependencies implied by
  `Fortran Submodules`_.

* The existence and functionality of the file
  ``${CMAKE_BINARY_DIR}/cmake_install.cmake`` has now been documented in the
  :command:`install` documentation so that external packaging software can take
  advantage of CPack-style component installs.

* The :module:`CheckIncludeFile` module ``check_include_file`` macro
  learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable.
  See policy :policy:`CMP0075`.

* The :module:`CheckIncludeFileCXX` module ``check_include_file_cxx`` macro
  learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable.
  See policy :policy:`CMP0075`.

* The :module:`CheckIncludeFiles` module ``check_include_files`` macro
  learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable.
  See policy :policy:`CMP0075`.

* The :manual:`cmake(1)` ``-E copy_directory`` tool now fails when the
  source directory does not exist.  Previously it succeeded by creating
  an empty destination directory.

* The :module:`UseSWIG` module :command:`swig_add_library` command
  (and legacy ``swig_add_module`` command) now set the prefix of
  Java modules to ``""`` for MINGW, MSYS, and CYGWIN environments.

.. _Fortran Submodules: https://fortranwiki.org/fortran/show/Submodules


code:
CMake 3.13 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.12 include the following.

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

Generators
----------

* The :ref:`Visual Studio Generators` for VS 2010 and above learned to
  support the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property
  and supporting :module:`CheckIPOSupported` module.

* The :generator:`Xcode` generator learned to configure more Xcode Scheme
  fields.  See the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable.

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

  - Added support for architecture selection through
    :variable:`CMAKE_GENERATOR_PLATFORM`:
    e.g. ``arm``, ``ppc``, and ``86``.

  - Added support for toolset selection through
    :variable:`CMAKE_GENERATOR_TOOLSET`,
    e.g. ``comp_201205``, ``comp_201510``, ``comp_201722_beta``.

  - Added support for platform selection through ``GHS_TARGET_PLATFORM``,
    e.g. ``integrity``, ``linux``, ``standalone``, etc.

  - No longer checks that ``arm`` based compilers are installed but ensures
    that the correct ``gbuild.exe`` exists.

  - No longer hard-codes ARM files, BSP, toolset, or OS locations.

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

* The :manual:`cmake(1)` command gained the ``-S <source_dir>``
  command line option to specify the location of the source directory.
  This option can be used independently of ``-B``.

* The :manual:`cmake(1)` command gained the ``-B <build_dir>``
  command line option to specify the location of the build directory.
  This option can be used independently of ``-S``.

* The :manual:`cmake(1)` ``-E create_symlink`` command can now be used
  on Windows.

Commands
--------

* The :command:`add_custom_command` and :command:`add_custom_target` commands
  learned to support generator expressions in ``WORKING_DIRECTORY`` options.

* The :command:`add_link_options` command was created to add link
  options in the current directory.

* The :command:`install(TARGETS)` command learned to install targets
  created outside the current directory.

* The :command:`link_directories` command gained options to control
  insertion position.

* The :command:`list(SORT)` command gained options to control the
  comparison operation used to order the entries.

* The :command:`math` command gained options for hexadecimal.

* The :command:`target_link_directories` command was created to
  specify link directories for targets and their dependents.

* The :command:`target_link_options` command was created to
  specify link options for targets and their dependents.

* The :command:`target_link_libraries` command may now be called
  to modify targets created outside the current directory.
  See policy :policy:`CMP0079`.

Variables
---------

* A :variable:`CMAKE_AUTOGEN_VERBOSE` variable was added to optionally
  increase the verbosity of :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC`
  and :prop_tgt:`AUTORCC` from within CMake project code.

* A :variable:`CMAKE_VS_GLOBALS` variable was added to initialize
  :prop_tgt:`VS_GLOBAL_<variable>` target properties on targets as
  they are created.

Properties
----------

* The :prop_tgt:`DEPLOYMENT_ADDITIONAL_FILES` target property was
  added to tell the :generator:`Visual Studio 9 2008` generator
  to specify additional files for deployment to WinCE devices
  for remote debugging.

* The :prop_tgt:`INTERFACE_LINK_DEPENDS` target property was created
  to specify transitive link dependencies on files.

* The :prop_tgt:`LINK_DEPENDS` target property learned to support
  :manual:`generator expressions <cmake-generator-expressions(7)>`.

* :prop_tgt:`LINK_DIRECTORIES` and :prop_tgt:`INTERFACE_LINK_DIRECTORIES`
  target properties were added to collect link directories for a target
  and its dependents.  Use the :command:`target_link_directories` command
  to set them.

* :prop_tgt:`LINK_OPTIONS` and :prop_tgt:`INTERFACE_LINK_OPTIONS` target
  properties were added to collect link options for a target and its
  dependents.  Use the :command:`target_link_options` command to set them.

* A :prop_dir:`LINK_OPTIONS` directory property was added to collect
  link options for targets created under the current directory.
  Use the :command:`add_link_options` command to set it.

* A :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property was created
  to specify archiver options to use when creating static libraries.

* A :prop_tgt:`VS_DEBUGGER_COMMAND_ARGUMENTS` target property was created to
  set the debugging command line arguments with
  :ref:`Visual Studio Generators` for VS 2010 and above.

* A :prop_tgt:`VS_DEBUGGER_ENVIRONMENT` target property was created to
  set the debugging environment with
  :ref:`Visual Studio Generators` for VS 2010 and above.

* The :prop_tgt:`VS_DEBUGGER_COMMAND` and
  :prop_tgt:`VS_DEBUGGER_WORKING_DIRECTORY` target properties
  now support generator expressions.

Modules
-------

* The :module:`FindBoost` module gained a ``Boost_ARCHITECTURE`` option
  to specify a Boost architecture-specific library filename fragment.

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

* The :module:`FindMatlab` module gained new components ``ENGINE_LIBRARY`` and
  ``DATAARRAY_LIBRARY`` to request finding the Matlab C++ Engine and DataArray
  libraries respectively.

* The :module:`FindMatlab` module now explicitly exports mexFunction in Visual
  Studio.

* The :module:`FindMatlab` module gained a new ``MCC_COMPILER``
  component to request finding the Matlab Compiler add-on.

* The :module:`FindPkgConfig` module gained an option to create imported
  targets in global scope.

* The :module:`FindPkgConfig` module gained support for ``<`` and ``>``
  operators for version checks in addition to the already supported
  operators ``>=``, ``<=``, and ``=``.

* Modules :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
  gain capability to control order of resource lookup on macOS (Framework) and
  Windows (Registry).

* The :module:`FindSubversion` module ``Subversion_WC_INFO`` command
  gained an ``IGNORE_SVN_FAILURE`` option to suppress failures,
  e.g. when the source tree is not under Subversion control.

* The :module:`UseSWIG` module learned to manage target property
  :prop_tgt:`INCLUDE_DIRECTORIES` for ``SWIG`` compilation.

CTest
-----

* :manual:`ctest(1)` gained a ``--progress`` option to enable a live
  test progress summary when output goes to a terminal.

CPack
-----

* The :cpack_gen:`CPack DEB Generator` learned to split debug symbols into
  a corresponding .ddeb package when ``CPACK_DEBIAN_DEBUGINFO_PACKAGE`` is
  set.

* The :cpack_gen:`CPack DEB Generator` learned to honor the ``SOURCE_DATE_EPOCH``
  environment variable when packaging files.  This is useful for generating
  reproducible packages.

* CPack gained a new :cpack_gen:`CPack External Generator` which is used to
  export the CPack metadata in a format that other software can understand. The
  intention of this generator is to allow external packaging software to take
  advantage of CPack's features when it may not be possible to use CPack for
  the entire packaging process.

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

* An explicit deprecation diagnostic was added for policies ``CMP0055``
  through ``CMP0063`` (``CMP0054`` 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
=============

* The precompiled binaries provided on ``cmake.org`` now include
  qthelp-format documentation.

* The :command:`option` command now honors an existing normal variable
  of the same name and does nothing instead of possibly creating a cache
  entry (or setting its type) and removing the normal variable.
  See policy :policy:`CMP0077`.

* The :ref:`Makefile Generators` learned to remove custom command and
  custom target byproducts during ``make clean``.

* The :command:`target_sources` command now interprets relative source file
  paths as relative to the current source directory.  This simplifies
  incrementally building up a target's sources from subdirectories.  The
  :policy:`CMP0076` policy was added to provide backward compatibility with
  the old behavior where required.

* The :module:`BundleUtilities` module may no longer be included at configure
  time. This was always a bug anyway. See policy :policy:`CMP0080`.

* The :module:`UseSWIG` module has changed strategy for target naming.
  See policy :policy:`CMP0078`.

* The :prop_tgt:`LINK_DIRECTORIES` target property now expects absolute paths.
  See policy :policy:`CMP0081`.

* The CPack generators have been moved into their own separate section
  in the documentation, rather than having the documentation in their
  internal implementation modules.
  These internal implementation modules are also no longer available
  to scripts that may have been incorrectly including them, because
  they should never have been available in the first place.

Updates
=======

Changes made since CMake 3.13.0 include the following.

3.13.2
------

* CMake 3.13.0 included a change to pass compiler implicit include
  directories to the ``moc`` tool for :prop_tgt:`AUTOMOC`.  This has
  been reverted due to regressing existing builds and will need
  further investigation before being re-introduced in a later release.

3.13.3
------

* The :generator:`Visual Studio 15 2017` generator has been fixed to work
  when VS 2019 is installed.

* CMake now checks that at least one of the source or binary directory
  is specified when running CMake and issues an error if both are missing.
  This has always been a documented requirement, but the implementation
  previously accidentally accepted cases in which neither are specified
  so long as some other argument is given, and silently used the current
  working directory as the source and build tree.

3.13.4
------

* The error added by 3.13.3 in cases that neither a source or binary
  directory is specified has been downgraded to a warning.  While this
  was never intended, documented, nor supported behavior, some projects
  relied on it.  The error has been downgraded to a warning for the
  remainder of the 3.13.x release series to allow a transition period,
  but it may become a fatal error again in a later release.  Scripts
  relying on the old behavior can be trivially fixed by specifying
  the path to the source tree (even if just ``.``) explicitly and
  continue to work with all versions of CMake.

3.13.5
------

* In CMake 3.13.0 through 3.13.4, 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.


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.


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.