code:
XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE
------------------------------------------

.. versionadded:: 3.23

Property value for ``GPU Frame Capture`` in the Options section of
the generated Xcode scheme. Example values are `Metal` and
`Disabled`.

This property is initialized by the value of the variable
:variable:`CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE`
if it is set when a target is created.

Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property
documentation to see all Xcode schema related properties.


code:
XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION
-----------------------------------------

.. versionadded:: 3.25

Property value for ``Metal: Shader Validation`` in the Options section of
the generated Xcode scheme.

This property is initialized by the value of the variable
:variable:`CMAKE_XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION`
if it is set when a target is created.

Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property
documentation to see all Xcode schema related properties.

repo_name: lazytadpole/codenamesilverfish

license: mit


code:
XCODE_SCHEME_ENVIRONMENT
------------------------

.. versionadded:: 3.13

Specify environment variables that should be added to the Arguments
section of the generated Xcode scheme.

If set to a list of environment variables and values of the form
``MYVAR=value`` those environment variables will be added to the
scheme.

Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property
documentation to see all Xcode schema related properties.


code:
XCODE_SCHEME_EXECUTABLE
-----------------------

.. versionadded:: 3.13

Specify path to executable in the Info section of the generated
Xcode scheme. If not set the schema generator will select the
current target if it is actually executable.

Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property
documentation to see all Xcode schema related properties.


code:
XCODE_SCHEME_GUARD_MALLOC
------------------------------

.. versionadded:: 3.13

Whether to enable ``Guard Malloc``
in the Diagnostics section of the generated Xcode scheme.

This property is initialized by the value of the variable
:variable:`CMAKE_XCODE_SCHEME_GUARD_MALLOC` if it is set
when a target is created.

Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property
documentation to see all Xcode schema related properties.


code:
XCODE_SCHEME_LAUNCH_CONFIGURATION
---------------------------------

.. versionadded:: 3.25

Set the build configuration to run the target.

This property is initialized by the value of the variable
:variable:`CMAKE_XCODE_SCHEME_LAUNCH_CONFIGURATION`
if it is set when a target is created.

Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property
documentation to see all Xcode schema related properties.


code:
XCODE_SCHEME_LAUNCH_MODE
------------------------

.. versionadded:: 3.25

Property value for ``Launch`` in the Info section of the generated Xcode
scheme.

Possible values are:

``AUTO``
  Launch automatically. This is the default.

``WAIT``
  Wait for the executable to be launched.

This property is initialized by the value of the variable
:variable:`CMAKE_XCODE_SCHEME_LAUNCH_MODE` if it is set when a target is
created.

Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property
documentation to see all Xcode schema related properties.


code:
XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP
-------------------------------------

.. versionadded:: 3.13

Whether to enable the ``Main Thread Checker`` option
``Pause on issues``
in the Diagnostics section of the generated Xcode scheme.

This property is initialized by the value of the variable
:variable:`CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP` if it is set
when a target is created.

Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property
documentation to see all Xcode schema related properties.


code:
XCODE_SCHEME_MALLOC_GUARD_EDGES
-------------------------------

.. versionadded:: 3.13

Whether to enable ``Malloc Guard Edges``
in the Diagnostics section of the generated Xcode scheme.

This property is initialized by the value of the variable
:variable:`CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES` if it is set
when a target is created.

Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property
documentation to see all Xcode schema related properties.


code:
XCODE_SCHEME_MALLOC_SCRIBBLE
------------------------------

.. versionadded:: 3.13

Whether to enable ``Malloc Scribble``
in the Diagnostics section of the generated Xcode scheme.

This property is initialized by the value of the variable
:variable:`CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE` if it is set
when a target is created.

Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property
documentation to see all Xcode schema related properties.


code:
XCODE_SCHEME_MALLOC_STACK
-------------------------

.. versionadded:: 3.13

Whether to enable ``Malloc Stack`` in the Diagnostics
section of the generated Xcode scheme.

This property is initialized by the value of the variable
:variable:`CMAKE_XCODE_SCHEME_MALLOC_STACK` if it is set
when a target is created.

Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property
documentation to see all Xcode schema related properties.


code:
XCODE_SCHEME_THREAD_SANITIZER
-----------------------------

.. versionadded:: 3.13

Whether to enable ``Thread Sanitizer`` in the Diagnostics
section of the generated Xcode scheme.

This property is initialized by the value of the variable
:variable:`CMAKE_XCODE_SCHEME_THREAD_SANITIZER` if it is set
when a target is created.

Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property
documentation to see all Xcode schema related properties.


code:
XCODE_SCHEME_THREAD_SANITIZER_STOP
----------------------------------

.. versionadded:: 3.13

Whether to enable ``Thread Sanitizer - Pause on issues``
in the Diagnostics section of the generated Xcode scheme.

This property is initialized by the value of the variable
:variable:`CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP` if it is set
when a target is created.

Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property
documentation to see all Xcode schema related properties.


code:
XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER
------------------------------------------

.. versionadded:: 3.13

Whether to enable ``Undefined Behavior Sanitizer``
in the Diagnostics section of the generated Xcode scheme.

This property is initialized by the value of the variable
:variable:`CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER`
if it is set when a target is created.

Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property
documentation to see all Xcode schema related properties.


code:
XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP
-----------------------------------------------

.. versionadded:: 3.13

Whether to enable ``Undefined Behavior Sanitizer`` option
``Pause on issues``
in the Diagnostics section of the generated Xcode scheme.

This property is initialized by the value of the variable
:variable:`CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP`
if it is set when a target is created.

Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property
documentation to see all Xcode schema related properties.


code:
XCODE_SCHEME_WORKING_DIRECTORY
------------------------------

.. versionadded:: 3.17

Specify the ``Working Directory`` of the *Run* and *Profile*
actions in the generated Xcode scheme. In case the value contains
generator expressions those are evaluated.

This property is initialized by the value of the variable
:variable:`CMAKE_XCODE_SCHEME_WORKING_DIRECTORY` if it is set
when a target is created.

Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property
documentation to see all Xcode schema related properties.


code:
XCODE_SCHEME_ZOMBIE_OBJECTS
------------------------------

.. versionadded:: 3.13

Whether to enable ``Zombie Objects``
in the Diagnostics section of the generated Xcode scheme.

This property is initialized by the value of the variable
:variable:`CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS` if it is set
when a target is created.

Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property
documentation to see all Xcode schema related properties.


code:
XCODE_XCCONFIG
--------------

.. versionadded:: 3.24

If set, the :generator:`Xcode` generator will register the specified
file as a target-level XCConfig file. For global XCConfig files see
the :variable:`CMAKE_XCODE_XCCONFIG` variable.

This feature is intended to ease migration from native Xcode projects
to CMake projects.

Contents of ``XCODE_XCCONFIG`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.


code:
XCTEST
------

.. versionadded:: 3.3

This target is a XCTest CFBundle on the Mac.

This property will usually get set via the :command:`xctest_add_bundle`
macro in :module:`FindXCTest` module.

If a module library target has this property set to true it will be
built as a CFBundle when built on the Mac.  It will have the directory
structure required for a CFBundle.

This property depends on :prop_tgt:`BUNDLE` to be effective.


code:
CMake 3.0 Release Notes
***********************

.. only:: html

  .. contents::

Changes made since CMake 2.8.12 include the following.

Documentation Changes
=====================

* The CMake documentation has been converted to reStructuredText and
  now transforms via Sphinx (`<https://www.sphinx-doc.org>`__) into man and
  html pages.  This allows the documentation to be properly indexed
  and to contain cross-references.

  Conversion from the old internal documentation format was done by
  an automatic process so some documents may still contain artifacts.
  They will be updated incrementally over time.

  A basic reStructuredText processor has been implemented to support
  ``cmake --help-command`` and similar command-line options.

* New manuals were added:

  - :manual:`cmake-buildsystem(7)`
  - :manual:`cmake-commands(7)`, replacing ``cmakecommands(1)``
    and ``cmakecompat(1)``
  - :manual:`cmake-developer(7)`
  - :manual:`cmake-generator-expressions(7)`
  - :manual:`cmake-generators(7)`
  - :manual:`cmake-language(7)`
  - :manual:`cmake-modules(7)`, replacing ``cmakemodules(1)``
  - :manual:`cmake-packages(7)`
  - :manual:`cmake-policies(7)`, replacing ``cmakepolicies(1)``
  - :manual:`cmake-properties(7)`, replacing ``cmakeprops(1)``
  - :manual:`cmake-qt(7)`
  - :manual:`cmake-toolchains(7)`
  - :manual:`cmake-variables(7)`, replacing ``cmakevars(1)``

* Release notes for CMake 3.0.0 and above will now be included with
  the html documentation.

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

Syntax
------

* The CMake language has been extended with
  :ref:`Bracket Argument` and  :ref:`Bracket Comment`
  syntax inspired by Lua long brackets::

    set(x [===[bracket argument]===] #[[bracket comment]])

  Content between equal-length open- and close-brackets is taken
  literally with no variable replacements.

  .. warning::
    This syntax change could not be made in a fully compatible
    way.  No policy is possible because syntax parsing occurs before
    any chance to set a policy.  Existing code using an unquoted
    argument that starts with an open bracket will be interpreted
    differently without any diagnostic.  Fortunately the syntax is
    obscure enough that this problem is unlikely in practice.

Generators
----------

* A new :generator:`CodeLite` extra generator is available
  for use with the Makefile or Ninja generators.

* A new :generator:`Kate` extra generator is available
  for use with the Makefile or Ninja generators.

* The :generator:`Ninja` generator learned to use ``ninja`` job pools
  when specified by a new :prop_gbl:`JOB_POOLS` global property.

Commands
--------

* The :command:`add_library` command learned a new ``INTERFACE``
  library type.  Interface libraries have no build rules but may
  have properties defining
  :manual:`usage requirements <cmake-buildsystem(7)>`
  and may be installed, exported, and imported.  This is useful to
  create header-only libraries that have concrete link dependencies
  on other libraries.

* The :command:`export()` command learned a new ``EXPORT`` mode that
  retrieves the list of targets to export from an export set configured
  by the :command:`install(TARGETS)` command ``EXPORT`` option.  This
  makes it easy to export from the build tree the same targets that
  are exported from the install tree.

* The :command:`export` command learned to work with multiple dependent
  export sets, thus allowing multiple packages to be built and exported
  from a single tree.  The feature requires CMake to wait until the
  generation step to write the output file.  This means one should not
  :command:`include` the generated targets file later during project
  configuration because it will not be available.
  Use :ref:`Alias Targets` instead.  See policy :policy:`CMP0024`.

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

* The :command:`project` command learned to set some version variables
  to values specified by the new ``VERSION`` option or to empty strings.
  See policy :policy:`CMP0048`.

* The :command:`string` command learned a new ``CONCAT`` mode.
  It is particularly useful in combination with the new
  :ref:`Bracket Argument` syntax.

* The :command:`unset` command learned a ``PARENT_SCOPE`` option
  matching that of the :command:`set` command.

* The :command:`include_external_msproject` command learned
  to handle non-C++ projects like ``.vbproj`` or ``.csproj``.

* The :command:`ctest_update` command learned to update work trees
  managed by the Perforce (p4) version control tool.

* The :command:`message` command learned a ``DEPRECATION`` mode. Such
  messages are not issued by default, but may be issued as a warning if
  :variable:`CMAKE_WARN_DEPRECATED` is enabled, or as an error if
  :variable:`CMAKE_ERROR_DEPRECATED` is enabled.

* The :command:`target_link_libraries` command now allows repeated use of
  the ``LINK_PUBLIC`` and ``LINK_PRIVATE`` keywords.

Variables
---------

* Variable :variable:`CMAKE_FIND_NO_INSTALL_PREFIX` has been
  introduced to tell CMake not to add the value of
  :variable:`CMAKE_INSTALL_PREFIX` to the
  :variable:`CMAKE_SYSTEM_PREFIX_PATH` variable by default.
  This is useful when building a project that installs some
  of its own dependencies to avoid finding files it is about
  to replace.

* Variable :variable:`CMAKE_STAGING_PREFIX` was introduced for use
  when cross-compiling to specify an installation prefix on the
  host system that differs from a :variable:`CMAKE_INSTALL_PREFIX`
  value meant for the target system.

* Variable :variable:`CMAKE_SYSROOT` was introduced to specify the
  toolchain SDK installation prefix, typically for cross-compiling.
  This is used to pass a ``--sysroot`` option to the compiler and
  as a prefix searched by ``find_*`` commands.

* Variable :variable:`CMAKE_<LANG>_COMPILER_TARGET` was introduced
  for use when cross-compiling to specify the target platform in the
  :ref:`toolchain file <Cross Compiling Toolchain>` specified by the
  :variable:`CMAKE_TOOLCHAIN_FILE` variable.
  This is used to pass an option such as ``--target=<triple>`` to some
  cross-compiling compiler drivers.

* Variable :variable:`CMAKE_MAP_IMPORTED_CONFIG_<CONFIG>` has been
  introduced to optionally initialize the
  :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` target property.

Properties
----------

* The :prop_dir:`ADDITIONAL_MAKE_CLEAN_FILES` directory property
  learned to support
  :manual:`generator expressions <cmake-generator-expressions(7)>`.

* A new directory property :prop_dir:`CMAKE_CONFIGURE_DEPENDS`
  was introduced to allow projects to specify additional
  files on which the configuration process depends.  CMake will
  re-run at build time when one of these files is modified.
  Previously this was only possible to achieve by specifying
  such files as the input to a :command:`configure_file` command.

* A new :ref:`Qt AUTORCC` feature replaces the need to
  invoke ``qt4_add_resources()`` by allowing ``.qrc`` files to
  be listed as target sources.

* A new :ref:`Qt AUTOUIC` feature replaces the need to
  invoke ``qt4_wrap_ui()``.

* Test properties learned to support
  :manual:`generator expressions <cmake-generator-expressions(7)>`.
  This is useful to specify per-configuration values for test
  properties like :prop_test:`REQUIRED_FILES` and
  :prop_test:`WORKING_DIRECTORY`.

* A new :prop_test:`SKIP_RETURN_CODE` test property was introduced
  to tell :manual:`ctest(1)` to treat a particular test return code as
  if the test were not run.  This is useful for test drivers to report
  that certain test requirements were not available.

* New types of :ref:`Compatible Interface Properties` were introduced,
  namely the :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MAX` and
  :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MIN` for calculating numeric
  maximum and minimum values respectively.

Modules
-------

* The :module:`CheckTypeSize` module ``check_type_size`` macro and
  the :module:`CheckStructHasMember` module ``check_struct_has_member``
  macro learned a new ``LANGUAGE`` option to optionally check C++ types.

* The :module:`ExternalData` module learned to work with no
  URL templates if a local store is available.

* The :module:`ExternalProject` function ``ExternalProject_Add``
  learned a new ``GIT_SUBMODULES`` option to specify a subset
  of available submodules to checkout.

* A new :module:`FindBacktrace` module has been added to support
  :command:`find_package(Backtrace)` calls.

* A new :module:`FindLua` module has been added to support
  :command:`find_package(Lua)` calls.

* The :module:`FindBoost` module learned a new ``Boost_NAMESPACE``
  option to change the ``boost`` prefix on library names.

* The :module:`FindBoost` module learned to control search
  for libraries with the ``g`` tag (for MS debug runtime) with
  a new ``Boost_USE_DEBUG_RUNTIME`` option.  It is ``ON`` by
  default to preserve existing behavior.

* The :module:`FindJava` and :module:`FindJNI` modules learned
  to use a ``JAVA_HOME`` CMake variable or environment variable,
  and then try ``/usr/libexec/java_home`` on OS X.

* The :module:`UseJava` module ``add_jar`` function learned a new
  ``MANIFEST`` option to pass the ``-m`` option to ``jar``.

* A new :module:`CMakeFindDependencyMacro` module was introduced with
  a ``find_dependency`` macro to find transitive dependencies in
  a :manual:`package configuration file <cmake-packages(7)>`.  Such
  dependencies are omitted by the listing of the :module:`FeatureSummary`
  module.

* The :module:`FindQt4` module learned to create :ref:`Imported Targets`
  for Qt executables.  This helps disambiguate when using multiple
  :manual:`Qt versions <cmake-qt(7)>` in the same buildsystem.

* The :module:`FindRuby` module learned to search for Ruby 2.0 and 2.1.

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

* New ``$<PLATFORM_ID>`` and ``$<PLATFORM_ID:...>``
  :manual:`generator expressions <cmake-generator-expressions(7)>`
  have been added.

* The ``$<CONFIG>``
  :manual:`generator expression <cmake-generator-expressions(7)>` now has
  a variant which takes no argument.  This is equivalent to the
  ``$<CONFIGURATION>`` expression.

* New ``$<UPPER_CASE:...>`` and ``$<LOWER_CASE:...>``
  :manual:`generator expressions <cmake-generator-expressions(7)>`
  generator expressions have been added.

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

Other
-----

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

* The :manual:`ccmake(1)` dialog learned to honor the
  :prop_cache:`STRINGS` cache entry property to cycle through
  the enumerated list of possible values.

* The :manual:`cmake-gui(1)` dialog learned to remember window
  settings between sessions.

* The :manual:`cmake-gui(1)` dialog learned to remember the type
  of a cache entry for completion in the ``Add Entry`` dialog.

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

* Directories named in the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
  target property of imported targets linked conditionally by a
  :manual:`generator expression <cmake-generator-expressions(7)>`
  were not checked for existence.  Now they are checked.
  See policy :policy:`CMP0027`.

* Build target names must now match a validity pattern and may no longer
  conflict with CMake-defined targets.  See policy :policy:`CMP0037`.

* Build targets that specify themselves as a link dependency were
  silently accepted but are now diagnosed.  See :policy:`CMP0038`.

* The :command:`target_link_libraries` command used to silently ignore
  calls specifying as their first argument build targets created by
  :command:`add_custom_target` but now diagnoses this mistake.
  See policy :policy:`CMP0039`.

* The :command:`add_custom_command` command used to silently ignore
  calls specifying the ``TARGET`` option with a non-existent target
  but now diagnoses this mistake.  See policy :policy:`CMP0040`.

* Relative paths in the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
  target property used to be silently accepted if they contained a
  :manual:`generator expression <cmake-generator-expressions(7)>`
  but are now rejected.  See policy :policy:`CMP0041`.

* The :command:`get_target_property` command learned to reject calls
  specifying a non-existent target.  See policy :policy:`CMP0045`.

* The :command:`add_dependencies` command learned to reject calls
  specifying a dependency on a non-existent target.
  See policy :policy:`CMP0046`.

* Link dependency analysis learned to assume names containing ``::``
  refer to :ref:`Alias Targets` or :ref:`Imported Targets`.  It will
  now produce an error if such a linked target is missing.  Previously
  in this case CMake generated a link line that failed at build time.
  See policy :policy:`CMP0028`.

* When the :command:`project` or :command:`enable_language` commands
  initialize support for a language, it is now an error if the full
  path to the compiler cannot be found and stored in the corresponding
  :variable:`CMAKE_<LANG>_COMPILER` variable.  This produces nicer error
  messages up front and stops processing when no working compiler
  is known to be available.

* Target sources specified with the :command:`add_library` or
  :command:`add_executable` command learned to reject items which
  require an undocumented extra layer of variable expansion.
  See policy :policy:`CMP0049`.

* Use of :command:`add_custom_command` undocumented ``SOURCE``
  signatures now results in an error.  See policy :policy:`CMP0050`.

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

* Compatibility options supporting code written for CMake versions
  prior to 2.4 have been removed.

* Several long-outdated commands that should no longer be called
  have been disallowed in new code by policies:

  - Policy :policy:`CMP0029` disallows :command:`subdir_depends`
  - Policy :policy:`CMP0030` disallows :command:`use_mangled_mesa`
  - Policy :policy:`CMP0031` disallows :command:`load_command`
  - Policy :policy:`CMP0032` disallows :command:`output_required_files`
  - Policy :policy:`CMP0033` disallows :command:`export_library_dependencies`
  - Policy :policy:`CMP0034` disallows :command:`utility_source`
  - Policy :policy:`CMP0035` disallows :command:`variable_requires`
  - Policy :policy:`CMP0036` disallows :command:`build_name`

* The :manual:`cmake(1)` ``-i`` wizard mode has been removed.
  Instead use an interactive dialog such as :manual:`ccmake(1)`
  or use the ``-D`` option to set cache values from the command line.

* The builtin documentation formatters that supported command-line
  options such as ``--help-man`` and ``--help-html`` have been removed
  in favor of the above-mentioned new documentation system.  These and
  other command-line options that used to generate man- and html-
  formatted pages no longer work.  The :manual:`cmake(1)`
  ``--help-custom-modules`` option now produces a warning at runtime
  and generates a minimal document that reports the limitation.

* The :prop_dir:`COMPILE_DEFINITIONS_<CONFIG>` directory properties and the
  :prop_tgt:`COMPILE_DEFINITIONS_<CONFIG>` target properties have been
  deprecated.  Instead set the corresponding :prop_dir:`COMPILE_DEFINITIONS`
  directory property or :prop_tgt:`COMPILE_DEFINITIONS` target property and
  use :manual:`generator expressions <cmake-generator-expressions(7)>` like
  ``$<CONFIG:...>`` to specify per-configuration definitions.
  See policy :policy:`CMP0043`.

* The :prop_tgt:`LOCATION` target property should no longer be read from
  non-IMPORTED targets.  It does not make sense in multi-configuration
  generators since the build configuration is not known while configuring
  the project.  It has been superseded by the ``$<TARGET_FILE>`` generator
  expression.  See policy :policy:`CMP0026`.

* The :prop_tgt:`COMPILE_FLAGS` target property is now documented
  as deprecated, though no warning is issued.  Use the
  :prop_tgt:`COMPILE_OPTIONS` target property or the
  :command:`target_compile_options` command instead.

* The :module:`GenerateExportHeader` module ``add_compiler_export_flags``
  function is now deprecated.  It has been superseded by the
  :prop_tgt:`<LANG>_VISIBILITY_PRESET` and
  :prop_tgt:`VISIBILITY_INLINES_HIDDEN` target properties.

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

* The version scheme was changed to use only two components for
  the feature level instead of three.  The third component will
  now be used for bug-fix releases or the date of development versions.
  See the :variable:`CMAKE_VERSION` variable documentation for details.

* The default install locations of CMake itself on Windows and
  OS X no longer contain the CMake version number.  This allows
  for easy replacement without re-generating local build trees
  manually.

* Generators for Visual Studio 10 (2010) and later were renamed to
  include the product year like generators for older VS versions:

  - ``Visual Studio 10`` -> :generator:`Visual Studio 10 2010`
  - ``Visual Studio 11`` -> :generator:`Visual Studio 11 2012`
  - ``Visual Studio 12`` -> :generator:`Visual Studio 12 2013`

  This clarifies which generator goes with each Visual Studio
  version.  The old names are recognized for compatibility.

* The :variable:`CMAKE_<LANG>_COMPILER_ID` value for Apple-provided
  Clang is now ``AppleClang``.  It must be distinct from upstream
  Clang because the version numbers differ.
  See policy :policy:`CMP0025`.

* The :variable:`CMAKE_<LANG>_COMPILER_ID` value for ``qcc`` on QNX
  is now ``QCC``.  It must be distinct from ``GNU`` because the
  command-line options differ.  See policy :policy:`CMP0047`.

* On 64-bit OS X the :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` value
  is now correctly detected as ``x86_64`` instead of ``i386``.

* On OS X, CMake learned to enable behavior specified by the
  :prop_tgt:`MACOSX_RPATH` target property by default.  This activates
  use of ``@rpath`` for runtime shared library searches.
  See policy :policy:`CMP0042`.

* The :command:`build_command` command now returns a :manual:`cmake(1)`
  ``--build`` command line instead of a direct invocation of the native
  build tool.  When using ``Visual Studio`` generators, CMake and CTest
  no longer require :variable:`CMAKE_MAKE_PROGRAM` to be located up front.
  Selection of the proper msbuild or devenv tool is now performed as
  late as possible when the solution (``.sln``) file is available so
  it can depend on project content.

* The :manual:`cmake(1)` ``--build`` command now shares its own stdout
  and stderr pipes with the native build tool by default.
  The ``--use-stderr`` option that once activated this is now ignored.

* The ``$<C_COMPILER_ID:...>`` and ``$<CXX_COMPILER_ID:...>``
  :manual:`generator expressions <cmake-generator-expressions(7)>`
  used to perform case-insensitive comparison but have now been
  corrected to perform case-sensitive comparison.
  See policy :policy:`CMP0044`.

* The builtin ``edit_cache`` target will no longer select
  :manual:`ccmake(1)` by default when no interactive terminal will
  be available (e.g. with :generator:`Ninja` or an IDE generator).
  Instead :manual:`cmake-gui(1)` will be preferred if available.

* The :module:`ExternalProject` download step learned to
  re-attempt download in certain cases to be more robust to
  temporary network failure.

* The :module:`FeatureSummary` no longer lists transitive
  dependencies since they were not directly requested by the
  current project.

* The ``cmake-mode.el`` major Emacs editing mode has been cleaned
  up and enhanced in several ways.

* Include directories specified in the
  :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of :ref:`Imported Targets`
  are treated as ``SYSTEM`` includes by default when handled as
  :ref:`usage requirements <Include Directories and Usage Requirements>`.


code:
CMake 3.1 Release Notes
***********************

.. only:: html

  .. contents::

Changes made since CMake 3.0 include the following.

Documentation Changes
=====================

* A new :manual:`cmake-compile-features(7)` manual was added.

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

Generators
----------

* The :generator:`Visual Studio 14 2015` generator was added.

Windows Phone and Windows Store
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* Generators for Visual Studio 11 (2012) and above learned to generate
  projects for Windows Phone and Windows Store.  One may set the
  :variable:`CMAKE_SYSTEM_NAME` variable to ``WindowsPhone``
  or ``WindowsStore`` on the :manual:`cmake(1)` command-line
  or in a :variable:`CMAKE_TOOLCHAIN_FILE` to activate these platforms.
  Also set :variable:`CMAKE_SYSTEM_VERSION` to ``8.0`` or ``8.1`` to
  specify the version of Windows to be targeted.

NVIDIA Nsight Tegra
^^^^^^^^^^^^^^^^^^^

* Generators for Visual Studio 10 (2010) and above learned to generate
  projects for NVIDIA Nsight Tegra Visual Studio Edition.  One may set
  the :variable:`CMAKE_SYSTEM_NAME` variable to ``Android`` on the
  :manual:`cmake(1)` command-line or in a :variable:`CMAKE_TOOLCHAIN_FILE`
  to activate this platform.

Syntax
------

* The :manual:`cmake-language(7)` syntax for :ref:`Variable References` and
  :ref:`Escape Sequences` was simplified in order to allow a much faster
  implementation.  See policy :policy:`CMP0053`.

* The :command:`if` command no longer automatically dereferences
  variables named in quoted or bracket arguments.  See policy
  :policy:`CMP0054`.

Commands
--------

* The :command:`add_custom_command` command learned to interpret
  :manual:`cmake-generator-expressions(7)` in arguments to ``DEPENDS``.

* The :command:`export(PACKAGE)` command learned to check the
  :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable to skip
  exporting the package.

* The :command:`file(STRINGS)` command gained a new ``ENCODING``
  option to enable extraction of ``UTF-8`` strings.

* The :command:`find_package` command learned to check the
  :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` and
  :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY`
  variables to skip searching the package registries.

* The :command:`get_property` command learned a new ``INSTALL`` scope
  for properties.

* The :command:`install` command learned a ``MESSAGE_NEVER`` option
  to avoid output during installation.

* The :command:`set_property` command learned a new ``INSTALL`` scope
  for properties.

* The :command:`string` command learned a new ``GENEX_STRIP`` subcommand
  which removes
  :manual:`generator expression <cmake-generator-expressions(7)>`.

* The :command:`string` command learned a new ``UUID`` subcommand
  to generate a universally unique identifier.

* New :command:`target_compile_features` command allows populating the
  :prop_tgt:`COMPILE_FEATURES` target property, just like any other
  build variable.

* The :command:`target_sources` command was added to add to the
  :prop_tgt:`SOURCES` target property.

Variables
---------

* The Visual Studio generators for versions 8 (2005) and above
  learned to read the target platform name from a new
  :variable:`CMAKE_GENERATOR_PLATFORM` variable when it is
  not specified as part of the generator name.  The platform
  name may be specified on the :manual:`cmake(1)` command line
  with the ``-A`` option, e.g. ``-G "Visual Studio 12 2013" -A x64``.

* The :variable:`CMAKE_GENERATOR_TOOLSET` variable may now be
  initialized in a toolchain file specified by the
  :variable:`CMAKE_TOOLCHAIN_FILE` variable.  This is useful
  when cross-compiling with the Xcode or Visual Studio
  generators.

* The :variable:`CMAKE_INSTALL_MESSAGE` variable was introduced to
  optionally reduce output installation.

Properties
----------

* New :prop_tgt:`CXX_STANDARD` and :prop_tgt:`CXX_EXTENSIONS` target
  properties may specify values which CMake uses to compute required
  compile options such as ``-std=c++11`` or ``-std=gnu++11``. The
  :variable:`CMAKE_CXX_STANDARD` and :variable:`CMAKE_CXX_EXTENSIONS`
  variables may be set to initialize the target properties.

* New :prop_tgt:`C_STANDARD` and :prop_tgt:`C_EXTENSIONS` target
  properties may specify values which CMake uses to compute required
  compile options such as ``-std=c11`` or ``-std=gnu11``. The
  :variable:`CMAKE_C_STANDARD` and :variable:`CMAKE_C_EXTENSIONS`
  variables may be set to initialize the target properties.

* New :prop_tgt:`COMPILE_FEATURES` target property may contain a list
  of features required to compile a target.  CMake uses this
  information to ensure that the compiler in use is capable of building
  the target, and to add any necessary compile flags to support language
  features.

* New :prop_tgt:`COMPILE_PDB_NAME` and
  :prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY` target properties
  were introduced to specify the MSVC compiler program database
  file location (``cl /Fd``).  This complements the existing
  :prop_tgt:`PDB_NAME` and :prop_tgt:`PDB_OUTPUT_DIRECTORY`
  target properties that specify the linker program database
  file location (``link /pdb``).

* The :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property now supports
  a ``$<LINK_ONLY:...>``
  :manual:`generator expression <cmake-generator-expressions(7)>`.

* A new :prop_tgt:`INTERFACE_SOURCES` target property was introduced. This is
  consumed by dependent targets, which compile and link the listed sources.

* The :prop_tgt:`SOURCES` target property now contains
  :manual:`generator expression <cmake-generator-expressions(7)>`
  such as ``TARGET_OBJECTS`` when read at configure time, if
  policy :policy:`CMP0051` is ``NEW``.

* The :prop_tgt:`SOURCES` target property now generally supports
  :manual:`generator expression <cmake-generator-expressions(7)>`.  The
  generator expressions may be used in the :command:`add_library` and
  :command:`add_executable` commands.

* It is now possible to write and append to the :prop_tgt:`SOURCES` target
  property.  The :variable:`CMAKE_DEBUG_TARGET_PROPERTIES` variable may be
  used to trace the origin of sources.

* A :prop_sf:`VS_DEPLOYMENT_CONTENT` source file property was added
  to tell the Visual Studio generators to mark content for deployment
  in Windows Phone and Windows Store projects.

* A :prop_sf:`VS_DEPLOYMENT_LOCATION` source file property was added
  to tell the Visual Studio generators the relative location of content
  marked for deployment in Windows Phone and Windows Store projects.

* The :prop_tgt:`VS_WINRT_COMPONENT` target property was created to
  tell Visual Studio generators to compile a shared library as a
  Windows Runtime (WinRT) component.

* The :generator:`Xcode` generator learned to check source
  file properties  :prop_sf:`XCODE_EXPLICIT_FILE_TYPE` and
  :prop_sf:`XCODE_LAST_KNOWN_FILE_TYPE` for a custom Xcode
  file reference type.

Modules
-------

* The :module:`BundleUtilities` module learned to resolve and replace
  ``@rpath`` placeholders on OS X to correctly bundle applications
  using them.

* The :module:`CMakePackageConfigHelpers` module
  :command:`configure_package_config_file` command learned a new
  ``INSTALL_PREFIX`` option to generate package configuration files
  meant for a prefix other than :variable:`CMAKE_INSTALL_PREFIX`.

* The :module:`CheckFortranSourceCompiles` module was added to
  provide a ``CHECK_Fortran_SOURCE_COMPILES`` macro.

* The :module:`ExternalData` module learned to tolerate a ``DATA{}``
  reference to a missing source file with a warning instead of
  rejecting it with an error.  This helps developers write new
  ``DATA{}`` references to test reference outputs that have not
  yet been created.

* The :module:`ExternalProject` module learned to support lzma-compressed
  source tarballs with ``.7z``, ``.tar.xz``, and ``.txz`` extensions.

* The :module:`ExternalProject` module ``ExternalProject_Add`` command
  learned a new ``BUILD_ALWAYS`` option to cause the external project
  build step to run every time the host project is built.

* The :module:`ExternalProject` module ``ExternalProject_Add`` command
  learned a new ``EXCLUDE_FROM_ALL`` option to cause the external
  project target to have the :prop_tgt:`EXCLUDE_FROM_ALL` target
  property set.

* The :module:`ExternalProject` module ``ExternalProject_Add_Step`` command
  learned a new ``EXCLUDE_FROM_MAIN`` option to cause the step to not be
  a direct dependency of the main external project target.

* The :module:`ExternalProject` module ``ExternalProject_Add`` command
  learned a new ``DOWNLOAD_NO_PROGRESS`` option to disable progress
  output while downloading the source tarball.

* The :module:`FeatureSummary` module ``feature_summary`` API
  learned to accept multiple values for the ``WHAT`` option and
  combine them appropriately.

* The :module:`FindCUDA` module learned to support ``fatbin`` and ``cubin``
  modules.

* The :module:`FindGTest` module ``gtest_add_tests`` macro learned
  a new ``AUTO`` option to automatically read the :prop_tgt:`SOURCES`
  target property of the test executable and scan the source files
  for tests to be added.

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

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

* The :module:`FindHg` module gained a new ``Hg_WC_INFO`` macro to
  help run ``hg`` to extract information about a Mercurial work copy.

* The :module:`FindOpenCL` module was introduced.

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

* The :module:`FindPkgConfig` module learned to use the ``PKG_CONFIG``
  environment variable value as the ``pkg-config`` executable, if set.

* The :module:`FindXercesC` module was introduced.

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

* The :module:`GenerateExportHeader` module ``generate_export_header``
  function learned to allow use with :ref:`Object Libraries`.

* The :module:`InstallRequiredSystemLibraries` module gained a new
  ``CMAKE_INSTALL_OPENMP_LIBRARIES`` option to install MSVC OpenMP
  runtime libraries.

* The :module:`UseSWIG` module learned to detect the module name
  from ``.i`` source files if possible to avoid the need to set
  the ``SWIG_MODULE_NAME`` source file property explicitly.

* The :module:`WriteCompilerDetectionHeader` module was added to allow
  creation of a portable header file for compiler optional feature detection.

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

* New ``COMPILE_FEATURES``
  :manual:`generator expression <cmake-generator-expressions(7)>` allows
  setting build properties based on available compiler features.

CTest
-----

* The :command:`ctest_coverage` command learned to read variable
  ``CTEST_COVERAGE_EXTRA_FLAGS`` to set ``CoverageExtraFlags``.

* The :command:`ctest_coverage` command learned to support
  Intel coverage files with the ``codecov`` tool.

* The :command:`ctest_memcheck` command learned to support sanitizer
  modes, including ``AddressSanitizer``, ``MemorySanitizer``,
  ``ThreadSanitizer``, and ``UndefinedBehaviorSanitizer``.
  Options may be set using the new
  :variable:`CTEST_MEMORYCHECK_SANITIZER_OPTIONS` variable.

CPack
-----

* :manual:`cpack(1)` gained an ``IFW`` generator to package using
  Qt Framework Installer tools.  See the :cpack_gen:`CPack IFW Generator`.

* :manual:`cpack(1)` gained ``7Z`` and ``TXZ`` generators supporting
  lzma-compressed archives.

* The :cpack_gen:`CPack DEB Generator` learned a new
  :variable:`CPACK_DEBIAN_COMPRESSION_TYPE` variable to set the
  tarball compression type.

* The :cpack_gen:`CPack WIX Generator` learned to support
  a :prop_inst:`CPACK_WIX_ACL` installed file property to
  specify an Access Control List.

Other
-----

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

* The :manual:`cmake(1)` ``-E tar`` command learned to support
  lzma-compressed files.

* :ref:`Object Libraries` may now have extra sources that do not
  compile to object files so long as they would not affect linking
  of a normal library (e.g. ``.dat`` is okay but not ``.def``).

* Visual Studio generators for VS 8 and later learned to support
  the ``ASM_MASM`` language.

* The Visual Studio generators learned to treat ``.hlsl`` source
  files as High Level Shading Language sources (using ``FXCompile``
  in ``.vcxproj`` files).  Source file properties
  :prop_sf:`VS_SHADER_TYPE`, :prop_sf:`VS_SHADER_MODEL`, and
  :prop_sf:`VS_SHADER_ENTRYPOINT` were added added to specify the
  shader type, model, and entry point name.

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

* Policy :policy:`CMP0052` introduced to control directories in the
  :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of exported targets.

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

* In CMake 3.0 the :command:`target_link_libraries` command
  accidentally began allowing unquoted arguments to use
  :manual:`generator expressions <cmake-generator-expressions(7)>`
  containing a (``;`` separated) list within them.  For example::

    set(libs B C)
    target_link_libraries(A PUBLIC $<BUILD_INTERFACE:${libs}>)

  This is equivalent to writing::

    target_link_libraries(A PUBLIC $<BUILD_INTERFACE:B C>)

  and was never intended to work.  It did not work in CMake 2.8.12.
  Such generator expressions should be in quoted arguments::

    set(libs B C)
    target_link_libraries(A PUBLIC "$<BUILD_INTERFACE:${libs}>")

  CMake 3.1 again requires the quotes for this to work correctly.

* Prior to CMake 3.1 the Makefile generators did not escape ``#``
  correctly inside make variable assignments used in generated
  makefiles, causing them to be treated as comments.  This made
  code like::

    add_compile_options(-Wno-#pragma-messages)

  not work in Makefile generators, but work in other generators.
  Now it is escaped correctly, making the behavior consistent
  across generators.  However, some projects may have tried to
  workaround the original bug with code like::

    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wno-\\#pragma-messages")

  This added the needed escape for Makefile generators but also
  caused other generators to pass ``-Wno-\#pragma-messages`` to
  the shell, which would work only in POSIX shells.
  Unfortunately the escaping fix could not be made in a compatible
  way so this platform- and generator-specific workaround no
  longer works.  Project code may test the :variable:`CMAKE_VERSION`
  variable value to make the workaround version-specific too.

* Callbacks established by the :command:`variable_watch` command will no
  longer receive the ``ALLOWED_UNKNOWN_READ_ACCESS`` access type when
  the undocumented ``CMAKE_ALLOW_UNKNOWN_VARIABLE_READ_ACCESS`` variable is
  set.  Uninitialized variable accesses will always be reported as
  ``UNKNOWN_READ_ACCESS``.

* The :module:`CMakeDetermineVSServicePack` module now warns that
  it is deprecated and should not longer be used.  Use the
  :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable instead.

* The :module:`FindITK` module has been removed altogether.
  It was a thin-wrapper around ``find_package(ITK ... NO_MODULE)``.
  This produces much clearer error messages when ITK is not found.

* The :module:`FindVTK` module has been removed altogether.
  It was a thin-wrapper around ``find_package(VTK ... NO_MODULE)``.
  This produces much clearer error messages when VTK is not found.

  The module also provided compatibility support for finding VTK 4.0.
  This capability has been dropped.

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

* The :manual:`cmake-gui(1)` learned to capture output from child
  processes started by the :command:`execute_process` command
  and display it in the output window.

* The :manual:`cmake-language(7)` internal implementation of generator
  expression and list expansion parsers have been optimized and shows
  non-trivial speedup on large projects.

* The Makefile generators learned to use response files with GNU tools
  on Windows to pass library directories and names to the linker.

* When generating linker command-lines, CMake now avoids repeating
  items corresponding to SHARED library targets.

* Support for the Open Watcom compiler has been overhauled.
  The :variable:`CMAKE_<LANG>_COMPILER_ID` is now ``OpenWatcom``,
  and the :variable:`CMAKE_<LANG>_COMPILER_VERSION` now uses
  the Open Watcom external version numbering.  The external
  version numbers are lower than the internal version number
  by 11.

* The ``cmake-mode.el`` major Emacs editing mode no longer
  treats ``_`` as part of words, making it more consistent
  with other major modes.


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.


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.