code:
CMake 3.27 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.26 include the following.

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

Debugger
--------

* :manual:`cmake(1)` now supports interactive debugging of the CMake language.
  See the :option:`--debugger <cmake --debugger>` option.

Presets
-------

* :manual:`cmake-presets(7)` files now support schema version ``7``.

* :manual:`cmake-presets(7)` now supports ``$penv{}`` macro expansion
  in ``include`` fields.

Generators
----------

* The :ref:`Makefile <Makefile Generators>` and :ref:`Ninja <Ninja Generators>`
  generators now support using the ``--dependency-file`` linker flag,
  added by GNU Binutils 2.35 and LLVM's LLD 12.0.0, so that files read by the
  linker will cause a relink if they change (typically modified timestamps).
  See the :variable:`CMAKE_LINK_DEPENDS_USE_LINKER` variable.

* The :ref:`Visual Studio Generators` for VS 14 (2015) and above learned to
  select the Windows SDK version explicitly using a ``version=`` field
  in the :variable:`CMAKE_GENERATOR_PLATFORM` variable.
  See :ref:`Visual Studio Platform Selection`.

Languages
---------

* The ``CXX`` language now treats source file extensions
  ``.ccm``, ``.cxxm``, and ``.c++m`` as C++.

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

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

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

Platforms
---------

* Apple text-based stubs (i.e. ``.tbd`` files) may now be created for shared
  libraries on macOS.  See the :prop_tgt:`ENABLE_EXPORTS` property.

Commands
--------

* The :command:`add_custom_command` command gained a new
  ``DEPENDS_EXPLICIT_ONLY`` option to tell the :ref:`Ninja Generators`
  not to add any dependencies implied by the target to which it is
  attached.  The :variable:`CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY`
  variable was added to enable ``DEPENDS_EXPLICIT_ONLY`` on all calls to
  :command:`add_custom_command` command.

* The :command:`cmake_file_api` command was added for projects to add
  :manual:`CMake file API <cmake-file-api(7)>` queries for the current
  CMake run.

* The :command:`find_package` command now searches prefixes specified by
  upper-case :variable:`<PACKAGENAME>_ROOT` CMake variables and upper-case
  :envvar:`<PACKAGENAME>_ROOT` environment variables.
  See policy :policy:`CMP0144`.

* The :command:`install(CODE)` and :command:`install(SCRIPT)` commands
  now support the :genex:`$<INSTALL_PREFIX>` generator expression.

Variables
---------

* The :variable:`CMAKE_DLL_NAME_WITH_SOVERSION` variable and associated
  :prop_tgt:`DLL_NAME_WITH_SOVERSION` target property were added to
  optionally append the :prop_tgt:`SOVERSION` to the filename of the
  ``.dll`` part of a shared library on Windows.

* Variables :variable:`CMAKE_VS_DEBUGGER_COMMAND`,
  :variable:`CMAKE_VS_DEBUGGER_COMMAND_ARGUMENTS`,
  :variable:`CMAKE_VS_DEBUGGER_ENVIRONMENT`, and
  :variable:`CMAKE_VS_DEBUGGER_WORKING_DIRECTORY` were added to initialize
  corresponding target properties.

* The :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION` variable
  was added to initialize the :prop_tgt:`VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION`
  target property on all targets when they are created.

Properties
----------

* A :prop_tgt:`CUDA_CUBIN_COMPILATION` target property was added to
  :ref:`Object Libraries` to support compiling to ``.cubin`` files
  instead of host object files. Currently only supported with NVIDIA.

* A :prop_tgt:`CUDA_FATBIN_COMPILATION` target property was added to
  :ref:`Object Libraries` to support compiling to ``.fatbin`` files
  instead of host object files. Currently only supported with NVIDIA.

* A :prop_tgt:`CUDA_OPTIX_COMPILATION` target property was added to
  :ref:`Object Libraries` to support compiling to ``.optixir`` files
  instead of host object files. Currently only supported with NVIDIA.

* The :prop_tgt:`<LANG>_CLANG_TIDY`, :prop_tgt:`<LANG>_CPPCHECK`,
  :prop_tgt:`<LANG>_CPPLINT`, and :prop_tgt:`<LANG>_INCLUDE_WHAT_YOU_USE`,
  target properties now support
  :manual:`generator expressions <cmake-generator-expressions(7)>`.

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

* The :prop_sf:`SKIP_LINTING` source file property was added to suppress
  target-wide code checks on specific sources.

Modules
-------

* The :module:`FindCUDAToolkit` module now provides an imported target for
  ``cudla``, and imported targets for CUPTI's ``nvperf`` and ``pcsampling``
  components.

* The :module:`FindDoxygen` module's :command:`doxygen_add_docs` command gained
  a ``CONFIG_FILE`` option to specify a custom doxygen configuration file.

* The :module:`FindOpenGL` module gained support for components
  ``GLES2`` and ``GLES3``.

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

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

* The :genex:`COMPILE_ONLY` generator expression was added to specify
  compilation usage requirements without any linking requirements.

* ``$<LIST:...>`` generator expressions were added for
  :ref:`query <GenEx List Queries>`,
  :ref:`transformation <GenEx List Transformations>`, and
  :ref:`ordering <GenEx List Ordering>` operations on
  :ref:`lists <CMake Language Lists>`.

* ``$<PATH:...>`` generator expressions for
  :ref:`decomposition <GenEx Path Decomposition>` and
  :ref:`transformation <GenEx Path Transformations>` operations learned
  to process :ref:`lists <CMake Language Lists>` of paths element-wise.

* The :genex:`TARGET_IMPORT_FILE`, :genex:`TARGET_IMPORT_FILE_BASE_NAME`,
  :genex:`TARGET_IMPORT_FILE_PREFIX`, :genex:`TARGET_IMPORT_FILE_SUFFIX`,
  :genex:`TARGET_IMPORT_FILE_NAME`, and :genex:`TARGET_IMPORT_FILE_DIR`
  generator expressions were added.  These expand to details about the
  linker import file for a target.

* The :genex:`TARGET_RUNTIME_DLL_DIRS` generator expression was added.
  It expands to a list of the directories containing DLLs in
  :genex:`TARGET_RUNTIME_DLLS`.

Autogen
-------

* The :variable:`CMAKE_AUTOMOC_EXECUTABLE`,
  :variable:`CMAKE_AUTORCC_EXECUTABLE`, and
  :variable:`CMAKE_AUTOUIC_EXECUTABLE` variables were added to initialize the
  corresponding target properties as targets are created.

* The :prop_tgt:`AUTOGEN_USE_SYSTEM_INCLUDE` target property and
  corresponding :variable:`CMAKE_AUTOGEN_USE_SYSTEM_INCLUDE` variable were
  added to explicitly control whether autogen headers are
  considered system headers.

* The :prop_tgt:`INTERFACE_AUTOMOC_MACRO_NAMES` target property was added to
  specify macro names for ``moc`` as a transitive usage requirement.

CTest
-----

* The :prop_test:`TIMEOUT_SIGNAL_NAME` and
  :prop_test:`TIMEOUT_SIGNAL_GRACE_PERIOD` test properties were added
  to specify a POSIX signal to send to a test process when its timeout
  is reached.

CPack
-----

* The :cpack_gen:`CPack Inno Setup Generator` was added to package using
  Inno Setup.

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

* Compatibility with versions of CMake older than 3.5 is now deprecated
  and will be removed from a future version.  Calls to
  :command:`cmake_minimum_required` or :command:`cmake_policy` that set
  the policy version to an older value now issue a deprecation diagnostic.

* The :ref:`Extra Generators` have been deprecated.  IDEs may use the
  :manual:`cmake-file-api(7)` to view CMake-generated project build trees.

* The :module:`FindCUDA` module, which has been deprecated since CMake 3.10,
  has been removed by policy :policy:`CMP0146`.  Port projects to CMake's
  first-class ``CUDA`` language support.

* The :module:`FindPythonInterp` and :module:`FindPythonLibs` modules,
  which have been deprecated since CMake 3.12, have been removed by
  policy :policy:`CMP0148`.  Port projects to :module:`FindPython3`,
  :module:`FindPython2`, or :module:`FindPython`.

* The :module:`Dart` and :module:`FindDart` modules have been deprecated via
  policy :policy:`CMP0145`.  Port projects to the :module:`CTest` module.

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

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

* ``cmake --build $dir --verbose`` will now print the working directory and
  command line used to perform the build.

* The :module:`ExternalProject` and :module:`FetchContent` modules
  now resolve relative ``GIT_REPOSITORY`` paths as relative to the
  parent project's remote, not as a relative local file system path.
  See :policy:`CMP0150`.

* The :module:`ExternalProject` ``configure`` step no longer re-runs on
  every build when the ``UPDATE_DISCONNECTED`` option is enabled.
  It will only re-run if details of the ``download``, ``update``,
  or ``patch`` step change.

* The :module:`ExternalProject` ``update`` and ``patch`` steps now always
  re-run if any of their details change, even if the ``UPDATE_DISCONNECTED``
  option is enabled.  If using the ``GIT`` download method, and the ``GIT_TAG``
  is changed to a commit that is not already known locally, an error is now
  issued instead of silently using the previous ``GIT_TAG``.

* The :module:`FindPython`, :module:`FindPython2` and :module:`FindPython3`
  modules now support the Windows ARM64 platform.

* The :command:`file(GET_RUNTIME_DEPENDENCIES)` command now case-preserves
  DLL names reported on Windows.  They are still converted to lowercase
  for filter matching.

* The :prop_tgt:`SYSTEM` target property is now honored for Apple Frameworks.

* :ref:`Visual Studio Generators`, for VS 15.8 (2017) and newer, now
  build custom commands in parallel.  See policy :policy:`CMP0147`.

* :ref:`Visual Studio Generators` for VS 14 (2015) and above now prefer
  to select the latest Windows SDK version.  See policy :policy:`CMP0149`.

Updates
=======

Changes made since CMake 3.27.0 include the following.

3.27.1
------

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

3.27.2
------

* :ref:`Visual Studio Generators` for VS 14 (2015) and above now prefer to
  select the latest Windows SDK, as documented by policy :policy:`CMP0149`,
  when targeting any version of Windows.  In CMake 3.27.[0-1] the
  preference was limited to targeting Windows 10 and above.

* :ref:`Visual Studio Generators` for VS 14 (2015) and above now support
  using ``version=8.1`` in the :variable:`CMAKE_GENERATOR_PLATFORM` variable
  to select the Windows 8.1 SDK.  In CMake 3.27.[0-1] the ``version=`` field
  was limited to selecting Windows 10 SDKs.

3.27.3, 3.27.4, 3.27.5, 3.27.6, 3.27.7, 3.27.8
----------------------------------------------

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

3.27.9
------

* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object
  ``fileSets`` field was introduced by CMake 3.26.0 with entries of its
  ``baseDirectories`` member incorrectly expressed as absolute paths
  even if they are inside the top-level source directory.  This was
  fixed in CMake 3.26.6 and has now been fixed in 3.27.9.  Clients must
  be updated to expect relative paths under the top-level source directory.

* Fortran module dependency scanning in :ref:`Ninja Generators` was updated
  by CMake 3.27.0 to use exact collation dependencies.  This was supposed
  to fix subtle rebuild failures when moving module sources among targets.
  Since then, several cases have been found in which exact collation
  dependencies were incorrectly computed when using :ref:`Object Libraries`.
  Some of these cases were incrementally fixed through the 3.27.x patch
  series, but additional more subtle cases have since been found.  In order
  to avoid further churn in the 3.27 release series, the original change has
  been reverted and deferred to a future version of CMake.


code:
CMake 3.28 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.27 include the following.

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

Languages
---------

* C++ 20 named modules are now supported by :ref:`Ninja Generators`
  and :ref:`Visual Studio Generators` for VS 2022 and newer, in combination
  with the MSVC 14.34 toolset (provided with VS 17.4) and newer, LLVM/Clang
  16.0 and newer, and GCC 14 (after the 2023-09-20 daily bump) and newer.
  See :manual:`cmake-cxxmodules(7)` for details.

* ``HIP`` language code may now be compiled for NVIDIA GPUs
  using the NVIDIA CUDA Compiler (NVCC).
  See the :variable:`CMAKE_HIP_PLATFORM` variable.

Platforms
---------

* On Apple platforms, ``.xcframework`` folders are now supported:

  * The :command:`find_library` command now finds ``.xcframework`` folders.

  * The :command:`target_link_libraries` command now supports
    linking against a ``.xcframework`` folder.

  * The :prop_tgt:`IMPORTED_LOCATION` target property of an imported
    library target may now be the path to a ``.xcframework`` folder.

* Apple visionOS and its ``xros`` and ``xrsimulator`` SDKs are now supported.
  Compiling for Apple visionOS can be requested by setting
  :variable:`CMAKE_SYSTEM_NAME` to ``visionOS``.
  See :ref:`Cross Compiling for iOS, tvOS, visionOS, or watchOS`
  for more information.

Presets
-------

* :manual:`cmake-presets(7)` files now support schema version ``8``.
  It adds support for a ``$schema`` field.

Compilers
---------

* Cray Clang-based compilers are now supported with
  :variable:`compiler id <CMAKE_<LANG>_COMPILER_ID>` ``CrayClang``.

* The OrangeC compiler is now supported with
  :variable:`compiler id <CMAKE_<LANG>_COMPILER_ID>` ``OrangeC``.

Commands
--------

* The :command:`add_custom_command` and :command:`add_custom_target`
  commands gained a ``JOB_SERVER_AWARE`` option.

* The :command:`cmake_host_system_information` command gained a
  ``MSYSTEM_PREFIX`` query for the installation prefix of a MSYS
  or MinGW development environment on Windows hosts.

* The :command:`set_property` command ``TEST`` mode gained a ``DIRECTORY``
  option to set properties on tests in other directories.

* The :command:`set_tests_properties` command gained a ``DIRECTORY``
  option to set properties on tests in other directories.

* The :command:`get_property` command ``TEST`` mode gained a ``DIRECTORY``
  option to get properties on tests in other directories.

* The :command:`get_test_property` command gained a ``DIRECTORY``
  option to get properties on tests in other directories.

Variables
---------

* The :envvar:`CMAKE_CROSSCOMPILING_EMULATOR` environment variable
  was added to initialize the :variable:`CMAKE_CROSSCOMPILING_EMULATOR`
  cache variable.

* The :variable:`CMAKE_HIP_PLATFORM` variable was added to specify
  the GPU platform for which HIP language sources are to be compiled
  (``amd`` or ``nvidia``).

Properties
----------

* On imported shared libraries, the :prop_tgt:`IMPORTED_IMPLIB` target
  property may now be used without :prop_tgt:`IMPORTED_LOCATION`.
  This can be used to represent a stub library whose location should not
  be added as a runtime search path to dependents that link it.

* The :prop_tgt:`IMPORTED_LOCATION` property of a macOS framework
  may now be a path to the ``.framework`` folder itself.

* The :prop_tgt:`XCODE_EMBED_RESOURCES <XCODE_EMBED_<type>>` target property
  was added to tell the :generator:`Xcode` generator what targets to put in
  the ``Embed Resources`` build phase.

Modules
-------

* The :module:`ExternalProject` module now includes the
  ``BUILD_JOB_SERVER_AWARE`` option for the
  :command:`ExternalProject_Add` command. This option enables
  the integration of the GNU Make job server when using an
  explicit ``BUILD_COMMAND`` with certain :ref:`Makefile Generators`.
  Additionally, the :command:`ExternalProject_Add_Step` command
  has been updated to support the new ``JOB_SERVER_AWARE`` option.

* The :module:`FetchContent` module's :command:`FetchContent_Declare` command
  gained an ``EXCLUDE_FROM_ALL`` option, which propagates through to the
  :command:`add_subdirectory` call made by
  :command:`FetchContent_MakeAvailable` for the dependency.

* The :module:`FindCURL` module gained a ``CURL_USE_STATIC_LIBS`` hint
  to select static libraries.

* The :module:`FindEXPAT` module gained an ``EXPAT_USE_STATIC_LIBS`` hint
  to select static libraries.

* The :module:`FindPkgConfig` module :command:`pkg_get_variable` command
  gained a ``DEFINE_VARIABLES`` option to pass variables to ``pkg-config``.

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

* The :manual:`generator expressions <cmake-generator-expressions(7)>`
  :genex:`$<IF:...>`, :genex:`$<AND:...>`, and :genex:`$<OR:...>`
  short-circuit to avoid unnecessary evaluation of parameters.

CTest
-----

* CTest may now take a :ref:`dynamically-generated resource spec file
  <ctest-resource-dynamically-generated-spec-file>`, which can be specified by the
  :prop_test:`GENERATED_RESOURCE_SPEC_FILE` test property.

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

* The :command:`exec_program` command, which has been deprecated
  since CMake 3.0, has been removed by policy :policy:`CMP0153`.
  Use the :command:`execute_process` command instead.

* The :generator:`Visual Studio 11 2012` generator has been removed.

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

* The :prop_tgt:`IOS_INSTALL_COMBINED` target property and corresponding
  :variable:`CMAKE_IOS_INSTALL_COMBINED` variable have been deprecated.
  Their functionality does not make sense on Apple Silicon hosts.

* The :generator:`Xcode` generator will now issue a fatal error if
  the Legacy Build System has been selected for Xcode 14 and
  newer. Those Xcode versions dropped support for the Legacy Build
  System and expect the project to be set-up for their current
  Build System.

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

* Generated files, in targets using :ref:`file sets`, are now considered
  private by default.  Generated public headers must be specified using
  file sets.  This allows :ref:`Ninja Generators` to produce more
  efficient build graphs.  See policy :policy:`CMP0154`.

* The :command:`find_library`, :command:`find_path`, and :command:`find_file`
  commands no longer search in installation prefixes derived from the ``PATH``
  environment variable.  This behavior was added in CMake 3.3 to support
  MSYS and MinGW (``MSYSTEM``) development environments on Windows, but
  it can search undesired prefixes that happen to be in the ``PATH`` for
  unrelated reasons.  Users who keep some ``<prefix>/bin`` directories in
  the ``PATH`` just for their tools do not necessarily want any corresponding
  ``<prefix>/lib`` or ``<prefix>/include`` directories searched.
  The behavior was reverted for non-Windows platforms by CMake 3.6.
  Now it has been reverted on Windows platforms too.

  One may set the ``CMAKE_PREFIX_PATH`` environment variable with a
  :ref:`semicolon-separated list <CMake Language Lists>` of prefixes
  that are to be searched.

* When using MinGW tools in a ``MSYSTEM`` environment on Windows,
  the ``$MSYSTEM_PREFIX/local`` and ``$MSYSTEM_PREFIX`` prefixes are
  now added to :variable:`CMAKE_SYSTEM_PREFIX_PATH`.

* The precompiled Linux ``x86_64`` binaries provided on
  `cmake.org <https://cmake.org/download/>`_ now require GLIBC 2.17 or higher.

Updates
=======

Changes made since CMake 3.28.0 include the following.

3.28.1, 3.28.2, 3.28.3
----------------------

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

.. 3.28.4 (unreleased)

  * Apple visionOS support has been updated for the official Xcode 15.2
    release of the  ``xros`` and ``xrsimulator`` SDKs.

repo_name: lazytadpole/codenamesilverfish

license: mit


code:
CMake 3.29 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.28 include the following.

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

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

* :manual:`cmake(1)` :option:`-E cat <cmake-E cat>` can now print the standard
  input by passing the ``-`` argument.

Generators
----------

* :ref:`Visual Studio Generators` now support selecting between the
  Intel oneAPI Fortran compiler (``ifx``) and the Intel classic Fortran
  compiler (``ifort``) using a ``fortran=`` field in
  :variable:`CMAKE_GENERATOR_TOOLSET`.

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

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

* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object gained
  a new "launchers" field.

Compilers
---------

* The LLVM/Clang GNU-like frontend on Windows (``clang++``) may now be used
  to compile ``CUDA`` language sources.

* Compilers targeting the GNU ABI on Windows (MinGW) may now be used to
  compile Objective C (``OBJC``) and Objective C++ (``OBJCXX``).  These
  include GNU compilers (``gcc`` and ``g++``) and the LLVM/Clang GNU-like
  frontends (``clang`` and ``clang++``).

* TI Clang-based compilers are now supported with
  :variable:`compiler id <CMAKE_<LANG>_COMPILER_ID>` ``TIClang``.

Commands
--------

* The :ref:`add_custom_command(TARGET) <add_custom_command(TARGET)>`
  signature now supports adding build events through :ref:`Alias Targets`.

* The :command:`cmake_language(EXIT)` sub-command was added to terminate
  :option:`cmake -P` scripts with a specified exit code.

* The :command:`export(SETUP)` sub-command was added to configure export sets.
  Its ``PACKAGE_DEPENDENCY`` option configures how :command:`find_dependency`
  calls are exported.  Its ``TARGET`` option's ``XCFRAMEWORK_LOCATION``
  setting specifies the location of a ``.xcframework`` that can be
  substituted for an installed target.

* The :command:`if` command gained new tests ``IS_READABLE``, ``IS_WRITABLE``
  and ``IS_EXECUTABLE`` to check file or directory permissions.

* :command:`install(EXPORT)` and :command:`export(EXPORT)` learned a new
  ``EXPORT_PACKAGE_DEPENDENCIES`` argument, which can be used to generate
  :command:`find_dependency` calls based on what targets the exported targets
  depend on.

Variables
---------

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

* The :variable:`CMAKE_LINKER_TYPE` variable and corresponding
  :prop_tgt:`LINKER_TYPE` target property were added to specify
  what linker to use with some toolchains.

* The :variable:`CMAKE_<LANG>_COMPILER_LINKER`,
  :variable:`CMAKE_<LANG>_COMPILER_LINKER_ID`,
  :variable:`CMAKE_<LANG>_COMPILER_LINKER_VERSION` and
  :variable:`CMAKE_<LANG>_COMPILER_LINKER_FRONTEND_VARIANT` variables
  were added to describe the linker used by the language's link step.

* The :variable:`CMAKE_PROJECT_INCLUDE`,
  :variable:`CMAKE_PROJECT_INCLUDE_BEFORE`,
  :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, and
  :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` variables learned
  to support a :ref:`semicolon-separated list <CMake Language Lists>` of
  CMake language files to be included sequentially. These variables can also
  reference module names to be found in :variable:`CMAKE_MODULE_PATH` or
  builtin to CMake.

* The :variable:`CMAKE_SKIP_TEST_ALL_DEPENDENCY` variable was added
  to control whether the ``test`` (or ``RUN_TESTS``) buildsystem
  target depends on the ``all`` (or ``ALL_BUILD``) target.

* A :variable:`CMAKE_TEST_LAUNCHER` variable and corresponding
  :prop_tgt:`TEST_LAUNCHER` target property were added to specify
  a launcher to be used by executable targets when invoked by
  tests added by the :command:`add_test` command.

Properties
----------

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

* The :prop_tgt:`EXPORT_FIND_PACKAGE_NAME` target property was added to
  allow targets to specify what package name to pass when exporting
  :command:`find_dependency` calls. This property is initialized with a new
  :variable:`CMAKE_EXPORT_FIND_PACKAGE_NAME` variable.

* The :prop_tgt:`UNITY_BUILD` target property now supports the
  Objective C (``OBJC``) and Objective C++ (``OBJCXX``) languages.

* The :prop_tgt:`XCODE_EMBED_XPC_SERVICES <XCODE_EMBED_<type>>` target property
  was added to tell the :generator:`Xcode` generator what targets to put in
  the ``Embed XPC Resources`` build phase.

Modules
-------

* The :module:`CMakePackageConfigHelpers` module gained new
  :command:`generate_apple_platform_selection_file` and
  :command:`generate_apple_architecture_selection_file` functions, which can
  be used to generate a file that includes another Apple-platform-specific
  file or the includes an architecture-specific implementation of a package
  for an Apple platform, respectively.

* The :module:`FindOpenGL` module learned to find a GLU include
  directory different than the GL include directory.  A new
  ``OPENGL_INCLUDE_DIRS`` result variable provides all include
  directories.

CTest
-----

* :manual:`ctest(1)` gained a :option:`--http-header <ctest --http-header>`
  option to add custom headers on submission to CDash.

* :manual:`ctest(1)` gained the :option:`--tests-from-file <ctest
  --tests-from-file>` and :option:`--exclude-from-file <ctest
  --exclude-from-file>` options to run or exclude tests named in a file.

* :manual:`ctest(1)` now supports :ref:`job server integration
  <ctest-job-server-integration>` on POSIX systems.

* The :command:`ctest_test` command gained options
  ``INCLUDE_FROM_FILE`` and ``EXCLUDE_FROM_FILE`` to run or exclude
  tests named in a file.

CPack
-----

* The :cpack_gen:`CPack DEB Generator` :variable:`CPACK_DEBIAN_FILE_NAME`
  variable may now be set without any suffix, and the ``.deb`` suffix
  will be added automatically.

* The :cpack_gen:`CPack RPM Generator` :variable:`CPACK_RPM_FILE_NAME`
  variable may now be set without any suffix, and the ``.rpm`` suffix
  will be added automatically.

* The :cpack_gen:`CPack WIX Generator` gained a new variable,
  :variable:`CPACK_WIX_INSTALL_SCOPE`, to control the
  ``InstallScope`` property of WiX MSI installers.

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

* CMake learned to de-duplicate libraries on link lines based on linker
  capabilities.  See policy :policy:`CMP0156`.

* The :command:`add_test` command now honors
  :variable:`CMAKE_CROSSCOMPILING_EMULATOR` only when cross-compiling.
  See policy :policy:`CMP0158`.

* :command:`FetchContent_MakeAvailable` now sets the
  :variable:`CMAKE_EXPORT_FIND_PACKAGE_NAME` variable for CMake projects.

* On Windows, when targeting the MSVC ABI, the :command:`find_library` command
  now accepts ``.a`` file names after first considering ``.lib``.  This is
  symmetric with existing behavior when targeting the GNU ABI, in which the
  command accepts ``.lib`` file names after first considering ``.a``.

* On Windows, when targeting the MSVC ABI, the :command:`find_library` command
  now considers ``.dll.lib`` file names before ``.lib``.  This is the default
  suffix for DLL import libraries created by Rust toolchains for the MSVC ABI.

* The :generator:`Ninja` and :generator:`NMake Makefiles` generators now use
  the ``-external:I`` flag for system includes when using IntelLLVM as of
  version 2021.4. The ``-external:W0`` flag is also used as of version 2022.2.

* The :command:`create_test_sourcelist` command now provides a full path to
  the generated driver source file.

* The :variable:`CPACK_PRODUCTBUILD_DOMAINS` variable now defaults to true.
  See policy :policy:`CMP0161`.

* The :cpack_gen:`CPack WIX Generator` now produces WiX MSI installers
  that create start menu and uninstall entries for all users by default,
  as documented by the :variable:`CPACK_WIX_INSTALL_SCOPE` variable
  ``perMachine`` value.  Previously, without a custom WiX template,
  it produced installers that would only create start menu and uninstall
  entries for the current user, even though they install for all users.


code:
CMake 3.3 Release Notes
***********************

.. only:: html

  .. contents::

Changes made since CMake 3.2 include the following.

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

Generators
----------

* The :ref:`Makefile Generators` now add ``.DELETE_ON_ERROR`` to the
  makefiles that contain the actual build rules for files on disk.
  This tells GNU make to remove rule outputs when their recipe
  modifies an output but fails.

* The :ref:`Visual Studio Generators` learned to support ``.xaml``
  source files and automatically associate them with corresponding
  ``.h`` and ``.cpp`` sources.

* A new experimental :generator:`Green Hills MULTI` generator was
  added on Windows.  `Green Hills MULTI`_ is an IDE for embedded
  real-time systems.

.. _`Green Hills MULTI`: https://www.ghs.com/products/MULTI_IDE.html

Commands
--------

* The :command:`add_dependencies` command learned to allow dependencies
  to be added to :ref:`interface libraries <Interface Libraries>`.
  Dependencies added to an interface library are followed transitively
  in its place since the target itself does not build.

* The :command:`execute_process` command learned to support specifying
  the same file for ``OUTPUT_FILE`` and ``ERROR_FILE``.

* The :command:`file(GLOB)` and :command:`file(GLOB_RECURSE)` commands
  learned a new ``LIST_DIRECTORIES <bool>`` option to specify whether
  the glob result should include directories.

* The :command:`find_library`, :command:`find_path`, and :command:`find_file`
  commands now search in installation prefixes derived from the ``PATH``
  environment variable.

* The :command:`if` command learned a new ``IN_LIST`` operator that
  evaluates to true if a given element is contained in a named list.

* The :command:`install(EXPORT)` and :command:`export()` commands
  learned to export targets that populate the :prop_tgt:`INTERFACE_SOURCES`
  target property.

* The :command:`install(TARGETS)` command learned to support
  generator expressions in the ``DESTINATION`` value.

Variables
---------

* The version of some Fortran compilers is now detected and stored in the
  :variable:`CMAKE_Fortran_COMPILER_VERSION <CMAKE_<LANG>_COMPILER_VERSION>`
  variable.

* The :ref:`Visual Studio Generators` learned a new
  :variable:`CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD` option
  to put the ``INSTALL`` target in the default build of a
  solution (``.sln``) file.

Properties
----------

* A :prop_tgt:`CROSSCOMPILING_EMULATOR` target property and supporting
  :variable:`CMAKE_CROSSCOMPILING_EMULATOR` variable were introduced
  to allow target platform binaries to run on the host during cross
  compiling.

* A :prop_tgt:`<LANG>_INCLUDE_WHAT_YOU_USE` target property and supporting
  :variable:`CMAKE_<LANG>_INCLUDE_WHAT_YOU_USE` variable were introduced
  to tell the :ref:`Makefile Generators` and the :generator:`Ninja` generator
  to run ``include-what-you-use`` along with the compiler for ``C`` and
  ``CXX`` languages.

* The :prop_tgt:`<LANG>_VISIBILITY_PRESET` and
  :prop_tgt:`VISIBILITY_INLINES_HIDDEN` target properties now
  affect compilation in sources of all target types.  See
  policy :policy:`CMP0063`.

* The :prop_tgt:`XCODE_ATTRIBUTE_<an-attribute>` target property learned
  to support generator expressions.

Modules
-------

* The :module:`CheckFortranCompilerFlag` module was introduced
  to check ``Fortran`` compiler flags, much like the
  :module:`CheckCCompilerFlag` module already does for ``C``.

* The :module:`ExternalData` module learned a new
  :variable:`ExternalData_NO_SYMLINKS` option to disable use of
  symbolic links to populate the real data files and use copies
  instead.

* The :module:`ExternalData` module learned a new ``RECURSE:``
  option in ``DATA{}`` references specifying directories.
  This allows an entire directory tree of associated files
  to be matched.

* The :module:`ExternalData` module learned a new URL template
  placeholder ``%(algo:<key>)`` to allow custom mapping from
  algorithm name to URL component through configuration of new
  :variable:`ExternalData_URL_ALGO_<algo>_<key>` variables.
  This allows more flexibility in remote URLs.

* The :module:`ExternalProject` module learned to replace tokens
  like ``<BINARY_DIR>`` in the ``BYPRODUCTS`` of each step.

* The :module:`ExternalProject` module APIs learned to support
  :manual:`generator expressions <cmake-generator-expressions(7)>`
  when using ``LOG_*`` options and in CMake initial cache options.

* The :module:`FindBoost` module now tracks the directories containing
  libraries separately for RELEASE and DEBUG configurations.

* The :module:`FindCUDA` module now defaults to using the static
  CUDA runtime library if it is available.  A new
  ``CUDA_USE_STATIC_CUDA_RUNTIME`` option is offered to control
  this behavior.

* The :module:`FindMatlab` module was completely rewritten.  It learned
  about versions and components and to find Matlab in a more precise and
  multiplatform way.  The module now offers APIs to create mex extensions,
  documentation, and unit tests.

* The :module:`FindPackageHandleStandardArgs` module
  ``FIND_PACKAGE_HANDLE_STANDARD_ARGS`` function now
  always populates both the ``<PackageName>_FOUND``
  and ``<UPPERCASE_NAME>_FOUND`` variables (the latter
  for backwards compatibility).  The ``FOUND_VAR``
  option is now ignored except to enforce its allowed
  values.

* The :module:`InstallRequiredSystemLibraries` module learned a new
  ``CMAKE_INSTALL_SYSTEM_RUNTIME_COMPONENT`` option to specify the
  installation component.

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

* A new ``COMPILE_LANGUAGE`` generator expression was introduced to
  allow specification of compile options for target files based on the
  :prop_sf:`LANGUAGE` of each source file.  Due to limitations of the
  underlying native build tools, this feature has varying support across
  generators.  See the :manual:`cmake-generator-expressions(7)` manual
  for details.

CTest
-----

* The :manual:`ctest(1)` tool learned a new ``--repeat-until-fail <n>``
  option to help find sporadic test failures.

* The :module:`CTestCoverageCollectGCOV` module learned to support
  the same ``CTEST_CUSTOM_COVERAGE_EXCLUDE`` option as the
  :command:`ctest_coverage` command.

CPack
-----

* The :cpack_gen:`CPack IFW Generator` learned to support
  Qt Framework Installer 2.0 tools.

* The :cpack_gen:`CPack DEB Generator` learned a new
  :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS`
  variable to specify per-component use of ``dpkg-shlibdeps``.

* The :cpack_gen:`CPack DEB Generator` learned a new
  :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS`
  option to specify per-component dependencies.

* The :cpack_gen:`CPack RPM Generator` learned to package symbolic links
  more cleanly and now supports directory symlinks with recent
  ``rpmbuild`` versions.

* The :cpack_gen:`CPack RPM Generator` learned a new
  :variable:`CPACK_RPM_ADDITIONAL_MAN_DIRS` variable to specify
  directories containing man pages for the brp-compress RPM macro.

* The :cpack_gen:`CPack RPM Generator` learned a new
  :variable:`CPACK_RPM_<component>_PACKAGE_ARCHITECTURE` variable
  to specify a component-specific package architecture.

* The CPack WIX generator learned the new
  :prop_inst:`CPACK_START_MENU_SHORTCUTS`,
  :prop_inst:`CPACK_DESKTOP_SHORTCUTS` and
  :prop_inst:`CPACK_STARTUP_SHORTCUTS` installed file properties which can
  be used to install shortcuts in the Start Menu, on the Desktop and
  in the Startup Folder respectively.

Other
-----

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
  is now aware of features supported by GNU compilers on Windows, versions
  4.4 through 5.0.

* The :manual:`cmake(1)` ``-E tar`` command learned a new
  ``--format<format>`` option to specify the archive format to
  be written.

* On OS X, CMake learned to create XCTest bundles to test Frameworks
  and App Bundles within Xcode.  The :module:`FindXCTest` module
  provides convenience functions to handle :prop_tgt:`XCTEST` bundles.

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

* On OS X the :manual:`cmake-gui(1)` no longer has the
  ``Install For Command Line Use`` menu item.  Instead there
  is a ``How to Install For Command Line Use`` menu item
  that shows an informational dialog box explaining how to
  make the command line tools available.  For example::

    /Applications/CMake.app/Contents/bin/cmake-gui --install

* The :command:`ctest_build` and :command:`build_command` commands
  no longer tell ``make`` tools to ignore errors with the ``-i`` option.
  Previously this was done for :ref:`Makefile Generators` but not others.
  See policy :policy:`CMP0061`.

* The :generator:`Visual Studio 10 2010` generator no longer checks
  for running VS IDEs with the project open or asks them to reload.
  This was originally done for VS 10 because it had been done for
  VS 7 through 9 to avoid prompting for every project in a solution.
  Since VS >= 10 allow the whole solution to reload at once they
  do not need CMake to help them.

* The :generator:`Visual Studio 7` generator (.NET 2002) is now
  deprecated and will be removed in a future version of CMake.

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

* The :command:`find_package` command no longer considers project
  build trees recently configured in a :manual:`cmake-gui(1)`.
  This was previously done only on Windows and is now never done.
  The ``NO_CMAKE_BUILDS_PATH`` option is now ignored if given
  and effectively always on.
  Projects may populate the :ref:`User Package Registry` to aid
  users building multiple dependent projects one after another.

* The :command:`add_definitions()` command no longer causes a
  :prop_dir:`DEFINITIONS` directory property to be populated. See policy
  :policy:`CMP0059`.

* With Visual Studio 7, 8, and 9 generators the value of the ``$(OutDir)``
  placeholder no longer evaluates to the configuration name.  Projects
  should use ``$(ConfigurationName)`` for that instead.

* Using the output of :command:`export()` with the :command:`install(FILES)`
  command is no longer allowed.  See policy :policy:`CMP0062` for details.

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

* The :generator:`Ninja` generator now requires that calls to the
  :command:`add_custom_command` and :command:`add_custom_target`
  commands use the ``BYPRODUCTS`` option to explicitly specify any
  files generated by the custom commands that are not listed as
  outputs (perhaps because their timestamps are allowed to be older
  than the inputs).  See policy :policy:`CMP0058`.

* Build-time progress output of :ref:`Makefile Generators` has been improved.
  It no longer mixes progress and build rule messages during parallel builds.
  The link rule messages now have progress and are displayed as bold green
  instead of bold red (since red is often associated with an error message).

* The :variable:`CMAKE_CFG_INTDIR` variable value for Visual Studio
  7, 8, and 9 is now ``$(ConfigurationName)`` instead of ``$(OutDir)``.
  This should have no effect on the intended use cases of the variable.

* Linking to library files by a full path in an implicit linker search
  directory (e.g. ``/usr/lib/libfoo.a``) no longer asks the linker to
  search for the library (e.g. ``-lfoo``) and now links by full path.
  See policy :policy:`CMP0060`.


code:
CMake 3.4 Release Notes
***********************

.. only:: html

  .. contents::

Changes made since CMake 3.3 include the following.

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

Generators
----------

* The :generator:`Visual Studio 14 2015` generator learned to select
  a Windows 10 SDK based on the value of the :variable:`CMAKE_SYSTEM_VERSION`
  variable and the SDKs available on the host.

* CMake learned rudimentary support for the Apple Swift language.  When using
  the :generator:`Xcode` generator with Xcode 6.1 or higher, one may enable
  the ``Swift`` language with the :command:`enable_language` command or the
  :command:`project` command (this is an error with other generators or when
  Xcode is too old).  Then one may list ``.swift`` source files in targets
  for compilation.

Commands
--------

* The :command:`find_program` command learned a ``NAMES_PER_DIR``
  option to consider all given ``NAMES`` in each directory before
  moving on to the next directory.

* The :command:`get_filename_component` command learned a new ``BASE_DIR``
  subcommand.  This is used to specify a base directory when calculating an
  absolute path from a relative path.

* The :command:`if` command learned a new ``TEST`` operator that evaluates
  to true if a given test name has been defined by the :command:`add_test`
  command.  See policy :policy:`CMP0064`.

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

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

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

Variables
---------

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

* New :variable:`CMAKE_LINK_SEARCH_START_STATIC` and
  :variable:`CMAKE_LINK_SEARCH_END_STATIC` variables were
  introduced to initialize the
  :prop_tgt:`LINK_SEARCH_START_STATIC` and
  :prop_tgt:`LINK_SEARCH_END_STATIC` target properties,
  respectively.

Properties
----------

* :ref:`Visual Studio Generators` learned to support additional
  target properties to customize projects for NVIDIA Nsight
  Tegra Visual Studio Edition:

  * :prop_tgt:`ANDROID_ANT_ADDITIONAL_OPTIONS`
  * :prop_tgt:`ANDROID_ARCH`
  * :prop_tgt:`ANDROID_ASSETS_DIRECTORIES`
  * :prop_tgt:`ANDROID_JAR_DEPENDENCIES`
  * :prop_tgt:`ANDROID_JAR_DIRECTORIES`
  * :prop_tgt:`ANDROID_JAVA_SOURCE_DIR`
  * :prop_tgt:`ANDROID_NATIVE_LIB_DEPENDENCIES`
  * :prop_tgt:`ANDROID_NATIVE_LIB_DIRECTORIES`
  * :prop_tgt:`ANDROID_PROCESS_MAX`
  * :prop_tgt:`ANDROID_PROGUARD`
  * :prop_tgt:`ANDROID_PROGUARD_CONFIG_PATH`
  * :prop_tgt:`ANDROID_SECURE_PROPS_PATH`
  * :prop_tgt:`ANDROID_SKIP_ANT_STEP`
  * :prop_tgt:`ANDROID_STL_TYPE`

* The :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`,
  :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY`, and
  :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` target properties learned to
  support :manual:`generator expressions <cmake-generator-expressions(7)>`.

* The :prop_tgt:`SOURCE_DIR` and :prop_tgt:`BINARY_DIR` target properties
  were introduced to allow project code to query where a target is defined.

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

* A :prop_gbl:`TARGET_MESSAGES` global property was added to tell the
  :ref:`Makefile Generators` whether to generate commands to print output
  after each target is completed.

* On Windows with MS-compatible tools, CMake learned to optionally
  generate a module definition (``.def``) file for ``SHARED`` libraries.
  See the :prop_tgt:`WINDOWS_EXPORT_ALL_SYMBOLS` target property.

Modules
-------

* The :module:`ExternalProject` module :command:`ExternalProject_Add`
  function ``GIT_SUBMODULES`` option now also limits the set of
  submodules that are initialized in addition to the prior behavior
  of limiting the set of submodules that are updated.

* The :module:`ExternalProject` module learned new ``USES_TERMINAL``
  arguments for giving steps exclusive terminal access.  This is
  useful with the :generator:`Ninja` generator to monitor CMake
  superbuild progress and prevent CPU oversubscription.

* The :module:`FindBISON` module ``BISON_TARGET`` macro learned a
  new ``DEFINES_FILE`` option to specify a custom output header
  to be generated.

* The :module:`FindHDF5` module learend a new ``HDF5_PREFER_PARALLEL``
  option allowing users to specify that a parallel HDF5 tool is
  preferred if both are available.

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

* The :module:`FindJava` module learned to optionally find
  the ``idlj`` and ``jarsigner`` tools.

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

* The :module:`FindOpenSSL` module learned a new ``OPENSSL_USE_STATIC_LIBS``
  option to search only for static libraries.

* The :module:`FindPkgConfig` learned a new :command:`pkg_get_variable`
  command which may be used to query for arbitrary variables from a package
  (such as for related tools or data and plugin install paths).

* The :module:`FindProtobuf` module gained a new
  :command:`protobuf_generate_python` function to generate python
  sources from ``.proto`` files.

* The :module:`FindTIFF` module learned to search separately for
  debug and release variants.

* The :module:`FindwxWidgets` module learned to support version requests.

* The :module:`FindXercesC` module learned to search separately for
  debug and release variants.

* The :module:`FindZLIB` module learned to search separately for
  debug and release variants.

* The :module:`GNUInstallDirs` module learned special default values
  for certain installation prefixes according to the `GNU Coding
  Standards`_ and the `Filesystem Hierarchy Standard`_.

* The :module:`UseJava` module ``add_jar`` function learned
  to support response files (e.g. ``@srcs.txt``) for source
  specification.

* The :module:`UseJava` module ``install_jar`` function learned
  new ``DESTINATION`` and ``COMPONENT`` options to specify
  the corresponding :command:`install` command options.

* The :module:`UseJava` module gained a new ``create_javah``
  function to create C headers from Java classes.

.. _`GNU Coding Standards`: https://www.gnu.org/prep/standards/html_node/Directory-Variables.html
.. _`Filesystem Hierarchy Standard`: https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html

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

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

CTest
-----

* CTest learned to optionally measure the CPU load during parallel
  testing and avoid starting tests that may cause the load to exceed
  a given threshold.  See the :manual:`ctest(1)` command ``--test-load``
  option, the ``TestLoad`` setting of the :ref:`CTest Test Step`,
  the :variable:`CTEST_TEST_LOAD` variable, and the ``TEST_LOAD``
  option of the :command:`ctest_test` command.

* :manual:`ctest(1)` learned options
  ``--test-output-size-passed`` and ``--test-output-size-failed``
  to customize the limit on test output size submitted when
  running as a :ref:`Dashboard Client`.

CPack
-----

* The :cpack_gen:`CPack DEB Generator` learned to set package dependencies
  per component.  See variables:

  * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS`
  * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONFLICTS`
  * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES`
  * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS`
  * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_PROVIDES`
  * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS`
  * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES`
  * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS`

* The :module:`CPack` module learned to package empty directories.

* The :module:`CPack` module gained a new setting, ``CPACK_VERBATIM_VARIABLES``,
  which can be used to ensure the cpack program receives the settings' values
  exactly as they were set, even if they contain CMake-special characters.
  For compatibility, it's off by default.

Other
-----

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
  is now aware of features supported by GNU C compilers on Windows.

* CMake learned to honor ``*.manifest`` source files with MSVC tools.
  Manifest files named as sources of ``.exe`` and ``.dll`` targets
  will be merged with linker-generated manifests and embedded in the
  binary.

* The Concurrent Fortran 77 compiler is now supported.
  Its :variable:`compiler id <CMAKE_<LANG>_COMPILER_ID>` is ``CCur``.

* :manual:`cmake(1)` gained a new ``--trace-expand`` command line option
  that is like ``--trace`` but expands variable references in the output.

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

* The :module:`CMakeExpandImportedTargets` module is now documented
  as deprecated.  See module documentation for an explanation.

* The :variable:`CMAKE_USE_RELATIVE_PATHS` variable no longer has any
  effect.  Previously it was partially implemented and unreliable.

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

* The :module:`CheckFunctionExists`, :module:`CheckLibraryExists`,
  :module:`CheckSymbolExists`, and :module:`FindThreads` modules learned to
  work in environments where only CXX is enabled.

* The :cpack_gen:`CPack DEB Generator` now correctly excludes symlinks
  during package checksum calculation.

* The :cpack_gen:`CPack DEB Generator` no longer uses fakeroot and
  system tar program for packaging.

* The :module:`CPack` module no longer mangles settings with CMake-special
  characters when they're used as defaults for other settings. The macro
  ``cpack_set_if_not_set``, which was responsible for this, is now deprecated.

* CMake no longer links executables with flags to export symbols
  unless the :prop_tgt:`ENABLE_EXPORTS` target property is set.
  See policy :policy:`CMP0065`.

* The ``SONAME`` field is no longer set for ``MODULE`` libraries
  created with the :command:`add_library` command.  ``MODULE``
  libraries are meant for explicit dynamic loading at runtime.
  They cannot be linked so ``SONAME`` is not useful.

* The internal :variable:`CMAKE_<LANG>_COMPILE_OBJECT` rule variable now
  substitutes compiler include flags in a separate ``<INCLUDES>`` placeholder
  instead of the main ``<FLAGS>`` placeholder.


code:
CMake 3.5 Release Notes
***********************

.. only:: html

  .. contents::

Changes made since CMake 3.4 include the following.

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

GUI
---

* The :manual:`cmake-gui(1)` gained options to control warnings about
  deprecated functionality.

* The :manual:`cmake-gui(1)` learned an option to set the toolset
  to be used with VS IDE and Xcode generators, much like the
  existing ``-T`` option to :manual:`cmake(1)`.

* The :manual:`cmake-gui(1)` gained a Regular Expression Explorer which
  may be used to create and evaluate regular expressions in real-time.
  The explorer window is available via the ``Tools`` menu.

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

* The ``-Wdev`` and ``-Wno-dev`` :manual:`cmake(1)` options now also enable
  and suppress the deprecated warnings output by default.

* The suppression of developer warnings as errors can now be controlled with
  the new ``-Werror=dev`` and ``-Wno-error=dev`` :manual:`cmake(1)` options.

* The :manual:`cmake(1)` ``-E`` command-line tools ``copy``,
  ``copy_if_different``, ``copy_directory``, and ``make_directory``
  learned to support multiple input files or directories.

Commands
--------

* The :command:`cmake_parse_arguments` command is now implemented natively.
  The :module:`CMakeParseArguments` module remains as an empty placeholder
  for compatibility.

* The :command:`install(DIRECTORY)` command learned to support
  :manual:`generator expressions <cmake-generator-expressions(7)>`
  in the list of directories.

Variables
---------

* The :variable:`CMAKE_ERROR_DEPRECATED` variable can now be set using the
  ``-Werror=deprecated`` and ``-Wno-error=deprecated`` :manual:`cmake(1)`
  options.

* The :variable:`CMAKE_WARN_DEPRECATED` variable can now be set using the
  ``-Wdeprecated`` and ``-Wno-deprecated`` :manual:`cmake(1)` options.

Properties
----------

* The :prop_tgt:`VS_GLOBAL_<variable>` target property is now implemented
  for VS 2010 and above.  Previously it worked only in VS 2008 and below.

Modules
-------

* The :module:`ExternalProject` module learned a new ``GIT_REMOTE_NAME``
  option to control the ``git clone --origin`` value.

* The :module:`FindBoost` module now provides imported targets
  such as ``Boost::boost`` and ``Boost::filesystem``.

* The :module:`FindFLEX` module ``FLEX_TARGET`` macro learned a
  new ``DEFINES_FILE`` option to specify a custom output header
  to be generated.

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

* The :module:`FindGTK2` module, when ``GTK2_USE_IMPORTED_TARGETS`` is
  enabled, now sets ``GTK2_LIBRARIES`` to contain the list of imported
  targets instead of the paths to the libraries.  Moreover it now sets
  a new ``GTK2_TARGETS`` variable containing all the targets imported.

* The :module:`FindOpenMP` module learned to support Clang.

* The :module:`FindOpenSSL` module gained a new
  ``OPENSSL_MSVC_STATIC_RT`` option to search for libraries using
  the MSVC static runtime.

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

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

* A :module:`FindXalanC` module was introduced to find the
  Apache Xalan-C++ XSL transform processing library.

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

Platforms
---------

* Support was added for the ARM Compiler (arm.com) with compiler id ``ARMCC``.

* A new platform file for cross-compiling in the Cray Linux Environment to
  target compute nodes was added.  See
  :ref:`Cross Compiling for the Cray Linux Environment <Cray Cross-Compile>`
  for usage details.

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
  is now aware of features supported by Clang compilers on Windows (MinGW).

* When building for embedded Apple platforms like iOS CMake learned to build and
  install combined targets which contain both a device and a simulator build.
  This behavior can be enabled by setting the :prop_tgt:`IOS_INSTALL_COMBINED`
  target property.

CPack
-----

* The :cpack_gen:`CPack DragNDrop Generator` learned new variable to
  specify AppleScript file run to customize appearance of ``DragNDrop``
  installer folder, including background image setting using supplied
  PNG or multi-resolution TIFF file.
  See the :variable:`CPACK_DMG_DS_STORE_SETUP_SCRIPT` and
  :variable:`CPACK_DMG_BACKGROUND_IMAGE` variables.

* The :cpack_gen:`CPack DEB Generator` learned to set the optional config
  file ``Source`` field using a monolithic or per-component variable.
  See :variable:`CPACK_DEBIAN_PACKAGE_SOURCE`.

* The :cpack_gen:`CPack DEB Generator` learned to set Package, Section
  and Priority control fields per-component.
  See variables :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION` and
  :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY`.

* The :cpack_gen:`CPack DragNDrop Generator` learned to add
  multi-lingual SLAs to a DMG which is presented to the user when they try to
  mount the DMG.  See the :variable:`CPACK_DMG_SLA_LANGUAGES` and
  :variable:`CPACK_DMG_SLA_DIR` variables for details.

* The :cpack_gen:`CPack NSIS Generator` learned new variables to
  add bitmaps to the installer.
  See the :variable:`CPACK_NSIS_MUI_WELCOMEFINISHPAGE_BITMAP`
  and :variable:`CPACK_NSIS_MUI_UNWELCOMEFINISHPAGE_BITMAP` variables.

* The :cpack_gen:`CPack RPM Generator` learned to set Name and Group
  control fields per-component.
  See :variable:`CPACK_RPM_<component>_PACKAGE_NAME`
  and :variable:`CPACK_RPM_<component>_PACKAGE_GROUP`.

Other
-----

* Warnings about deprecated functionality are now enabled by default.
  They may be suppressed with ``-Wno-deprecated`` or by setting the
  :variable:`CMAKE_WARN_DEPRECATED` variable to false.

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

* The :manual:`cmake(1)` ``-E time`` command now properly passes arguments
  with spaces or special characters through to the child process.  This
  may break scripts that worked around the bug with their own extra
  quoting or escaping.

* The :generator:`Xcode` generator was fixed to escape backslashes in
  strings consistently with other generators.  Projects that previously
  worked around the inconsistecy with an extra level of backslashes
  conditioned on the Xcode generator must be updated to remove the
  workaround for CMake 3.5 and greater.

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

* The :generator:`Visual Studio 14 2015` generator learned to map the
  ``/debug:fastlink`` linker flag to the ``.vcxproj`` file property.

* The :module:`FindGTK2` module now configures the ``GTK2::sigc++`` imported
  target to enable c++11 on its dependents when using sigc++ 2.5.1 or higher.

* The precompiled Windows binary provided on ``cmake.org`` is now a
  ``.msi`` package instead of an installer executable.  One may need
  to manually uninstall CMake versions lower than 3.5 before installing
  the new package.


code:
CMake 3.6 Release Notes
***********************

.. only:: html

  .. contents::

Changes made since CMake 3.5 include the following.

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

Generators
----------

* The :generator:`Ninja` generator learned to produce phony targets
  of the form ``sub/dir/all`` to drive the build of a subdirectory.
  This is equivalent to ``cd sub/dir; make all`` with
  :ref:`Makefile Generators`.

* The :generator:`Ninja` generator now includes system header files in build
  dependencies to ensure correct re-builds when system packages are updated.

* The :generator:`Visual Studio 14 2015` generator learned to support the
  Clang/C2 toolsets, e.g. with the ``-T v140_clang_3_7`` option.
  This feature is experimental.

Commands
--------

* The :command:`add_custom_command` and :command:`add_custom_target` commands
  learned how to use the :prop_tgt:`CROSSCOMPILING_EMULATOR` executable
  target property.

* The :command:`install` command learned a new ``EXCLUDE_FROM_ALL`` option
  to leave installation rules out of the default installation.

* The :command:`list` command gained a ``FILTER`` sub-command to filter
  list elements by regular expression.

* The :command:`string(TIMESTAMP)` and :command:`file(TIMESTAMP)`
  commands gained support for the ``%s`` placeholder.  This is
  the number of seconds since the UNIX Epoch.

Variables
---------

* A :variable:`CMAKE_DEPENDS_IN_PROJECT_ONLY` variable was introduced
  to tell :ref:`Makefile Generators` to limit dependency scanning only
  to files in the project source and build trees.

* A new :variable:`CMAKE_HOST_SOLARIS` variable was introduced to
  indicate when CMake is running on an Oracle Solaris host.

* A :variable:`CMAKE_<LANG>_STANDARD_INCLUDE_DIRECTORIES` variable was
  added for use by toolchain files to specify system include directories
  to be appended to all compiler command lines.

* The :variable:`CMAKE_<LANG>_STANDARD_LIBRARIES` variable is now documented.
  It is intended for use by toolchain files to specify system libraries to be
  added to all linker command lines.

* A :variable:`CMAKE_NINJA_OUTPUT_PATH_PREFIX` variable was introduced
  to tell the :generator:`Ninja` generator to configure the generated
  ``build.ninja`` file for use as a ``subninja``.

* A :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` variable was
  added for use by toolchain files to specify platform-specific
  variables that must be propagated by the :command:`try_compile`
  command into test projects.

* A :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable was added
  to optionally tell the :command:`try_compile` command to build
  a static library instead of an executable.  This is useful for
  cross-compiling toolchains that cannot link binaries without
  custom flags or scripts.

Properties
----------

* A :prop_tgt:`DEPLOYMENT_REMOTE_DIRECTORY` target property was introduced
  to tell the :generator:`Visual Studio 9 2008` and
  :generator:`Visual Studio 8 2005` generators to generate the "remote
  directory" for WinCE project deployment and debugger settings.

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

* A :prop_test:`TIMEOUT_AFTER_MATCH` test property was introduced to
  optionally tell CTest to enforce a secondary timeout after matching
  certain output from a test.

* A :prop_tgt:`VS_CONFIGURATION_TYPE` target property was introduced
  to specify a custom project file type for :ref:`Visual Studio Generators`
  supporting VS 2010 and above.

* A :prop_dir:`VS_STARTUP_PROJECT` directory property was introduced
  to specify for :ref:`Visual Studio Generators` the default startup
  project for generated solutions (``.sln`` files).

Modules
-------

* The :module:`CMakePushCheckState` module now pushes/pops/resets the variable
  ``CMAKE_EXTRA_INCLUDE_FILES`` used in :module:`CheckTypeSize`.

* The :module:`ExternalProject` module leared the ``GIT_SHALLOW 1``
  option to perform a shallow clone of a Git repository.

* The :module:`ExternalProject` module learned to initialize Git submodules
  recursively and also to initialize new submodules on updates.  Use the
  ``GIT_SUBMODULES`` option to restrict which submodules are initialized and
  updated.

* The :module:`ExternalProject` module leared the ``DOWNLOAD_NO_EXTRACT 1``
  argument to skip extracting the file that is downloaded (e.g., for
  self-extracting shell installers or ``.msi`` files).

* The :module:`ExternalProject` module now uses ``TLS_VERIFY`` when fetching
  from git repositories.

* The :module:`FindBLAS` and :module:`FindLAPACK` modules learned to
  support `OpenBLAS <http://www.openblas.net>`__.

* The :module:`FindCUDA` module learned to find the ``cublas_device`` library.

* The :module:`FindGTest` module ``gtest_add_tests`` function now causes
  CMake to automatically re-run when test sources change so that they
  can be re-scanned.

* The :module:`FindLTTngUST` module was introduced to find the LTTng-UST
  library.

* The :module:`FindPkgConfig` module learned to optionally create imported
  targets for the libraries it has found.

* The :module:`FindProtobuf` module learned to provide a ``Protobuf_VERSION``
  variable and check the version number requested in a :command:`find_package`
  call.

* The :module:`InstallRequiredSystemLibraries` module learned a new
  ``CMAKE_INSTALL_UCRT_LIBRARIES`` option to enable app-local deployment
  of the Windows Universal CRT libraries with Visual Studio 2015.

Platforms
---------

* The Clang compiler is now supported on CYGWIN.

* Support was added for the Bruce C Compiler with compiler id ``Bruce``.

CTest
-----

* The :command:`ctest_update` command now looks at the
  :variable:`CTEST_GIT_INIT_SUBMODULES` variable to determine whether
  submodules should be updated or not before updating.

* The :command:`ctest_update` command will now synchronize submodules on an
  update. Updates which add submodules or change a submodule's URL will now be
  pulled properly.

CPack
-----

* The :cpack_gen:`CPack DEB Generator` learned how to handle ``$ORIGIN``
  in ``CMAKE_INSTALL_RPATH`` when :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS`
  is used for dependency auto detection.

* The :cpack_gen:`CPack DEB Generator` learned how to generate
  ``DEBIAN/shlibs`` control file when package contains shared libraries.

* The :cpack_gen:`CPack DEB Generator` learned how to generate
  ``DEBIAN/postinst`` and ``DEBIAN/postrm`` files if the package installs
  libraries in ldconfig-controlled locations (e.g. ``/lib/``, ``/usr/lib/``).

* The :cpack_gen:`CPack DEB Generator` learned how to generate dependencies
  between Debian packages if multi-component setup is used and
  :variable:`CPACK_COMPONENT_<compName>_DEPENDS` variables are set.
  For backward compatibility this feature is disabled by default.
  See :variable:`CPACK_DEBIAN_ENABLE_COMPONENT_DEPENDS`.

* The :cpack_gen:`CPack DEB Generator` learned how to set custom package
  file names including how to generate properly-named Debian packages::

    <PackageName>_<VersionNumber>-<DebianRevisionNumber>_<DebianArchitecture>.deb

  For backward compatibility this feature is disabled by default. See
  :variable:`CPACK_DEBIAN_FILE_NAME` and
  :variable:`CPACK_DEBIAN_<COMPONENT>_FILE_NAME`.

* The :cpack_gen:`CPack DEB Generator` learned how to set the package
  release number (``DebianRevisionNumber`` in package file name when
  used in combination with ``DEB-DEFAULT`` value set by
  :variable:`CPACK_DEBIAN_FILE_NAME`).
  See :variable:`CPACK_DEBIAN_PACKAGE_RELEASE`.

* The :cpack_gen:`CPack DEB Generator` learned how to set the package
  architecture per-component.
  See :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE`.

* The :cpack_gen:`CPack DragNDrop Generator` learned a new option to skip the
  ``/Applications`` symlink.
  See the :variable:`CPACK_DMG_DISABLE_APPLICATIONS_SYMLINK` variable.

* The :module:`CPackIFW` module gained a new
  :command:`cpack_ifw_update_repository` command to update a QtIFW-specific
  repository from a remote repository.

* The :cpack_gen:`CPack RPM Generator` learned how to set RPM ``dist`` tag
  as part of RPM ``Release:`` tag when enabled (mandatory on some Linux
  distributions for e.g. on Fedora).
  See :variable:`CPACK_RPM_PACKAGE_RELEASE_DIST`.

* The :cpack_gen:`CPack RPM Generator` learned how to set default values
  for owning user/group and file/directory permissions of package content.
  See :variable:`CPACK_RPM_DEFAULT_USER`, :variable:`CPACK_RPM_DEFAULT_GROUP`,
  :variable:`CPACK_RPM_DEFAULT_FILE_PERMISSIONS`,
  :variable:`CPACK_RPM_DEFAULT_DIR_PERMISSIONS` and their per component
  counterparts.

* The :cpack_gen:`CPack RPM Generator` learned how to set user defined
  package file names, how to specify that rpmbuild should decide on file
  name format as well as handling of multiple rpm packages generated by a
  single user defined spec file.
  See :variable:`CPACK_RPM_PACKAGE_NAME` and
  :variable:`CPACK_RPM_<component>_PACKAGE_NAME`.

* The :cpack_gen:`CPack RPM Generator` learned how to correctly handle symlinks
  that are pointing outside generated packages.

Other
-----

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
  is now aware of features supported by Intel C++ compilers versions 12.1
  through 16.0 on UNIX platforms.

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

* The :module:`CMakeForceCompiler` module and its macros are now deprecated.
  See module documentation for an explanation.

* The :command:`find_library`, :command:`find_path`, and :command:`find_file`
  commands no longer search in installation prefixes derived from the ``PATH``
  environment variable on non-Windows platforms.  This behavior was added in
  CMake 3.3 to support Windows hosts but has proven problematic on UNIX hosts.
  Users that keep some ``<prefix>/bin`` directories in the ``PATH`` just for
  their tools do not necessarily want any supporting ``<prefix>/lib``
  directories searched.  One may set the ``CMAKE_PREFIX_PATH`` environment
  variable with a :ref:`semicolon-separated list <CMake Language Lists>` of prefixes that are
  to be searched.

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

* The :generator:`Visual Studio 7` generator (for VS .NET 2002) has been
  removed.  It had been deprecated since CMake 3.3.

* The :generator:`Visual Studio 6` generator has been removed.
  It had been deprecated since CMake 3.3.

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

* The precompiled OS X binary provided on ``cmake.org`` now requires
  OS X 10.7 or newer.

* On Linux and FreeBSD platforms, when building CMake itself from source and
  not using a system-provided libcurl, OpenSSL is now used by default if it is
  found on the system.  This enables SSL/TLS support for commands supporting
  network communication via ``https``, such as :command:`file(DOWNLOAD)`,
  :command:`file(UPLOAD)`, and :command:`ctest_submit`.

* The :manual:`cmake(1)` ``--build`` command-line tool now rejects multiple
  ``--target`` options with an error instead of silently ignoring all but the
  last one.

* :prop_tgt:`AUTOMOC` now diagnoses name collisions when multiple source
  files in different directories use ``#include <moc_foo.cpp>`` with the
  same name (because the generated ``moc_foo.cpp`` files would collide).

* The :module:`FindBISON` module ``BISON_TARGET`` macro now supports
  special characters by passing the ``VERBATIM`` option to internal
  :command:`add_custom_command` calls.  This may break clients that
  added escaping manually to work around the bug.

* The :module:`FindFLEX` module ``FLEX_TARGET`` macro now supports
  special characters by passing the ``VERBATIM`` option to internal
  :command:`add_custom_command` calls.  This may break clients that
  added escaping manually to work around the bug.

* The :module:`FindProtobuf` module input and output variables were all renamed
  from ``PROTOBUF_`` to ``Protobuf_`` for consistency with other find modules.
  Input variables of the old case will be honored if provided, and output
  variables of the old case are always provided.

* The :cpack_gen:`CPack RPM Generator` now supports upper cased component
  names in per component CPackRPM specific variables.
  E.g. component named ``foo`` now expects component specific
  variable to be ``CPACK_RPM_FOO_PACKAGE_NAME`` while before
  it expected ``CPACK_RPM_foo_PACKAGE_NAME``.
  Upper cased component name part in variables is compatible
  with convention used for other CPack variables.
  For back compatibility old format of variables is still valid
  and preferred if both versions of variable are set, but the
  preferred future use is upper cased component names in variables.
  New variables that will be added to CPackRPM in later versions
  will only support upper cased component variable format.

* The CPack NSIS generator's configuration file template was fixed to
  quote the path to the uninstaller tool used by the
  :variable:`CPACK_NSIS_ENABLE_UNINSTALL_BEFORE_INSTALL` option.
  This avoids depending on an insecure Windows feature to run an
  uninstaller tool with a space in the path.


code:
CMake 3.7 Release Notes
***********************

.. only:: html

  .. contents::

Changes made since CMake 3.6 include the following.

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

Platforms
---------

* CMake now supports :ref:`Cross Compiling for Android` with simple
  toolchain files.

* The Clang compiler is now supported on AIX.

Generators
----------

* The :generator:`Ninja` generator learned to conditionally support
  Fortran when using a ``ninja`` tool that has the necessary features.
  See generator documentation for details.

* The :generator:`Ninja` generator learned to produce phony targets
  of the form ``sub/dir/{test,install,package}`` to drive the build
  of a subdirectory installation, test or packaging target.
  This is equivalent to ``cd sub/dir; make {test,install,package}``
  with :ref:`Makefile Generators`.

* The :generator:`Visual Studio 15 2017` generator was added.  This is
  experimental and based on "Visual Studio 2017 RC" because this version
  of VS has not been released.

* :ref:`Visual Studio Generators` for VS 2010 and above learned to
  place ``.natvis`` source files into VS project files properly.

* The :generator:`Xcode` generator's rudimentary Swift language support
  learned to honor a new :variable:`CMAKE_Swift_LANGUAGE_VERSION` variable
  to tell Xcode what version of Swift is used by the source.

* The :generator:`CodeLite` generator gained a new
  :variable:`CMAKE_CODELITE_USE_TARGETS` option
  to change project creation from projects to targets.

Commands
--------

* The :command:`add_custom_command` command gained a new ``DEPFILE``
  option that works with the :generator:`Ninja` generator to provide
  implicit dependency information to the build tool.

* The :command:`cmake_parse_arguments` command gained a new ``PARSE_ARGV``
  mode to read arguments directly from ``ARGC`` and ``ARGV#``
  variables inside a :command:`function` body.

* The :command:`export` command gained an ``ANDROID_MK`` option
  to generate ``Android.mk`` files referencing CMake-built
  libraries as prebuilts for the Android NDK build system.

* The :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands gained
  ``HTTPHEADER <HTTP-header>`` and ``USERPWD <username>:<password>`` options.

* The :command:`find_library` and :command:`find_package` commands learned
  to search in ``lib32/`` directories when the build targets a 32-bit
  architecture.  See the :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` global
  property.

* The :command:`find_package` command gained the possibility of
  sorting compatible libraries by ``NAME`` or by ``NATURAL`` sorting by
  setting the two new variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER`
  and :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`.

* The :command:`if` command gained new boolean comparison operations
  ``LESS_EQUAL``, ``GREATER_EQUAL``, ``STRLESS_EQUAL``, ``STRGREATER_EQUAL``,
  ``VERSION_LESS_EQUAL``, and ``VERSION_GREATER_EQUAL``.

* The :command:`install` command gained an ``EXPORT_ANDROID_MK``
  subcommand to install ``Android.mk`` files referencing installed
  libraries as prebuilts for the Android NDK build system.

* The :command:`string(TIMESTAMP)` and :command:`file(TIMESTAMP)`
  commands gained support for the ``%a`` and ``%b`` placeholders.
  These are the abbreviated weekday and month names.

* The :command:`try_compile` command source file signature now honors
  configuration-specific flags (e.g. :variable:`CMAKE_<LANG>_FLAGS_DEBUG`)
  in the generated test project.  Previously only the default such flags
  for the current toolchain were used.  See policy :policy:`CMP0066`.

Variables
---------

* Variable :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` was added to control
  the sorting mode of the :command:`find_package` command.

* Variable :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION` was added to control
  the sorting direction the :command:`find_package` command.

* :variable:`Toolchain files <CMAKE_TOOLCHAIN_FILE>` may now set a
  :variable:`CMAKE_<LANG>_FLAGS_INIT` variable to initialize the
  :variable:`CMAKE_<LANG>_FLAGS` cache entry the first time a language is
  enabled in a build tree.

* :variable:`Toolchain files <CMAKE_TOOLCHAIN_FILE>` may now set
  :variable:`CMAKE_EXE_LINKER_FLAGS_INIT`,
  :variable:`CMAKE_SHARED_LINKER_FLAGS_INIT`, and
  :variable:`CMAKE_MODULE_LINKER_FLAGS_INIT` variables to initialize the
  :variable:`CMAKE_EXE_LINKER_FLAGS`,
  :variable:`CMAKE_SHARED_LINKER_FLAGS`, and
  :variable:`CMAKE_MODULE_LINKER_FLAGS` cache entries the first time
  a language is enabled in a build tree.

Properties
----------

* On Apple platforms the :prop_tgt:`BUNDLE_EXTENSION` target property
  now also applies to Frameworks and App Bundles.

* A :prop_dir:`BINARY_DIR` directory property was added to get the
  absolute path to the binary directory corresponding to the source
  directory on which the property is read.

* A :prop_dir:`BUILDSYSTEM_TARGETS` directory property was added to
  get the list of logical buildsystem target names added by the
  project in a directory.

* A :prop_tgt:`LINK_WHAT_YOU_USE` target property and supporting
  :variable:`CMAKE_LINK_WHAT_YOU_USE` variable were introduced
  to detect (on UNIX) shared libraries that are linked but not
  needed by running ``ldd -r -u``.

* A :prop_dir:`SOURCE_DIR` directory property was added to get the
  absolute path to the source directory associated with a directory.

* A :prop_dir:`SUBDIRECTORIES` directory property was added to
  get the list of subdirectories added by a project in a directory.

* A :prop_tgt:`VS_SDK_REFERENCES` target property was added to tell
  :ref:`Visual Studio Generators` to reference the named SDKs.

* A :prop_sf:`VS_TOOL_OVERRIDE` source file property was created to tell
  :ref:`Visual Studio Generators` what tool to use for a source file.

* The :prop_tgt:`WINDOWS_EXPORT_ALL_SYMBOLS` target property now applies
  to executable targets with the :prop_tgt:`ENABLE_EXPORTS` property set.

* A :prop_sf:`XCODE_FILE_ATTRIBUTES` source file property was
  added to tell the :generator:`Xcode` generator to generate
  custom content in the Xcode project attributes for the file.

Modules
-------

* An :module:`AndroidTestUtilities` module was added to manage transfer
  of test data to an Android device.

* The :module:`CheckFortranSourceCompiles` module macro
  ``CHECK_Fortran_SOURCE_COMPILES`` gained a ``SRC_EXT`` option
  to specify a custom test Fortran source file extension.

* The :module:`ExternalProject` module gained ``HTTP_USERNAME`` and
  ``HTTP_PASSWORD`` options to set http download credentials.

* The :module:`ExternalProject` module gained a ``HTTP_HEADER``
  option to add http download headers.

* The :module:`FindBISON` module ``BISON_TARGET`` macro learned a new
  ``REPORT_FILE`` option to specify the bison ``--report-file=`` option.

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

* A :module:`FindICU` module was introduced to find the International
  Components for Unicode (ICU) libraries and programs.

* The :module:`FindMatlab` module learned to find the SIMULINK and MAT
  components.

* The :module:`FindMatlab` module :command:`matlab_add_mex` command learned
  to add executables and modules.

* The :module:`FindMatlab` module :command:`matlab_add_unit_test` command
  learned to support inline Matlab test code.

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

* The :module:`FindOpenMP` module learned to detect the OpenMP
  version (specification date) from the compiler.

* A :module:`FindVulkan` module was added.

* The :module:`GenerateExportHeader` module learned a new
  ``CUSTOM_CONTENT_FROM_VARIABLE`` option to specify a variable
  containing custom content for inclusion in the generated header.

* The :module:`GNUInstallDirs` module gained a new
  :command:`GNUInstallDirs_get_absolute_install_dir` command.

* The :module:`UseJava` module gained APIs to "export" jar targets
  for use by external CMake projects.  See the ``install_jar_exports``
  and ``export_jars`` functions.

CTest
-----

* CTest now supports test fixtures through the new :prop_test:`FIXTURES_SETUP`,
  :prop_test:`FIXTURES_CLEANUP` and :prop_test:`FIXTURES_REQUIRED` test
  properties. When using regular expressions or ``--rerun-failed`` to limit
  the tests to be run, a fixture's setup and cleanup tests will automatically
  be added to the execution set if any test requires that fixture.

* The :command:`ctest_configure`, :command:`ctest_build`,
  :command:`ctest_test`, :command:`ctest_coverage`, and :command:`ctest_upload`
  commands gained a new ``CAPTURE_CMAKE_ERROR`` option to capture any errors
  that occur as the commands run into a variable and avoid affecting the return
  code of the :manual:`ctest(1)` process.

CPack
-----

* CPack gained a :cpack_gen:`CPack productbuild Generator` on OS X.

* CPack gained a new :variable:`CPACK_PACKAGE_CHECKSUM` variable to
  enable generation of a checksum file for each package file.

* The :cpack_gen:`CPack DEB Generator` learned to support long file names
  when archive format is set to GNU tar.
  See :variable:`CPACK_DEBIAN_ARCHIVE_TYPE`

* The :module:`CPackIFW` module gained a new
  :command:`cpack_ifw_add_package_resources` command to include additional
  resources in the installer binary.

* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and
  :command:`cpack_ifw_configure_component_group` commands gained a new
  ``USER_INTERFACES`` option to add a list of additional pages to the IFW
  installer.

* The :cpack_gen:`CPack RPM Generator` learned to generate debuginfo
  packages on demand. See :variable:`CPACK_RPM_DEBUGINFO_PACKAGE`
  and its per component version.

* The :cpack_gen:`CPack RPM Generator` learned to generate source rpm
  (SRPM) packages on demand. See :variable:`CPACK_RPM_PACKAGE_SOURCES`,
  :variable:`CPACK_RPM_SOURCE_PKG_BUILD_PARAMS` and
  :variable:`CPACK_RPM_SOURCE_PKG_PACKAGING_INSTALL_PREFIX`.

* The :cpack_gen:`CPack NSIS Generator` now supports
  :variable:`CPACK_NSIS_<compName>_INSTALL_DIRECTORY`.
  This can be used to set component specific installation directories.

* The :cpack_gen:`CPack WIX Generator` now supports
  :variable:`CPACK_WIX_SKIP_PROGRAM_FOLDER` to allow specification
  of a custom absolute installation prefix outside
  of the ProgramFiles folders.

* The :cpack_gen:`CPack WIX Generator` now supports
  :variable:`CPACK_COMPONENT_<compName>_DISABLED`.
  This can be used to deselect a component from being installed by default.

* The :cpack_gen:`CPack WIX Generator` now supports
  :variable:`CPACK_WIX_PATCH_FILE` fragments for Feature elements.

* The :cpack_gen:`CPack WIX Generator` now supports
  :variable:`CPACK_WIX_ROOT_FEATURE_TITLE` and
  :variable:`CPACK_WIX_ROOT_FEATURE_DESCRIPTION` to allow the specification
  of a custom title and description for the root feature element.

Other
-----

* :manual:`cmake(1)` gained a ``-E capabilities`` option to provide a
  machine-readable (JSON) description of the capabilities of the
  cmake tool (available generators, etc.).

* A new :manual:`cmake-server(7)` mode was added to provide semantic
  information about a CMake-generated buildsystem to clients through
  a JSON protocol.  Currently all protocols are experimental and subject
  to change.

* The :manual:`cmake(1)` command learned a ``--trace-source=<file>`` option.

* :manual:`ccmake(1)` learned to support vim-like navigation bindings.

* :manual:`cmake-gui(1)` gained a button to open the generated project file
  for :ref:`Visual Studio Generators` and the :generator:`Xcode` generator.

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

* We no longer provide Linux i386 binaries for download from ``cmake.org``
  for new versions of CMake.

* Vim support files ``cmake-indent.vim``, ``cmake-syntax.vim``, and
  ``cmake-help.vim`` have been removed in favor of the files now provided
  from the `vim-cmake-syntax`_ project.

* Support for building CMake itself with some compilers was dropped:

  * Visual Studio 7.1 and 2005 -- superseded by VS 2008 and above
  * MinGW.org mingw32 -- superseded by MSYS2 mingw32 and mingw64

  CMake still supports generating build systems for other projects using
  these compilers.

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

* The Fortran dependency scanner learned to support the syntax of
  `Fortran Submodules`_.

* Vim support files ``indent/cmake.vim`` and ``syntax/cmake.vim``
  from the `vim-cmake-syntax`_ project are now distributed with CMake.

.. _`Fortran Submodules`: https://fortranwiki.org/fortran/show/Submodules
.. _`vim-cmake-syntax`: https://github.com/pboettch/vim-cmake-syntax