code:
CMP0111
-------

.. versionadded:: 3.19

An imported target missing its location property fails during generation.

:ref:`Imported Targets` for library files and executables require that
their location on disk is specified in a target property such as
:prop_tgt:`IMPORTED_LOCATION`, :prop_tgt:`IMPORTED_IMPLIB`, or a
per-configuration equivalent.  If a needed location property is not set,
CMake 3.18 and below generate the string ``<TARGET_NAME>-NOTFOUND`` in
its place, which results in failures of the corresponding rules at build
time.  CMake 3.19 and above prefer instead to raise an error during
generation.  This policy provides compatibility for projects that have
not been updated to expect the new behavior.

The ``OLD`` behavior of this policy is to generate the location of an imported
unknown, static or shared library target as ``<TARGET_NAME>-NOTFOUND`` if not
set.
The ``NEW`` behavior is to raise an error.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.19
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0112
-------

.. versionadded:: 3.19

Target file component generator expressions do not add target dependencies.

The following target-based generator expressions that query for directory or
file name components no longer add a dependency on the evaluated target.

    - ``TARGET_FILE_NAME``
    - ``TARGET_FILE_DIR``
    - ``TARGET_LINKER_FILE_BASE_NAME``
    - ``TARGET_LINKER_FILE_NAME``
    - ``TARGET_LINKER_FILE_DIR``
    - ``TARGET_SONAME_FILE_NAME``
    - ``TARGET_SONAME_FILE_DIR``
    - ``TARGET_PDB_FILE_NAME``
    - ``TARGET_PDB_FILE_DIR``
    - ``TARGET_BUNDLE_DIR``
    - ``TARGET_BUNDLE_DIR_NAME``
    - ``TARGET_BUNDLE_CONTENT_DIR``

In CMake 3.18 and lower a dependency on the evaluated target of the above
generator expressions would always be added.  CMake 3.19 and above prefer
to not add this dependency.  This policy provides compatibility for projects
that have not been updated to expect the new behavior.  The policy setting
is recorded on each target when it is created, and decides whether generator
expressions referencing that target imply a dependency on it.

The ``OLD`` behavior for this policy is to add a dependency on the evaluated
target for the above generator expressions.  The ``NEW`` behavior of
this policy is to not add a dependency on the evaluated target for the
above generator expressions.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.19
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn by default
.. include:: STANDARD_ADVICE.txt

See documentation of the
:variable:`CMAKE_POLICY_WARNING_CMP0112 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
variable to control the warning.

.. include:: DEPRECATED.txt

repo_name: lazytadpole/codenamesilverfish

license: mit


code:
CMP0113
-------

.. versionadded:: 3.19

:ref:`Makefile Generators` do not repeat custom commands from target
dependencies.

Consider a chain of custom commands split across two dependent targets:

.. code-block:: cmake

  add_custom_command(OUTPUT output-not-created
    COMMAND ... DEPENDS ...)
  set_property(SOURCE output-not-created PROPERTY SYMBOLIC 1)
  add_custom_command(OUTPUT output-created
    COMMAND ... DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/output-not-created)
  add_custom_target(first DEPENDS output-not-created)
  add_custom_target(second DEPENDS output-created)
  add_dependencies(second first)

In CMake 3.18 and lower, the Makefile generators put a copy of both custom
commands in the Makefile for target ``second`` even though its dependency on
target ``first`` ensures that the first custom command runs before the second.
Running ``make second`` would cause the first custom command to run once in
the ``first`` target and then again in the ``second`` target.

CMake 3.19 and above prefer to not duplicate custom commands in a target that
are already generated in other targets on which the target depends (directly or
indirectly).  This policy provides compatibility for projects that have not
been updated to expect the new behavior.  In particular, projects that relied
on the duplicate execution or that did not properly set the :prop_sf:`SYMBOLIC`
source file property may be affected.

The ``OLD`` behavior for this policy is to duplicate custom commands in
dependent targets.  The ``NEW`` behavior of this policy is to not duplicate
custom commands in dependent targets.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.19
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0114
-------

.. versionadded:: 3.19

:module:`ExternalProject` step targets fully adopt their steps.

The :command:`ExternalProject_Add` ``STEP_TARGETS`` option, and the
:command:`ExternalProject_Add_StepTargets` function, can be used to
create build targets for individual steps of an external project.

In CMake 3.18 and below, step targets have some limitations:

* Step targets always depend on targets named by the
  :command:`ExternalProject_Add` ``DEPENDS`` option even though
  not all steps need them.  In order to allow step targets to be created
  without those dependencies, the :command:`ExternalProject_Add`
  ``INDEPENDENT_STEP_TARGETS`` option or the
  :command:`ExternalProject_Add_StepTargets` ``NO_DEPENDS`` option may
  be used.  However, adding such "independent" step targets makes sense
  only for specific steps such as ``download``, ``update``, and ``patch``
  because they do not need any of the external project's build dependencies.
  Furthermore, it does not make sense to create independent step targets
  for steps that depend on non-independent steps.  Such rules are not
  enforced, and projects that do not follow them can generate build systems
  with confusing and generator-specific behavior.

* Step targets hold copies of the custom commands implementing their
  steps that are separate from the copies in the primary target created
  by :command:`ExternalProject_Add`, and the primary target does not
  depend on the step targets.  In parallel builds that drive the primary
  target and step targets concurrently, multiple copies of the steps'
  commands may run concurrently and race each other.

  Also, prior to policy :policy:`CMP0113`, the step targets generated
  by :ref:`Makefile Generators` also contain all the custom commands
  on which their step depends.  This can lead to repeated execution of
  those steps even in serial builds.

In CMake 3.19 and above, the :module:`ExternalProject` module prefers
a revised design to address these problems:

* Each step is classified as "independent" if it does not depend
  on other targets named by the :command:`ExternalProject_Add` ``DEPENDS``.
  The predefined steps are automatically classified by default:

  * The ``download``, ``update``, and ``patch`` steps are independent.
  * The ``configure``, ``build``, ``test``, and ``install`` steps are not.

  For custom steps, the :command:`ExternalProject_Add_Step` command provides
  an ``INDEPENDENT`` option to mark them as independent.  It is an error to
  mark a step as independent if it depends on other steps that are not.  Note
  that this use of the term "independent" refers only to independence from
  external targets and is orthogonal to a step's dependencies on other steps.

* Step targets created by the :command:`ExternalProject_Add` ``STEP_TARGETS``
  option or the :command:`ExternalProject_Add_Step` function are now
  independent if and only if their steps are marked as independent.
  The :command:`ExternalProject_Add` ``INDEPENDENT_STEP_TARGETS`` option
  and :command:`ExternalProject_Add_StepTargets` ``NO_DEPENDS`` option
  are no longer allowed.

* Step targets, when created, are fully responsible for holding the
  custom commands implementing their steps.  The primary target created
  by :command:`ExternalProject_Add` depends on the step targets, and the
  step targets depend on each other.  The target-level dependencies match
  the file-level dependencies used by the custom commands for each step.

  When the :command:`ExternalProject_Add` ``UPDATE_DISCONNECTED`` or
  ``TEST_EXCLUDE_FROM_MAIN`` option is used, or the
  :command:`ExternalProject_Add_Step` ``EXCLUDE_FROM_MAIN`` option is used
  for a custom step, some step targets may be created automatically.
  These are needed to hold the steps commonly depended upon by the primary
  target and the disconnected step targets.

Policy ``CMP0114`` provides compatibility for projects that have not been
updated to expect the new behavior.  The ``OLD`` behavior for this policy
is to use the above-documented behavior from 3.18 and below.  The ``NEW``
behavior for this policy is to use the above-documented behavior preferred
by 3.19 and above.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.19
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0115
-------

.. versionadded:: 3.20

Source file extensions must be explicit.

In CMake 3.19 and below, if a source file could not be found by the name
specified, it would append a list of known extensions to the name to see if
the file with the extension could be found. For example, this would allow the
user to run:

.. code-block:: cmake

  add_executable(exe main)

and put ``main.c`` in the executable without specifying the extension.

Starting in CMake 3.20, CMake prefers all source files to have their extensions
explicitly listed:

.. code-block:: cmake

  add_executable(exe main.c)

The ``OLD`` behavior for this policy is to implicitly append known extensions
to source files if they can't be found. The ``NEW`` behavior of this policy is
to not append known extensions and require them to be explicit.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.20
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0116
-------

.. versionadded:: 3.20

Ninja generators transform ``DEPFILE`` s from :command:`add_custom_command`.

In CMake 3.19 and below, files given to the ``DEPFILE`` argument of
:command:`add_custom_command` were passed directly to Ninja's ``depfile``
variable without any path resolution. This meant that if
:command:`add_custom_command` was called from a subdirectory (created by
:command:`add_subdirectory`), the ``DEPFILE`` argument would have to be either
an absolute path or a path relative to :variable:`CMAKE_BINARY_DIR`, rather
than :variable:`CMAKE_CURRENT_BINARY_DIR`. In addition, no transformation was
done on the file listed in ``DEPFILE``, which meant that the paths within the
``DEPFILE`` had the same restrictions.

Starting with CMake 3.20, the ``DEPFILE`` argument is relative to
:variable:`CMAKE_CURRENT_BINARY_DIR` (unless it is absolute), and the paths in
the ``DEPFILE`` are also relative to :variable:`CMAKE_CURRENT_BINARY_DIR`.
CMake automatically transforms the paths in the ``DEPFILE`` (unless they are
absolute) after the custom command is run. The file listed in ``DEPFILE`` is
not modified in any way. Instead, CMake writes the transformation to its own
internal file, and passes this internal file to Ninja's ``depfile`` variable.
This transformation happens regardless of whether or not ``DEPFILE`` is
relative, and regardless of whether or not :command:`add_custom_command` is
called from a subdirectory.

The ``OLD`` behavior for this policy is to pass the ``DEPFILE`` to Ninja
unaltered. The ``NEW`` behavior for this policy is to transform the ``DEPFILE``
after running the custom command. The status of ``CMP0116`` is recorded at the
time of the custom command's creation, and you can have custom commands in the
same directory with different values for ``CMP0116`` by setting the policy
before each custom command.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.20
.. |WARNS_OR_DOES_NOT_WARN| replace::
   does *not* warn by default (unless ``DEPFILE`` is used in a subdirectory)
.. include:: STANDARD_ADVICE.txt

See documentation of the
:variable:`CMAKE_POLICY_WARNING_CMP0116 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
variable to control the warning.

.. include:: DEPRECATED.txt


code:
CMP0117
-------

.. versionadded:: 3.20

MSVC RTTI flag ``/GR`` is not added to
:variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` by default.

When using MSVC-like compilers in CMake 3.19 and below, the RTTI flag
``/GR`` is added to :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` by
default.  This behavior is left from support for MSVC versions from Visual
Studio 2003 and below that did not enable RTTI by default.  It is no longer
necessary.  Furthermore, it is problematic for projects that want to change
to ``/GR-`` programmatically.  In particular, it requires string editing of
the :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` variable with knowledge
of the CMake builtin default so it can be replaced.

CMake 3.20 and above prefer to leave out ``/GR`` from the value of
:variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` by default.

This policy provides compatibility with projects that have not been updated
to expect the lack of the ``/GR`` flag.  The policy setting takes effect as
of the first :command:`project` or :command:`enable_language` command that
initializes :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>`.

.. note::

  Once the policy has taken effect at the top of a project for a given
  language, that choice must be used throughout the tree for that language.
  In projects that have nested projects in subdirectories, be sure to
  convert everything together.

The ``OLD`` behavior for this policy is to place the MSVC ``/GR`` flag in the
default :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` cache entry.  The
``NEW`` behavior for this policy is to *not* place the MSVC ``/GR`` flag in
the default cache entry.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.20
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0118
-------

.. versionadded:: 3.20

The :prop_sf:`GENERATED` source file property is now visible in all directories.

Whether or not a source file is generated is an all-or-nothing global
property of the source.  Consequently, the associated ``GENERATED``
property is now visible from any directory scope, not only from the scope
for which it was set.

Additionally, the ``GENERATED`` property may now be set only to boolean
values, and may not be turned off once turned on.

The ``OLD`` behavior of this policy is to only allow ``GENERATED`` to be
visible from the directory scope for which it was set.  The ``NEW``
behavior on the other hand allows it to be visible from any scope.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.20
.. |WARNS_OR_DOES_NOT_WARN| replace::
   does *not* warn with regard to visibility of the ``GENERATED``
   property, but does warn about setting the ``GENERATED`` property
   to a non-boolean value,
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0119
-------

.. versionadded:: 3.20

:prop_sf:`LANGUAGE` source file property explicitly compiles as specified
language.

The :prop_sf:`LANGUAGE` source file property is documented to mean that the
source file is written in the specified language.  In CMake 3.19 and below,
setting this property causes CMake to compile the source file using the
compiler for the specified language.  However, it only passes an explicit
flag to tell the compiler to treat the source as the specified language
for MSVC-like, XL, and Embarcadero compilers for the ``CXX`` language.
CMake 3.20 and above prefer to also explicitly tell the compiler to use
the specified language using a flag such as ``-x c`` on all compilers
for which such flags are known.

This policy provides compatibility for projects that have not been updated
to expect this behavior.  For example, some projects were setting the
``LANGUAGE`` property to ``C`` on assembly-language ``.S`` source files
in order to compile them using the C compiler.  Such projects should be
updated to use ``enable_language(ASM)``, for which CMake will often choose
the C compiler as the assembler on relevant platforms anyway.

The ``OLD`` behavior for this policy is to interpret the ``LANGUAGE <LANG>``
property using its undocumented meaning to "use the ``<LANG>`` compiler".
The ``NEW`` behavior for this policy is to interpret the ``LANGUAGE <LANG>``
property using its documented meaning to "compile as a ``<LANG>`` source".

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.20
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0120
-------

.. versionadded:: 3.20

The :module:`WriteCompilerDetectionHeader` module is removed.

CMake versions 3.1 through 3.19 provide this module to generate a
C++ compatibility layer by re-using information from CMake's table of
preprocessor checks for :manual:`cmake-compile-features(7)`.  However:

* Those granular features have been superseded by meta-features for
  :ref:`Requiring Language Standards` such as ``cxx_std_11``.  Therefore
  no new granular feature checks will be added and projects will need to
  use other means to conditionally use new C++ features.

* The module exposes some of CMake's implementation details directly
  to C++ translation units.

* The module's approach effectively provides a header file with CMake,
  thus tying the version of the header to the version of CMake.
  Many projects found that the :module:`WriteCompilerDetectionHeader` was
  best used by manually generating its header locally with a recent version
  of CMake and then bundling it with the project source so that it could
  be used with older CMake versions.

For reasons including the above, CMake 3.20 and above prefer to not
provide the :module:`WriteCompilerDetectionHeader` module.  This policy
provides compatibility for projects that have not been ported away from
it.  Projects using the module should be updated to stop using it.
Alternatives include:

* Bundle a copy of the generated header in the project's source.
* Use a third-party alternative, such as the CC0-licensed `Hedley`_.
* Drop support for compilers too old to provide the features natively.

The ``OLD`` behavior of this policy is for inclusion of the deprecated
:module:`WriteCompilerDetectionHeader` module to work.  The ``NEW``
behavior is for inclusion of the module to fail as if it does not exist.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.20
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt

.. _`Hedley`: https://nemequ.github.io/hedley/


code:
CMP0121
-------

.. versionadded:: 3.21

The :command:`list` command now detects invalid indices.

Prior to CMake version 3.21, the :command:`list` command's ``GET``,
``INSERT``, ``SUBLIST``, and ``REMOVE_AT`` subcommands did not detect invalid
index arguments.

The ``OLD`` behavior of this policy is for invalid indices to be treated as
their integer value (if any) at the start of the string. For example,
``2good4you`` is a ``2`` and ``not_an_integer`` is a ``0``. The ``NEW``
behavior is for invalid indices to trigger an error.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.21
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0122
-------

.. versionadded:: 3.21

:module:`UseSWIG` use library name conventions for ``CSharp`` language.

Starting with CMake 3.21, :module:`UseSWIG` generates now a library using
default naming conventions. This policy provides compatibility with projects
that expect the legacy behavior.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.21
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0123
-------

.. versionadded:: 3.21

``ARMClang`` cpu/arch compile and link flags must be set explicitly.

CMake 3.20 and lower automatically maps the :variable:`CMAKE_SYSTEM_PROCESSOR`
variable and an undocumented ``CMAKE_SYSTEM_ARCH`` to compile and link options
for ``ARMClang``.  For example, the ``-mcpu=cortex-m33`` flag is added when
:variable:`CMAKE_SYSTEM_PROCESSOR` equals ``cortex-m33``.  CMake requires
projects to set either variable or it raises a fatal error.  However, the
project may need to additionally specify CPU features using e.g.
``-mcpu=cortex-m33+nodsp``, conflicting with the ``-mcpu=cortex-m33`` added
by CMake.  This results in either link errors or unusable binaries.

CMake 3.21 and above prefer instead to not add any cpu/arch compile and link
flags automatically.  Instead, projects must specify them explicitly.
This policy provides compatibility for projects that have not been updated.

The ``OLD`` behavior of this policy requires projects that use ``ARMClang``
to set either :variable:`CMAKE_SYSTEM_PROCESSOR` or ``CMAKE_SYSTEM_ARCH``
and it automatically adds a compile option ``-mcpu=`` or ``-march=`` and
a link option ``--cpu=`` based on those variables.  The ``NEW`` behavior
does not add compile or link options, and projects are responsible for
setting correct options.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.21
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0124
-------

.. versionadded:: 3.21

:command:`foreach` loop variables are only available in the loop scope.

CMake 3.20 and below always leave the loop variable set at the end of the
loop, either to the value it had before the loop, if any, or to the empty
string.  CMake 3.21 and above prefer to leave the loop variable in the
state it had before the loop started, either set or unset.  This policy
provides compatibility for projects that expect the loop variable to always
be left set.

The ``OLD`` behavior for this policy is to set the loop variable at the
end of the loop, either to its original value, or to an empty value.
The ``NEW`` behavior for this policy is to restore the loop variable to
the state it had before the loop started, either set or unset.

For example:

.. code-block:: cmake

  set(items a b c)

  set(var1 "value")
  unset(var2)

  foreach(var1 IN LISTS items)
  endforeach()

  foreach(var2 IN LISTS items)
  endforeach()

  if(DEFINED var1)
    message("var1: ${var1}")
  endif()
  if(DEFINED var2)
    message("var2: ${var2}")
  endif()

Under the ``OLD`` behavior, this code prints ``var1: value`` and ``var2:``.
Under the ``NEW`` behavior, this code prints only ``var1: value``.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.21
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0125
-------

.. versionadded:: 3.21

The :command:`find_file`, :command:`find_path`, :command:`find_library` and
:command:`find_program` commands cache their result in the variable specified
by their first argument.  Prior to CMake 3.21, if a cache variable of that
name already existed before the call but the cache variable had no type, any
non-cache variable of the same name would be discarded and the cache variable
was always used (see also :policy:`CMP0126` for a different but similar
behavior).  This contradicts the convention that a non-cache variable should
take precedence over a cache variable of the same name.  Such a situation can
arise if a user sets a cache variable on the command line without specifying
a type, such as ``cmake -DMYVAR=blah ...`` instead of
``cmake -DMYVAR:FILEPATH=blah``.

Related to the above, if a cache variable of the specified name already exists
and it *does* have a type, the various ``find_...()`` commands would return
that value unchanged.  In particular, if it contained a relative path, it
would not be converted to an absolute path in this situation.

When policy ``CMP0125`` is set to ``OLD`` or is unset, the behavior is as
described above.  When it is set to ``NEW``, the behavior is as follows:

* If a non-cache variable of the specified name exists when the ``find_...()``
  command is called, its value will be used regardless of whether a cache
  variable of the same name already exists or not.  A cache variable will not
  be created in this case if no such cache variable existed before.
  If a cache variable of the specified name did already exist, the cache will
  be updated to match the non-cache variable.

* The various ``find...()`` commands will always provide an absolute path in
  the result variable, except where a relative path provided by a cache or
  non-cache variable cannot be resolved to an existing path.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.21
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0126
-------

.. versionadded:: 3.21

When this policy is set to ``NEW``, the :command:`set(CACHE)` command does not
remove any normal variable of the same name from the current scope.
The ``OLD`` behavior removes any normal variable of the same name from the
current scope in the following situations:

* No cache variable of that name existed previously.

* A cache variable of that name existed previously, but it had no type.
  This can occur when the variable was set on the command line using a form
  like ``cmake -DMYVAR=blah`` instead of ``cmake -DMYVAR:STRING=blah``.

* The ``FORCE`` or ``INTERNAL`` keywords were used when setting the cache
  variable.

Note that the ``NEW`` behavior has an important difference to the similar
``NEW`` behavior of policy :policy:`CMP0077`.  The :command:`set(CACHE)`
command always sets the cache variable if it did not exist previously,
regardless of the ``CMP0126`` policy setting.  The :command:`option` command
will *not* set the cache variable if a non-cache variable of the same name
already exists and :policy:`CMP0077` is set to ``NEW``.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.21
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn by default
.. include:: STANDARD_ADVICE.txt

See documentation of the
:variable:`CMAKE_POLICY_WARNING_CMP0126 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
variable to control the warning.

The :variable:`CMAKE_POLICY_DEFAULT_CMP0126 <CMAKE_POLICY_DEFAULT_CMP\<NNNN\>>`
variable may be used to set the policy for a third-party project in a
subdirectory without modifying it.

.. include:: DEPRECATED.txt


code:
CMP0127
-------

.. versionadded:: 3.22

:command:`cmake_dependent_option` supports full :ref:`Condition Syntax`.

The ``<depends>`` parameter accepts a :ref:`semicolon-separated list <CMake
Language Lists>` of conditions.  CMake 3.21 and lower evaluates each
``condition`` as ``if(${condition})``, which does not properly handle
conditions with nested paren groups.  CMake 3.22 and above instead prefer
to evaluate each ``condition`` as ``if(<condition>)``, where ``<condition>``
is re-parsed as if literally written in a call to :command:`if`.  This
allows expressions like::

  "A AND (B OR C)"

but requires expressions like::

  "FOO MATCHES (UPPER|lower)"

to be re-written as::

  "FOO MATCHES \"(UPPER|lower)\""

Policy ``CMP0127`` provides compatibility for projects that have not
been updated to expect the new behavior.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.22
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0128
-------

.. versionadded:: 3.22

When this policy is set to ``NEW``:

* :prop_tgt:`<LANG>_EXTENSIONS` is initialized to
  :variable:`CMAKE_<LANG>_EXTENSIONS` if set, otherwise falling back to
  :variable:`CMAKE_<LANG>_EXTENSIONS_DEFAULT`.

* Extensions are correctly enabled/disabled if :prop_tgt:`<LANG>_STANDARD` is
  unset or satisfied by the default.

* Standard mode-affecting flags aren't added unless necessary to achieve the
  specified mode.

The ``OLD`` behavior:

* Initializes :prop_tgt:`<LANG>_EXTENSIONS` to
  :variable:`CMAKE_<LANG>_EXTENSIONS` if set, otherwise falling back to ``ON``.

* Always adds a flag if :prop_tgt:`<LANG>_STANDARD` is set and
  :prop_tgt:`<LANG>_STANDARD_REQUIRED` is ``OFF``.

* If :prop_tgt:`<LANG>_STANDARD` is unset:

  * Doesn't disable extensions even if :prop_tgt:`<LANG>_EXTENSIONS` is
    ``OFF``.

  * Fails to enable extensions if :prop_tgt:`<LANG>_EXTENSIONS` is ``ON``
    except for the ``IAR`` compiler.

Code may need to be updated for the ``NEW`` behavior in the following cases:

* If a standard mode flag previously overridden by CMake's and not used during
  compiler detection now takes effect due to CMake no longer adding one as the
  default detected is appropriate.

  Such code should be converted to either:

  * Use :prop_tgt:`<LANG>_STANDARD` and :prop_tgt:`<LANG>_EXTENSIONS` instead
    of manually adding flags.

  * Or ensure the manually-specified flags are used during compiler detection.

* If extensions were disabled without :prop_tgt:`<LANG>_STANDARD` being set
  CMake previously wouldn't actually disable extensions.

  Such code should be updated to not disable extensions if they are required.

* If extensions were enabled/disabled when :prop_tgt:`<LANG>_STANDARD` was
  satisfied by the compiler's default CMake previously wouldn't actually
  enable/disable extensions.

  Such code should be updated to set the correct extensions mode.

If compiler flags affecting the standard mode are used during compiler
detection (for example in :manual:`a toolchain file <cmake-toolchains(7)>`
using :variable:`CMAKE_<LANG>_FLAGS_INIT`) then they will affect the detected
default :variable:`standard <CMAKE_<LANG>_STANDARD_DEFAULT>` and
:variable:`extensions <CMAKE_<LANG>_EXTENSIONS_DEFAULT>`.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.22
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn by default
.. include:: STANDARD_ADVICE.txt

See documentation of the
:variable:`CMAKE_POLICY_WARNING_CMP0128 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
variable to control the warning.

.. include:: DEPRECATED.txt


code:
CMP0129
-------

.. versionadded:: 3.23

Compiler id for MCST LCC compilers is now ``LCC``, not ``GNU``.

CMake 3.23 and above recognize MCST LCC compiler as a different from ``GNU``,
with its own command line and set of capabilities.
CMake now prefers to present this to projects by setting the
:variable:`CMAKE_<LANG>_COMPILER_ID` variable to ``LCC`` instead
of ``GNU``. However, existing projects may assume the compiler id for
LCC is ``GNU`` as it was in CMake versions prior to 3.23.
Therefore this policy determines for MCST LCC compiler which
compiler id to report in the :variable:`CMAKE_<LANG>_COMPILER_ID`
variable after language ``<LANG>`` is enabled by the :command:`project`
or :command:`enable_language` command.  The policy must be set prior
to the invocation of either command.

The ``OLD`` behavior for this policy is to use compiler id ``GNU`` (and set
:variable:`CMAKE_<LANG>_COMPILER_VERSION` to the supported GNU compiler version.)
``NEW`` behavior for this policy is to use compiler id ``LCC``, and set
:variable:`CMAKE_<LANG>_SIMULATE_ID` to ``GNU``, and
:variable:`CMAKE_<LANG>_SIMULATE_VERSION` to the supported GNU compiler version.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.23
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn by default
.. include:: STANDARD_ADVICE.txt

See documentation of the
:variable:`CMAKE_POLICY_WARNING_CMP0129 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
variable to control the warning.

.. include:: DEPRECATED.txt


code:
CMP0130
-------

.. versionadded:: 3.24

:command:`while` diagnoses condition evaluation errors.

CMake 3.23 and below accidentally tolerated errors encountered while
evaluating the condition passed to the :command:`while` command
(but not the :command:`if` command).  For example, the code

.. code-block:: cmake

  set(paren "(")
  while(${paren})
  endwhile()

creates an unbalanced parenthesis during condition evaluation.

CMake 3.24 and above prefer to diagnose such errors.  This policy
provides compatibility for projects that have not been updated to
fix their condition errors.

The ``OLD`` behavior for this policy is to ignore errors in
:command:`while` conditions.  The ``NEW`` behavior for this
policy is to diagnose errors in :command:`while` conditions.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.24
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0131
-------

.. versionadded:: 3.24

:prop_tgt:`LINK_LIBRARIES` supports the :genex:`$<LINK_ONLY:...>`
generator expression.

CMake 3.23 and below documented the :genex:`$<LINK_ONLY:...>` generator
expression only for use in :prop_tgt:`INTERFACE_LINK_LIBRARIES`.
When used in :prop_tgt:`LINK_LIBRARIES`, the content guarded inside
:genex:`$<LINK_ONLY:...>` was always used, even when collecting non-linking
usage requirements such as :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`.

CMake 3.24 and above prefer to support :genex:`$<LINK_ONLY:...>`, when
used in :prop_tgt:`LINK_LIBRARIES`, by using the guarded content only
for link dependencies and not other usage requirements.  This policy
provides compatibility for projects that have not been updated to
account for this change.

The ``OLD`` behavior for this policy is to use :prop_tgt:`LINK_LIBRARIES`
content guarded by :genex:`$<LINK_ONLY:...>` even for non-linking
usage requirements.  The ``NEW`` behavior for this policy is to use
the guarded content only for link dependencies.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.24
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0132
-------

.. versionadded:: 3.24

Apart from when using the Xcode generator and some Visual Studio generators,
CMake 3.23 and below will set environment variables like :envvar:`CC`,
:envvar:`CXX`, etc. when the corresponding language is enabled.
This only occurs on the very first time CMake is run in a build directory,
and the environment variables are only defined at configure time, not build
time. On subsequent CMake runs, these environment variables are not set,
opening up the opportunity for different behavior between the first and
subsequent CMake runs. CMake 3.24 and above prefer to not set these
environment variables when a language is enabled, even on the first run in
a build directory.

The ``OLD`` behavior for this policy sets the relevant environment variable
on the first run when a language is enabled. The ``NEW`` behavior for this
policy does not set any such environment variables.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.24
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0133
-------

.. versionadded:: 3.24

The :module:`CPack` module disables SLA by default in the
:cpack_gen:`CPack DragNDrop Generator`.

The :cpack_gen:`CPack DragNDrop Generator` in CMake 3.22 and below attach a
Software License Agreement (SLA) to ``.dmg`` files using the file specified
by :variable:`CPACK_RESOURCE_FILE_LICENSE`, if set to a non-default value.
macOS 12.0 deprecated the tools used to do this, so CMake 3.23 added
the :variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` option to
control the behavior.  CMake 3.23 enables that option by default for
compatibility with older versions. CMake 3.24 and above prefer to *not*
enable the :variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` option by
default. This policy provides compatibility with projects that have not
been updated to account for the lack of a SLA in their ``.dmg`` packages.

The ``OLD`` behavior for this policy is to enable
:variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` by default.
The ``NEW`` behavior for this policy is to not enable it by default.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.24
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn by default
.. include:: STANDARD_ADVICE.txt

See documentation of the
:variable:`CMAKE_POLICY_WARNING_CMP0133 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
variable to control the warning.

.. include:: DEPRECATED.txt


code:
CMP0134
-------

.. versionadded:: 3.24

The default registry view is ``TARGET`` for the :command:`find_file`,
:command:`find_path`, :command:`find_library`, and :command:`find_package`
commands and ``BOTH`` for the :command:`find_program` command.

The default registry views in CMake 3.23 and below are selected using the
following rules:

* if :variable:`CMAKE_SIZEOF_VOID_P` has value ``8``:

  * Use view ``64`` for all ``find_*`` commands except :command:`find_program`
    command.
  * Use view ``64_32`` for :command:`find_program` command.

* if :variable:`CMAKE_SIZEOF_VOID_P` has value ``4`` or is undefined:

  * Use view ``32`` for all ``find_*`` commands except :command:`find_program`
    command.
  * Use view ``32_64`` for :command:`find_program` command.

The ``OLD`` behavior for this policy is to use registry views ``64`` and
``64_32`` or ``32_64`` and ``32`` as default, depending of
:variable:`CMAKE_SIZEOF_VOID_P` variable value.
The ``NEW`` behavior for this policy is to use registry views ``TARGET`` and
``BOTH`` as default.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.24
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0135
-------

.. versionadded:: 3.24

When using the ``URL`` download method with the :command:`ExternalProject_Add`
command, CMake 3.23 and below sets the timestamps of the extracted contents
to the same as the timestamps in the archive. When the ``URL`` changes, the
new archive is downloaded and extracted, but the timestamps of the extracted
contents might not be newer than the previous contents. Anything that depends
on the extracted contents might not be rebuilt, even though the contents may
change.

CMake 3.24 and above prefers to set the timestamps of all extracted contents
to the time of the extraction. This ensures that anything that depends on the
extracted contents will be rebuilt whenever the ``URL`` changes.

The ``DOWNLOAD_EXTRACT_TIMESTAMP`` option to the
:command:`ExternalProject_Add` command can be used to explicitly specify how
timestamps should be handled. When ``DOWNLOAD_EXTRACT_TIMESTAMP`` is not
given, this policy controls the default behavior. The ``OLD`` behavior for
this policy is to restore the timestamps from the archive. The ``NEW``
behavior sets the timestamps of extracted contents to the time of extraction.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.24
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0136
-------

.. versionadded:: 3.24

Watcom runtime library flags are selected by an abstraction.

Compilers targeting the Watcom ABI have flags to select the Watcom runtime
library.

In CMake 3.23 and below, Watcom runtime library selection flags are added to
the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache entries by CMake
automatically.  This allows users to edit their cache entries to adjust the
flags.  However, the presence of such default flags is problematic for
projects that want to choose a different runtime library programmatically.
In particular, it requires string editing of the
:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variables with knowledge of the
CMake builtin defaults so they can be replaced.

CMake 3.24 and above prefer to leave the Watcom runtime library selection flags
out of the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` values and instead
offer a first-class abstraction.  The :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY`
variable and :prop_tgt:`WATCOM_RUNTIME_LIBRARY` target property may be set to
select the Watcom runtime library.  If they are not set then CMake uses the
default value ``MultiThreadedDLL`` on Windows and ``SingleThreaded`` on other
platforms, which is equivalent to the original flags.

This policy provides compatibility with projects that have not been updated
to be aware of the abstraction.  The policy setting takes effect as of the
first :command:`project` or :command:`enable_language` command that enables
a language whose compiler targets the Watcom ABI.

.. note::

  Once the policy has taken effect at the top of a project, that choice
  must be used throughout the tree.  In projects that have nested projects
  in subdirectories, be sure to convert everything together.

The ``OLD`` behavior for this policy is to place Watcom runtime library
flags in the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache
entries and ignore the :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY` abstraction.
The ``NEW`` behavior for this policy is to *not* place Watcom runtime
library flags in the default cache entries and use the abstraction instead.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.24
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0137
-------

.. versionadded:: 3.24

:command:`try_compile` passes platform variables in project mode.

The :command:`try_compile` command :ref:`source file <Try Compiling Source
Files>` signature propagates CMake variables containing platform settings,
and those specified by the :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES`
variable, into the generated test project.  This helps the test project drive
the toolchain the same way the calling project will.  In CMake 3.23 and below,
the :ref:`whole-project <Try Compiling Whole Projects>` signature does not
propagate platform variables automatically.  CMake 3.24 and above prefer to
propagate platform variables in the :ref:`whole-project <Try Compiling Whole
Projects>` signature.  This policy provides compatibility with projects that
have not been updated to expect the behavior.

The ``OLD`` behavior for this policy is to not pass any additional variables to
the :ref:`whole-project <Try Compiling Whole Projects>` signature.
The ``NEW`` behavior for this policy is to pass the same variables that the
:ref:`source file <Try Compiling Source Files>` signature does.

Regardless of the policy setting, the
:variable:`CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable may be set
to suppress passing the platform variables through either signature.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.24
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0138
-------

.. versionadded:: 3.24

:module:`CheckIPOSupported` uses flags from calling project.

The :module:`CheckIPOSupported` module :command:`check_ipo_supported`
command compiles a test project to determine whether the toolchain
supports :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION`.  CMake 3.23 and
below run the check with the default values of the
:variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`
variables for the current environment and toolchain settings.
However, some projects may modify these flag variables to add
flags that affect availability of the toolchain's IPO features.
CMake 3.24 and above prefer to honor the calling project's values
for these variables.  This policy provides compatibility for projects
that have not been updated to expect this behavior.

The ``OLD`` behavior for this policy is to ignore the calling
project's values of :variable:`CMAKE_<LANG>_FLAGS` and
:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`.  The ``NEW`` behavior
for this policy is to use the values of those variables as
compiler flags in the test project.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.24
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0139
-------

.. versionadded:: 3.24

The :command:`if` command supports path comparisons using ``PATH_EQUAL``
operator.

The ``OLD`` behavior for this policy is to ignore the ``PATH_EQUAL`` operator.
The ``NEW`` behavior is to interpret the ``PATH_EQUAL`` operator.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.24
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0140
-------

.. versionadded:: 3.25

The :command:`return` command checks its parameters.

The ``OLD`` behavior for this policy is to ignore any parameters given to the
command.
The ``NEW`` behavior is to check the validity of the parameters.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.25
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0141
-------

.. versionadded:: 3.25

MSVC debug information format flags are selected by an abstraction.

Compilers targeting the MSVC ABI have flags to select the debug information
format. Debug information format selection typically varies with build
configuration.

In CMake 3.24 and below, debug information format flags are added to
the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache entries by CMake
automatically.  This allows users to edit their cache entries to adjust the
flags.  However, the presence of such default flags is problematic for
projects that want to choose a different runtime library programmatically.
In particular, it requires string editing of the
:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variables with knowledge of the
CMake builtin defaults so they can be replaced.

CMake 3.25 and above prefer to leave the debug information format flags
out of the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` values and instead
offer a first-class abstraction.  The
:variable:`CMAKE_MSVC_DEBUG_INFORMATION_FORMAT` variable and
:prop_tgt:`MSVC_DEBUG_INFORMATION_FORMAT` target property may be set to
select the MSVC debug information format.  If they are not set, CMake
enables debug information in debug configurations using the default value
``$<$<CONFIG:Debug,RelWithDebInfo>:ProgramDatabase>``, if supported by the
compiler, and otherwise ``$<$<CONFIG:Debug,RelWithDebInfo>:Embedded>``.

This policy provides compatibility with projects that have not been updated
to be aware of the abstraction.  The policy setting takes effect as of the
first :command:`project` or :command:`enable_language` command that enables
a language whose compiler targets the MSVC ABI.

.. note::

  Once the policy has taken effect at the top of a project, that choice
  will be used throughout the tree.  In projects that have nested projects
  in subdirectories, be sure to confirm if everything is working with the
  selected policy behavior.

The ``OLD`` behavior for this policy is to place MSVC debug information
format flags in the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache
entries and ignore the :variable:`CMAKE_MSVC_DEBUG_INFORMATION_FORMAT`
abstraction.  The ``NEW`` behavior for this policy is to *not* place MSVC
debug information format flags in the default cache entries and use
the abstraction instead.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.25
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0142
-------

.. versionadded:: 3.25

The :generator:`Xcode` generator does not append per-config suffixes to
library search paths.

In CMake 3.24 and below, the :generator:`Xcode` generator preceded each
entry of a library search path with a copy of itself appended with
``$(CONFIGURATION)$(EFFECTIVE_PLATFORM_NAME)``.  This was left from
very early versions of CMake in which per-config directories were not well
modeled.  Such paths often do not exist, resulting in warnings from the
toolchain.  CMake 3.25 and above prefer to not add such library search
paths.  This policy provides compatibility for projects that may have been
accidentally relying on the old behavior.

The ``OLD`` behavior for this policy is to append
``$(CONFIGURATION)$(EFFECTIVE_PLATFORM_NAME)`` to all library search paths.
The ``NEW`` behavior is to not modify library search paths.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.25
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0143
-------

.. versionadded:: 3.26

:prop_gbl:`USE_FOLDERS` global property is treated as ``ON`` by default.

When using CMake 3.25 or earlier, :prop_gbl:`USE_FOLDERS` is treated
as ``OFF`` by default unless projects enable the feature.  For example:

.. code-block:: cmake

  cmake_minimum_required(VERSION 3.25)
  project(foobar LANGUAGES CXX)
  set_property(GLOBAL PROPERTY USE_FOLDERS ON)

CMake 3.26 and later prefer to enable the feature by default.

Note that it is the policy setting at the `end` of the top level
``CMakeLists.txt`` file that matters.  The policy setting applies globally
to the whole project.

This policy provides compatibility with projects that have not been updated
to expect enabling of folders.  Enabling folders causes projects to appear
differently in IDEs.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.26
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0144
-------

.. versionadded:: 3.27

:command:`find_package` uses upper-case ``<PACKAGENAME>_ROOT`` variables.

In CMake 3.27 and above the :command:`find_package(<PackageName>)` command now
searches prefixes specified by the upper-case :variable:`<PACKAGENAME>_ROOT`
CMake variable and the :envvar:`<PACKAGENAME>_ROOT` environment variable
in addition to the case-preserved :variable:`<PackageName>_ROOT` and
:envvar:`<PackageName>_ROOT` variables used since policy :policy:`CMP0074`.
This policy provides compatibility with projects that have not been
updated to avoid using ``<PACKAGENAME>_ROOT`` variables for other purposes.

The ``OLD`` behavior for this policy is to ignore ``<PACKAGENAME>_ROOT``
variables if the original ``<PackageName>`` has lower-case characters.
The ``NEW`` behavior for this policy is to use ``<PACKAGENAME>_ROOT``
variables.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.27
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0145
-------

.. versionadded:: 3.27

The :module:`Dart` and :module:`FindDart` modules are removed.

These modules were added very early in CMake's development to support
driving tests with a "DART" tool, but DART has not been distributed or
maintained for many years.  Projects would ``include(Dart)`` to use it,
and the ``Dart`` module would run ``find_package(Dart)`` internally.
Since :manual:`ctest(1)` was created, the ``Dart`` module has just been
a compatibility shim that finds ``Dart`` to support some legacy
functionality and then forwards to the :module:`CTest` module.

CMake 3.27 and above prefer to not provide the :module:`Dart` or
:module:`FindDart` modules.  This policy provides compatibility for
projects that have not been ported away from them.  Projects using the
``Dart`` module should be updated to use the :module:`CTest` module directly.

The ``OLD`` behavior of this policy is for ``include(Dart)`` and
``find_package(Dart)`` to load the deprecated modules.  The ``NEW``
behavior is for uses of the modules to fail as if they do not exist.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.27
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0146
-------

.. versionadded:: 3.27

The :module:`FindCUDA` module is removed.

The :module:`FindCUDA` module has been deprecated since CMake 3.10.
CMake 3.27 and above prefer to not provide the module.
This policy provides compatibility for projects that have not been
ported away from it.

Projects using the :module:`FindCUDA` module should be updated to use
CMake's first-class ``CUDA`` language support.  List ``CUDA`` among the
languages named in the top-level call to the :command:`project` command,
or call the :command:`enable_language` command with ``CUDA``.
Then one can add CUDA (``.cu``) sources directly to targets,
similar to other languages.

The ``OLD`` behavior of this policy is for ``find_package(CUDA)`` to
load the deprecated module.  The ``NEW`` behavior is for uses of the
module to fail as if it does not exist.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.27
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0147
-------

.. versionadded:: 3.27

:ref:`Visual Studio Generators` build custom commands in parallel.

Visual Studio 15.8 (2017) and newer support building custom commands in
parallel.  CMake 3.27 and above prefer to enable this behavior by adding
a ``BuildInParallel`` setting to custom commands in ``.vcxproj`` files.
This policy provides compatibility for projects that have not been updated
to expect this, e.g., because their custom commands were accidentally
relying on serial execution by MSBuild.

The ``OLD`` behavior for this policy is to not add ``BuildInParallel``.
The ``NEW`` behavior for this policy is to add ``BuildInParallel`` for
VS 15.8 and newer.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.27
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0148
-------

.. versionadded:: 3.27

The :module:`FindPythonInterp` and :module:`FindPythonLibs` modules are removed.

These modules have been deprecated since CMake 3.12.
CMake 3.27 and above prefer to not provide the modules.
This policy provides compatibility for projects that have not been
ported away from them.

Projects using the :module:`FindPythonInterp` and/or :module:`FindPythonLibs`
modules should be updated to use one of their replacements:

* :module:`FindPython3`
* :module:`FindPython2`
* :module:`FindPython`

The ``OLD`` behavior of this policy is for ``find_package(PythonInterp)``
and ``find_package(PythonLibs)`` to load the deprecated modules.  The ``NEW``
behavior is for uses of the modules to fail as if they do not exist.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.27
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0149
-------

.. versionadded:: 3.27

:ref:`Visual Studio Generators` select latest Windows SDK by default.

Visual Studio Generators select a Windows SDK version to put in the
``WindowsTargetPlatformVersion`` setting in ``.vcxproj`` files.
CMake sets the :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION`
variable to the selected SDK version.

Prior to CMake 3.27, the SDK version was always selected by the value of
the :variable:`CMAKE_SYSTEM_VERSION` variable.  Users or toolchain files
could set that variable to one of the exact Windows SDK versions available
on the host system.  Since :variable:`CMAKE_SYSTEM_VERSION` defaults to
:variable:`CMAKE_HOST_SYSTEM_VERSION`, and it is not guaranteed that a
matching Windows SDK version is available, CMake had to fall back to
using the latest Windows SDK version if no exact match was available.
This approach was problematic:

* The latest Windows SDK might or might not be selected based on whether
  the host version of Windows happens to match an available SDK version.

* An old Windows SDK version might be selected that has not been updated
  for newer language standards such as C11.

CMake 3.27 and higher prefer to ignore the exact value of
:variable:`CMAKE_SYSTEM_VERSION` and by default select the latest SDK
version available.  An exact SDK version may be specified explicitly
using a ``version=`` field in the :variable:`CMAKE_GENERATOR_PLATFORM`
variable.  See :ref:`Visual Studio Platform Selection`.

This policy provides compatibility for projects, toolchain files, and
build scripts that have not been ported away from using
:variable:`CMAKE_SYSTEM_VERSION` to specify an exact SDK version.

.. note::

  This policy must be set before the first :command:`project` or
  :command:`enable_language` command invocation at the top of the
  project.  That is when :ref:`Visual Studio Generators` select a
  Windows SDK.

The ``OLD`` behavior for this policy is to use the exact value of
:variable:`CMAKE_SYSTEM_VERSION` if possible.  The ``NEW`` behavior
for this policy is to ignore it.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.27
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0150
-------

.. versionadded:: 3.27

:command:`ExternalProject_Add` and :command:`FetchContent_Declare` commands
treat relative ``GIT_REPOSITORY`` paths as being relative to the parent
project's remote.

Earlier versions of these commands always treated relative paths in
``GIT_REPOSITORY`` as local paths, but the base directory it was treated
as relative to was both undocumented and unintuitive.  The ``OLD`` behavior
for this policy is to interpret relative paths used for ``GIT_REPOSITORY``
as local paths relative to the following:

* The parent directory of ``SOURCE_DIR`` for :command:`ExternalProject_Add`.
* ``FETCHCONTENT_BASE_DIR`` for :command:`FetchContent_Declare`.

The ``NEW`` behavior is to determine the remote from the parent project and
interpret the path relative to that remote.  The value of
:variable:`CMAKE_CURRENT_SOURCE_DIR` when :command:`ExternalProject_Add` or
:command:`FetchContent_Declare` is called determines the parent project.
The remote is selected according to the following (the first match is used):

* If the parent project is checked out on a branch with an upstream remote
  defined, use that remote.
* If only one remote is defined, use that remote.
* If multiple remotes are defined and one of them is named ``origin``, use
  ``origin``'s remote but also issue a warning.

If an appropriate remote cannot be determined from the above, a fatal error
will be raised.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.27
.. |WARNS_OR_DOES_NOT_WARN| replace::
   warns when a relative path is encountered
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0151
-------

.. versionadded:: 3.27

AUTOMOC include directory is a system include directory by default.

Headers generated for :ref:`Qt AUTOMOC` are placed in target-specific include
directories.  CMake 3.26 and older added these as normal include directories.
CMake 3.27 and newer prefer to add them as system include directories.
This policy provides compatibility for projects that have not been updated
to expect this.

If the :prop_tgt:`AUTOGEN_USE_SYSTEM_INCLUDE` target property is set,
perhaps via the :variable:`CMAKE_AUTOGEN_USE_SYSTEM_INCLUDE` variable,
then its value is used regardless of the setting of this policy.

The ``OLD`` behavior for this policy is to add autogen include directory to
the target's include directories.
The ``NEW`` behavior for this policy is to add autogen include directory to
the target's system include directories.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.27
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0152
-------

.. versionadded:: 3.28

:command:`file(REAL_PATH)` resolves symlinks before collapsing ../ components.

In CMake 3.27 and below, :command:`file(REAL_PATH)` collapsed any ``../``
components in a path before resolving symlinks.  This produced incorrect
results when the ``../`` collapsed away a symlink.

The ``OLD`` behavior for this policy is to collapse ``../`` components before
resolving symlinks.
The ``NEW`` behavior for this policy is to resolve all symlinks before
collapsing ``../`` components.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.28
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0153
-------

.. versionadded:: 3.28

The :command:`exec_program` command should not be called.

This command has long been superseded by the :command:`execute_process`
command and has been deprecated since CMake 3.0.

.. |disallowed_version| replace:: 3.28
.. include:: DISALLOWED_COMMAND.txt

.. include:: DEPRECATED.txt


code:
CMP0154
-------

.. versionadded:: 3.28

Generated files are private by default in targets using :ref:`file sets`.

CMake 3.27 and below assume that any file generated as an output or byproduct
of :command:`add_custom_command` or :command:`add_custom_target` may be a
public header file meant for inclusion by dependents' source files.  This
requires :ref:`Ninja Generators` to add conservative order-only dependencies
that prevent a target's source files from compiling before custom commands
from the target's dependencies are finished, even if those custom commands
only produce sources private to their own target.

:ref:`File Sets`, introduced by CMake 3.23, provide a way to express the
visibility of generated header files.  CMake 3.28 and above prefer to
assume that, in targets using file sets, generated files are private to
their own target by default.  Generated public headers must be specified
as members of a ``PUBLIC`` (or ``INTERFACE``) ``FILE_SET``, typically of
type ``HEADERS``.  With this information, :ref:`Ninja Generators` may omit
the above-mentioned conservative dependencies and produce more efficient
build graphs.

Additionally, if the custom command's output is a member of a file set of type
``CXX_MODULES``, it will additionally not be required to exist before
compiling other sources in the same target.  Since these files should not be
included at compile time directly, they may not be implicitly required to
exist for other compilation rules.

This policy provides compatibility for projects using file sets in targets
with generated header files that have not been updated.  Such projects
should be updated to express generated public headers in a file set.
For example:

.. code-block:: cmake

  add_custom_command(
    OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.h
    ...
  )
  target_sources(foo
    PUBLIC FILE_SET HEADERS
      BASE_DIRS ${CMAKE_CURRENT_BINARY_DIR}
      FILES     ${CMAKE_CURRENT_BINARY_DIR}/foo.h
  )

The ``OLD`` behavior for this policy is to assume generated files are
public, even in targets using file sets, and for :ref:`Ninja Generators`
to produce conservative build graphs.  The ``NEW`` behavior for this
policy is to assume generated files are private in targets using file sets,
and for :ref:`Ninja Generators` to produce more efficient build graphs.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.28
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0155
-------

.. versionadded:: 3.28

C++ sources in targets with at least C++20 are scanned for imports
when supported.

CMake 3.27 and below assume that C++ sources do not ``import`` modules.
CMake 3.28 and above prefer to assume that C++ sources in targets using C++20
or higher might ``import`` modules, and must be scanned before compiling,
unless explicitly disabled.  This policy provides compatibility for projects
that use C++20 or higher, without modules, that have not been updated to turn
off scanning, e.g., via the :variable:`CMAKE_CXX_SCAN_FOR_MODULES` variable.
See the :manual:`cmake-cxxmodules(7)` manual for more details on C++ module
support.

The ``OLD`` behavior for this policy is to assume that C++ 20 and newer
sources do not import modules.  The ``NEW`` behavior for this policy is to
assume that C++ 20 and newer files may import modules if the compiler
understands how to scan for their dependencies, and need to be scanned.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.28
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0156
-------

.. versionadded:: 3.29

De-duplicate libraries on link lines based on linker capabilities.

Traditional linkers maintain a set of undefined symbols during linking. The
linker processes each file in the order in which it appears on the command
line, until the set of undefined symbols becomes empty. An object file is
linked into the output object when it is encountered, with its undefined
symbols added to the set. Upon encountering an archive file a traditional
linker searches the objects contained therein, and processes those that satisfy
symbols in the unresolved set.

Handling mutually dependent archives may be awkward when using a traditional
linker. Archive files may have to be specified multiple times.

Some linkers (for instance Apple or Windows linkers, as well as ``LLVM LLD``)
records all symbols found in objects and archives as it iterates over command
line arguments. When one of these linkers encounters an undefined symbol that
can be resolved by an object file contained in a previously processed archive
file, it immediately extracts and links it into the output object.

CMake 3.28 and below may generate link lines that repeat static libraries as
a traditional linker would need, even when using a linker does not need it.
They may also de-duplicate shared libraries by keeping their last occurrence,
which on Windows platforms can change DLL load order.

CMake 3.29 and above prefer to apply different strategies based on linker
capabilities.  So, when targeting Apple and Windows platforms, all
libraries are de-duplicated.  Moreover, on Windows platforms, libraries
are de-duplicated by keeping their fist occurrence, thus respecting the
project-specified order.  This policy provides compatibility with projects
that have not been updated to expect the latter behavior.

The ``OLD`` behavior for this policy is to always repeat static libraries
as if using a traditional linker, and always de-duplicate shared libraries
by keeping the last occurrence of each.  The ``NEW`` behavior for this policy
is to apply different strategies based on linker capabilities.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.29
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0157
-------

.. versionadded:: 3.29

Swift compilation mode is selected by an abstraction.

The Swift compiler can compile modules in different modes. The desired build
mode depends whether the developer is iterating and wants to incrementally make
changes, or if they are building a release for distribution and want more
optimizations applied to the resulting binary.

CMake versions 3.26 through 3.28 build Swift binaries with whole-module
optimizations enabled when configured in a non-debug build type.
For CMake versions earlier than 3.26, the developer needs to specify
the necessary flag manually for the :ref:`Ninja Generators`, and cannot
not specify whole-module optimizations to the :generator:`Xcode` generator.

CMake versions 3.29 and above prefer to set the compilation mode using
the :prop_tgt:`Swift_COMPILATION_MODE` target property, which can be
initialized by the :variable:`CMAKE_Swift_COMPILATION_MODE` variable.

This policy provides compatibility for projects that have not been updated.
The policy setting takes effect as of the first :command:`project` or
:command:`enable_language` command that enables the ``Swift`` language.

.. note::

  Once the policy has taken effect at the top of a project, that choice
  must be used throughout the tree. In projects that have nested projects
  in subdirectories, be sure to convert everything together.

The ``OLD`` behavior for this policy builds all Swift targets in
``wholemodule`` mode for non-debug configurations.  :ref:`Ninja Generators`
prepend the ``-wmo`` flag to the default set of Swift flags.
The :generator:`Xcode` generator sets the ``SWIFT_COMPILATION_MODE``
attribute to ``wholemodule`` in the generated Xcode project file.

The ``NEW`` behavior for this policy is to apply the compilation mode specified
in the :prop_tgt:`Swift_COMPILATION_MODE` target property, initialized as each
target is created by the :variable:`CMAKE_Swift_COMPILATION_MODE` variable.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.29
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0158
-------

.. versionadded:: 3.29

:command:`add_test` honors :variable:`CMAKE_CROSSCOMPILING_EMULATOR` only
when :variable:`cross-compiling <CMAKE_CROSSCOMPILING>`.

In CMake 3.28 and below, :command:`add_test` unconditionally used the
:prop_tgt:`CROSSCOMPILING_EMULATOR` target property (initialized by the
:variable:`CMAKE_CROSSCOMPILING_EMULATOR` variable) to run test commands
naming executable targets.  CMake 3.29 and above prefer to use the emulator
only when the :variable:`CMAKE_CROSSCOMPILING` variable is enabled.  The
:variable:`CMAKE_TEST_LAUNCHER` variable may be used instead when not
cross-compiling.  This policy provides compatibility for projects that
have not been updated.

The ``OLD`` behavior for this policy is for :command:`add_test` to use
the :prop_tgt:`CROSSCOMPILING_EMULATOR` target property unconditionally.
The ``NEW`` behavior for this policy is for :command:`add_test` to use
the :prop_tgt:`CROSSCOMPILING_EMULATOR` target property only when
:variable:`cross-compiling <CMAKE_CROSSCOMPILING>`.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.29
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0159
-------

.. versionadded:: 3.29

:command:`file(STRINGS)` with ``REGEX`` updates :variable:`CMAKE_MATCH_<n>`.

In CMake 3.28 and below the :command:`file(STRINGS)` command's ``REGEX``
option does not affect :variable:`CMAKE_MATCH_<n>` variables.  CMake 3.29
and above prefer to update the :variable:`CMAKE_MATCH_<n>` variables using
captures from the last match in the file, similar to the
:command:`string(REGEX MATCHALL)` command.  This policy provides
compatibility for projects that have not been updated to expect the behavior.

The ``OLD`` behavior for this policy is for :command:`file(STRINGS)` with
``REGEX`` to not store capture groups in :variable:`CMAKE_MATCH_<n>`
variables.  The ``NEW`` behavior is to store the capture groups.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.29
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0160
-------

.. versionadded:: 3.29

More read-only target properties now error when trying to set them.

The :command:`set_target_properties` and :command:`set_property` commands
are intended to error out on all read-only properties. However, CMake 3.28 and
below only did this for the following properties:

* :prop_tgt:`HEADER_SETS`
* :prop_tgt:`INTERFACE_HEADER_SETS`
* :prop_tgt:`IMPORTED_GLOBAL`
* :prop_tgt:`MANUALLY_ADDED_DEPENDENCIES`
* :prop_tgt:`NAME`
* :prop_tgt:`TYPE`

This policy enforces the read-only nature of the following target properties:

* :prop_tgt:`ALIAS_GLOBAL`
* :prop_tgt:`BINARY_DIR`
* :prop_tgt:`CXX_MODULE_SETS`
* :prop_tgt:`IMPORTED`
* :prop_tgt:`INTERFACE_CXX_MODULE_SETS`
* :prop_tgt:`LOCATION`
* :prop_tgt:`LOCATION_<CONFIG>`
* :prop_tgt:`SOURCE_DIR`

The ``OLD`` behavior for this policy is to only error out for the properties
:prop_tgt:`MANUALLY_ADDED_DEPENDENCIES`, :prop_tgt:`NAME`, and :prop_tgt:`TYPE`.
The ``NEW`` behavior for this policy is to error out on all target properties
that are documented as read-only.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.29
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt

.. include:: DEPRECATED.txt


code:
CMP0161
-------

.. versionadded:: 3.29

The :variable:`CPACK_PRODUCTBUILD_DOMAINS` variable defaults to true.

Before CMake 3.29, the :variable:`CPACK_PRODUCTBUILD_DOMAINS` variable is
unset by default.  When using the :cpack_gen:`CPack productbuild Generator`,
this disables the use of the ``domains`` attribute in the productbuild
Distribution XML, and falls back to the ``auth`` attribute instead.
These attributes control where a productbuild package is allowed to be
installed.  But the ``auth`` attribute has been deprecated by Apple,
so projects should migrate to using ``domains`` instead.

CMake 3.29 and above prefer to use a default value of true for
:variable:`CPACK_PRODUCTBUILD_DOMAINS`, which means ``domains`` will be used
by default unless the project explicitly sets
:variable:`CPACK_PRODUCTBUILD_DOMAINS` to false.
This policy provides compatibility with projects that enabled the
:cpack_gen:`CPack productbuild Generator`, but did not explicitly set
:variable:`CPACK_PRODUCTBUILD_DOMAINS`.

The ``OLD`` behavior for this policy is to leave
:variable:`CPACK_PRODUCTBUILD_DOMAINS` unset if it hasn't been set.
The ``NEW`` behavior for this policy is to use a default value of true for
:variable:`CPACK_PRODUCTBUILD_DOMAINS`.

.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.29
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
Note that a warning will only be emitted if the
:variable:`CPACK_BINARY_PRODUCTBUILD <CPACK_BINARY_<GENNAME>>` variable is
set to true and the project is being built for an Apple platform.

.. include:: DEPRECATED.txt


code:
ADVANCED
--------

True if entry should be hidden by default in GUIs.

This is a boolean value indicating whether the entry is considered
interesting only for advanced configuration.  The :command:`mark_as_advanced`
command modifies this property.


code:
HELPSTRING
----------

Help associated with entry in GUIs.

This string summarizes the purpose of an entry to help users set it
through a CMake GUI.


code:
MODIFIED
--------

Internal management property.  Do not set or get.

This is an internal cache entry property managed by CMake to track
interactive user modification of entries.  Ignore it.


code:
STRINGS
-------

Enumerate possible ``STRING`` entry values for GUI selection.

For cache entries with type ``STRING``, this enumerates a set of values.
CMake GUIs may use this to provide a selection widget instead of a
generic string entry field.  This is for convenience only.  CMake does
not enforce that the value matches one of those listed.


code:
TYPE
----

Widget type for entry in GUIs.

Cache entry values are always strings, but CMake GUIs present widgets
to help users set values.  The GUIs use this property as a hint to
determine the widget type.  Valid ``TYPE`` values are:

::

  BOOL          = Boolean ON/OFF value.
  PATH          = Path to a directory.
  FILEPATH      = Path to a file.
  STRING        = Generic string value.
  INTERNAL      = Do not present in GUI at all.
  STATIC        = Value managed by CMake, do not change.
  UNINITIALIZED = Type not yet specified.

Generally the ``TYPE`` of a cache entry should be set by the command which
creates it ( :command:`set`, :command:`option`, :command:`find_library`, etc.).


code:
VALUE
-----

Value of a cache entry.

This property maps to the actual value of a cache entry.  Setting this
property always sets the value without checking, so use with care.


code:
ADDITIONAL_CLEAN_FILES
----------------------

.. versionadded:: 3.15

A :ref:`;-list <CMake Language Lists>` of files or directories that will be
removed as a part of the global ``clean`` target.  It is useful for
specifying generated files or directories that are used by multiple targets
or by CMake itself, or that are generated in ways which cannot be captured as
outputs or byproducts of custom commands.

If an additional clean file is specific to a single target only, then the
:prop_tgt:`ADDITIONAL_CLEAN_FILES` target property would usually be a better
choice than this directory property.

Relative paths are allowed and are interpreted relative to the
current binary directory.

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

This property only works for the :generator:`Ninja` and the Makefile
generators.  It is ignored by other generators.


code:
ADDITIONAL_MAKE_CLEAN_FILES
---------------------------

.. deprecated:: 3.15

  Use :prop_dir:`ADDITIONAL_CLEAN_FILES` instead.

Additional files to remove during the clean stage.

A :ref:`;-list <CMake Language Lists>` of files that will be removed as a
part of the ``make clean`` target.

Arguments to ``ADDITIONAL_MAKE_CLEAN_FILES`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.

This property only works for the Makefile generators.
It is ignored on other generators.


code:
BINARY_DIR
----------

.. versionadded:: 3.7

This read-only directory property reports absolute path to the binary
directory corresponding to the source on which it is read.


code:
BUILDSYSTEM_TARGETS
-------------------

.. versionadded:: 3.7

This read-only directory property contains a
:ref:`semicolon-separated list <CMake Language Lists>` of buildsystem targets added in the
directory by calls to the :command:`add_library`, :command:`add_executable`,
and :command:`add_custom_target` commands.  The list does not include any
:ref:`Imported Targets` or :ref:`Alias Targets`, but does include
:ref:`Interface Libraries`.  Each entry in the list is the logical name
of a target, suitable to pass to the :command:`get_property` command
``TARGET`` option.

See also the :prop_dir:`IMPORTED_TARGETS` directory property.


code:
CACHE_VARIABLES
---------------

List of cache variables available in the current directory.

This read-only property specifies the list of CMake cache variables
currently defined.  It is intended for debugging purposes.


code:
CLEAN_NO_CUSTOM
---------------

Set to true to tell :ref:`Makefile Generators` not to remove the outputs of
custom commands for this directory during the ``make clean`` operation.
This is ignored on other generators because it is not possible to implement.


code:
CMAKE_CONFIGURE_DEPENDS
-----------------------

Tell CMake about additional input files to the configuration process.
If any named file is modified the build system will re-run CMake to
re-configure the file and generate the build system again.

Specify files as a semicolon-separated list of paths.  Relative paths
are interpreted as relative to the current source directory.


code:
COMPILE_DEFINITIONS
-------------------

Preprocessor definitions for compiling a directory's sources.

This property specifies the list of options given so far to the
:command:`add_compile_definitions` (or :command:`add_definitions`) command.

The ``COMPILE_DEFINITIONS`` property may be set to a semicolon-separated
list of preprocessor definitions using the syntax ``VAR`` or ``VAR=value``.
Function-style definitions are not supported.  CMake will
automatically escape the value correctly for the native build system
(note that CMake language syntax may require escapes to specify some
values).

This property will be initialized in each directory by its value in the
directory's parent.

CMake will automatically drop some definitions that are not supported
by the native build tool.

.. versionadded:: 3.26
  Any leading ``-D`` on an item will be removed.

.. include:: /include/COMPILE_DEFINITIONS_DISCLAIMER.txt

Contents of ``COMPILE_DEFINITIONS`` may use "generator expressions" with
the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.

The corresponding :prop_dir:`COMPILE_DEFINITIONS_<CONFIG>` property may
be set to specify per-configuration definitions.  Generator expressions
should be preferred instead of setting the alternative property.


code:
COMPILE_DEFINITIONS_<CONFIG>
----------------------------

Ignored.  See CMake Policy :policy:`CMP0043`.

Per-configuration preprocessor definitions in a directory.

This is the configuration-specific version of :prop_dir:`COMPILE_DEFINITIONS`
where ``<CONFIG>`` is an upper-case name (ex. ``COMPILE_DEFINITIONS_DEBUG``).

This property will be initialized in each directory by its value in
the directory's parent.

Contents of ``COMPILE_DEFINITIONS_<CONFIG>`` may use "generator expressions"
with the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.

Generator expressions should be preferred instead of setting this property.


code:
COMPILE_OPTIONS
---------------

List of options to pass to the compiler.

This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of options
given so far to the :command:`add_compile_options` command.

This property is used to initialize the :prop_tgt:`COMPILE_OPTIONS` target
property when a target is created, which is used by the generators to set
the options for the compiler.

Contents of ``COMPILE_OPTIONS`` may use "generator expressions" with the
syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)` manual
for available expressions.  See the :manual:`cmake-buildsystem(7)` manual
for more on defining buildsystem properties.


code:
DEFINITIONS
-----------

For CMake 2.4 compatibility only.  Use :prop_dir:`COMPILE_DEFINITIONS`
instead.

This read-only property specifies the list of flags given so far to
the :command:`add_definitions` command.  It is intended for debugging
purposes.  Use the :prop_dir:`COMPILE_DEFINITIONS` directory property
instead.

This built-in read-only property does not exist if policy
:policy:`CMP0059` is set to ``NEW``.


code:
EXCLUDE_FROM_ALL
----------------

Set this directory property to a true value on a subdirectory to exclude
its targets from the "all" target of its ancestors.  If excluded, running
e.g. ``make`` in the parent directory will not build targets the
subdirectory by default.  This does not affect the "all" target of the
subdirectory itself.  Running e.g. ``make`` inside the subdirectory will
still build its targets.

If the :prop_tgt:`EXCLUDE_FROM_ALL` target property is set on a target
then its value determines whether the target is included in the "all"
target of this directory and its ancestors.


code:
IMPLICIT_DEPENDS_INCLUDE_TRANSFORM
----------------------------------

Specify ``#include`` line transforms for dependencies in a directory.

This property specifies rules to transform macro-like ``#include`` lines
during implicit dependency scanning of C and C++ source files.  The
list of rules must be semicolon-separated with each entry of the form
``A_MACRO(%)=value-with-%`` (the ``%`` must be literal).  During dependency
scanning occurrences of ``A_MACRO(...)`` on ``#include`` lines will be
replaced by the value given with the macro argument substituted for
``%``.  For example, the entry

::

  MYDIR(%)=<mydir/%>

will convert lines of the form

::

  #include MYDIR(myheader.h)

to

::

  #include <mydir/myheader.h>

allowing the dependency to be followed.

This property applies to sources in all targets within a directory.
The property value is initialized in each directory by its value in
the directory's parent.


code:
IMPORTED_TARGETS
----------------

.. versionadded:: 3.21

This read-only directory property contains a
:ref:`semicolon-separated list <CMake Language Lists>` of
:ref:`Imported Targets` added in the directory by calls to the
:command:`add_library` and :command:`add_executable` commands.
Each entry in the list is the logical name of a target, suitable
to pass to the :command:`get_property` command ``TARGET`` option
when called in the same directory.

See also the :prop_dir:`BUILDSYSTEM_TARGETS` directory property.


code:
INCLUDE_DIRECTORIES
-------------------

List of preprocessor include file search directories.

This property specifies the list of directories given so far to the
:command:`include_directories` command.

This property is used to populate the :prop_tgt:`INCLUDE_DIRECTORIES`
target property, which is used by the generators to set the include
directories for the compiler.

In addition to accepting values from that command, values may be set
directly on any directory using the :command:`set_property` command, and can be
set on the current directory using the :command:`set_directory_properties`
command.  A directory gets its initial value from its parent directory if it has
one.  The initial value of the :prop_tgt:`INCLUDE_DIRECTORIES` target property
comes from the value of this property.  Both directory and target property
values are adjusted by calls to the :command:`include_directories` command.
Calls to :command:`set_property` or :command:`set_directory_properties`,
however, will update the directory property value without updating target
property values.  Therefore direct property updates must be made before
calls to :command:`add_executable` or :command:`add_library` for targets
they are meant to affect.

The target property values are used by the generators to set the
include paths for the compiler.

Contents of ``INCLUDE_DIRECTORIES`` may use "generator expressions" with
the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.


code:
INCLUDE_REGULAR_EXPRESSION
--------------------------

Include file scanning regular expression.

This property specifies the regular expression used during
dependency scanning to match include files that should be followed.
See the :command:`include_regular_expression` command for a high-level
interface to set this property.


code:
INTERPROCEDURAL_OPTIMIZATION
----------------------------

This directory property does not exist anymore.

See the target property :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` instead.


code:
INTERPROCEDURAL_OPTIMIZATION_<CONFIG>
-------------------------------------

This directory property does not exist anymore.

See the target property :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION_<CONFIG>` instead.


code:
LABELS
------

.. versionadded:: 3.10

Specify a list of text labels associated with a directory and all of its
subdirectories. This is equivalent to setting the :prop_tgt:`LABELS` target
property and the :prop_test:`LABELS` test property on all targets and tests in
the current directory and subdirectories. Note: Launchers must enabled to
propagate labels to targets.

The :variable:`CMAKE_DIRECTORY_LABELS` variable can be used to initialize this
property.

The list is reported in dashboard submissions.


code:
LINK_DIRECTORIES
----------------

List of linker search directories.

This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of directories
and is typically populated using the :command:`link_directories` command.
It gets its initial value from its parent directory, if it has one.

The directory property is used to initialize the :prop_tgt:`LINK_DIRECTORIES`
target property when a target is created.  That target property is used
by the generators to set the library search directories for the linker.

Contents of ``LINK_DIRECTORIES`` may use "generator expressions" with
the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.


code:
LINK_OPTIONS
------------

.. versionadded:: 3.13

List of options to use for the link step of shared library, module
and executable targets as well as the device link step.

This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of options
given so far to the :command:`add_link_options` command.

This property is used to initialize the :prop_tgt:`LINK_OPTIONS` target
property when a target is created, which is used by the generators to set
the options for the compiler.

Contents of ``LINK_OPTIONS`` may use "generator expressions" with the
syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)` manual
for available expressions.  See the :manual:`cmake-buildsystem(7)` manual
for more on defining buildsystem properties.


code:
LISTFILE_STACK
--------------

The current stack of listfiles being processed.

This property is mainly useful when trying to debug errors in your
CMake scripts.  It returns a list of what list files are currently
being processed, in order.  So if one listfile does an
:command:`include` command then that is effectively pushing the
included listfile onto the stack.


code:
MACROS
------

List of macro commands available in the current directory.

This read-only property specifies the list of CMake macros currently
defined.  It is intended for debugging purposes.  See the :command:`macro`
command.


code:
PARENT_DIRECTORY
----------------

Source directory that added current subdirectory.

This read-only property specifies the source directory that added the
current source directory as a subdirectory of the build.  In the
top-level directory the value is the empty-string.


code:
RULE_LAUNCH_COMPILE
-------------------

Specify a launcher for compile rules.

.. note::
  This property is intended for internal use by :manual:`ctest(1)`.  Projects
  and developers should use the :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target
  properties or the associated :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER`
  variables instead.

See the :prop_gbl:`global property <RULE_LAUNCH_COMPILE>` of the same name
for details.  This overrides the global property for a directory.


code:
RULE_LAUNCH_CUSTOM
------------------

Specify a launcher for custom rules.

See the global property of the same name for details.  This overrides
the global property for a directory.


code:
RULE_LAUNCH_LINK
----------------

Specify a launcher for link rules.

.. note::
  This property is intended for internal use by :manual:`ctest(1)`.  Projects
  and developers should use the :prop_tgt:`<LANG>_LINKER_LAUNCHER` target
  properties or the associated :variable:`CMAKE_<LANG>_LINKER_LAUNCHER`
  variables instead.

See the :prop_gbl:`global property <RULE_LAUNCH_LINK>` of the same name for
details.  This overrides the global property for a directory.


code:
SOURCE_DIR
----------

.. versionadded:: 3.7

This read-only directory property reports absolute path to the source
directory on which it is read.


code:
SUBDIRECTORIES
--------------

.. versionadded:: 3.7

This read-only directory property contains a
:ref:`semicolon-separated list <CMake Language Lists>` of subdirectories processed so far by
the :command:`add_subdirectory` or :command:`subdirs` commands.  Each entry is
the absolute path to the source directory (containing the ``CMakeLists.txt``
file).  This is suitable to pass to the :command:`get_property` command
``DIRECTORY`` option.

.. note::

  The :command:`subdirs` command does not process its arguments until
  after the calling directory is fully processed.  Therefore looking
  up this property in the current directory will not see them.


code:
SYSTEM
------

.. versionadded:: 3.25

This directory property is used to initialize the :prop_tgt:`SYSTEM`
target property for non-imported targets created in that directory.
It is set to true by :command:`add_subdirectory` and
:command:`FetchContent_Declare` when the ``SYSTEM`` option is given
as an argument to those commands.


code:
TESTS
-----

.. versionadded:: 3.12

List of tests.

This read-only property holds a
:ref:`semicolon-separated list <CMake Language Lists>` of tests
defined so far, in the current directory, by the :command:`add_test` command.


code:
TEST_INCLUDE_FILE
-----------------

Deprecated.  Use :prop_dir:`TEST_INCLUDE_FILES` instead.

A cmake file that will be included when ctest is run.

If you specify ``TEST_INCLUDE_FILE``, that file will be included and
processed when ctest is run on the directory.


code:
TEST_INCLUDE_FILES
------------------

.. versionadded:: 3.10

A list of cmake files that will be included when ctest is run.

If you specify ``TEST_INCLUDE_FILES``, those files will be included and
processed when ctest is run on the directory.


code:
VARIABLES
---------

List of variables defined in the current directory.

This read-only property specifies the list of CMake variables
currently defined.  It is intended for debugging purposes.


code:
VS_GLOBAL_SECTION_POST_<section>
--------------------------------

Specify a postSolution global section in Visual Studio.

Setting a property like this generates an entry of the following form
in the solution file:

::

  GlobalSection(<section>) = postSolution
    <contents based on property value>
  EndGlobalSection

The property must be set to a semicolon-separated list of ``key=value``
pairs.  Each such pair will be transformed into an entry in the
solution global section.  Whitespace around key and value is ignored.
List elements which do not contain an equal sign are skipped.

This property only works for Visual Studio 9 and above; it is ignored
on other generators.  The property only applies when set on a
directory whose ``CMakeLists.txt`` contains a :command:`project` command.

Note that CMake generates postSolution sections ``ExtensibilityGlobals``
and ``ExtensibilityAddIns`` by default.  If you set the corresponding
property, it will override the default section.  For example, setting
``VS_GLOBAL_SECTION_POST_ExtensibilityGlobals`` will override the default
contents of the ``ExtensibilityGlobals`` section, while keeping
ExtensibilityAddIns on its default.  However, CMake will always
add a ``SolutionGuid`` to the ``ExtensibilityGlobals`` section
if it is not specified explicitly.


code:
VS_GLOBAL_SECTION_PRE_<section>
-------------------------------

Specify a preSolution global section in Visual Studio.

Setting a property like this generates an entry of the following form
in the solution file:

::

  GlobalSection(<section>) = preSolution
    <contents based on property value>
  EndGlobalSection

The property must be set to a semicolon-separated list of ``key=value``
pairs.  Each such pair will be transformed into an entry in the
solution global section.  Whitespace around key and value is ignored.
List elements which do not contain an equal sign are skipped.

This property only works for Visual Studio 9 and above; it is ignored
on other generators.  The property only applies when set on a
directory whose ``CMakeLists.txt`` contains a :command:`project` command.


code:
VS_STARTUP_PROJECT
------------------

.. versionadded:: 3.6

Specify the default startup project in a Visual Studio solution.

The :ref:`Visual Studio Generators` create a ``.sln`` file for each directory
whose ``CMakeLists.txt`` file calls the :command:`project` command.  Set this
property in the same directory as a :command:`project` command call (e.g. in
the top-level ``CMakeLists.txt`` file) to specify the default startup project
for the corresponding solution file.

The property must be set to the name of an existing target.  This
will cause that project to be listed first in the generated solution
file causing Visual Studio to make it the startup project if the
solution has never been opened before.

If this property is not specified, then the ``ALL_BUILD`` project
will be the default.


code:
ALLOW_DUPLICATE_CUSTOM_TARGETS
------------------------------

Allow duplicate custom targets to be created.

Normally CMake requires that all targets built in a project have
globally unique logical names (see policy :policy:`CMP0002`).
This is necessary to generate meaningful project file names in
:generator:`Xcode` and :ref:`Visual Studio Generators` IDE
generators.  It also allows the target names to be referenced
unambiguously.

Makefile generators are capable of supporting duplicate :command:`add_custom_target`
names.  For projects that care only about :ref:`Makefile Generators` and do
not wish to support :generator:`Xcode` or :ref:`Visual Studio Generators` IDE
generators, one may set this property to ``True``
to allow duplicate custom targets.  The property
allows multiple :command:`add_custom_target` command calls in different
directories to specify the same target name.  However, setting this
property will cause non-Makefile generators to produce an error and
refuse to generate the project.


code:
AUTOGEN_SOURCE_GROUP
--------------------

.. versionadded:: 3.9

Name of the  :command:`source_group` for :prop_tgt:`AUTOMOC`,
:prop_tgt:`AUTORCC` and :prop_tgt:`AUTOUIC` generated files.

Files generated by :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTORCC` and
:prop_tgt:`AUTOUIC` are not always known at configure time and therefore can't
be passed to :command:`source_group`.
``AUTOGEN_SOURCE_GROUP`` can be used instead to generate or select
a source group for :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTORCC` and
:prop_tgt:`AUTOUIC` generated files.

For :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTORCC` and :prop_tgt:`AUTOUIC` specific
overrides see :prop_gbl:`AUTOMOC_SOURCE_GROUP`, :prop_gbl:`AUTORCC_SOURCE_GROUP`
and :prop_gbl:`AUTOUIC_SOURCE_GROUP` respectively.


code:
AUTOGEN_TARGETS_FOLDER
----------------------

Name of :prop_tgt:`FOLDER` for ``*_autogen`` targets that are added
automatically by CMake for targets for which :prop_tgt:`AUTOMOC` is enabled.

If not set, CMake uses the :prop_tgt:`FOLDER` property of the parent target as a
default value for this property.  See also the documentation for the
:prop_tgt:`FOLDER` target property and the :prop_tgt:`AUTOMOC` target property.


code:
AUTOMOC_SOURCE_GROUP
--------------------

.. versionadded:: 3.9

Name of the  :command:`source_group` for :prop_tgt:`AUTOMOC` generated files.

When set this is used instead of :prop_gbl:`AUTOGEN_SOURCE_GROUP` for
files generated by :prop_tgt:`AUTOMOC`.


code:
AUTOMOC_TARGETS_FOLDER
----------------------

Name of :prop_tgt:`FOLDER` for ``*_autogen`` targets that are added automatically by
CMake for targets for which :prop_tgt:`AUTOMOC` is enabled.

This property is obsolete.  Use :prop_gbl:`AUTOGEN_TARGETS_FOLDER` instead.

If not set, CMake uses the :prop_tgt:`FOLDER` property of the parent target as a
default value for this property.  See also the documentation for the
:prop_tgt:`FOLDER` target property and the :prop_tgt:`AUTOMOC` target property.


code:
AUTORCC_SOURCE_GROUP
--------------------

.. versionadded:: 3.9

Name of the  :command:`source_group` for :prop_tgt:`AUTORCC` generated files.

When set this is used instead of :prop_gbl:`AUTOGEN_SOURCE_GROUP` for
files generated by :prop_tgt:`AUTORCC`.


code:
AUTOUIC_SOURCE_GROUP
--------------------

.. versionadded:: 3.21

Name of the  :command:`source_group` for :prop_tgt:`AUTOUIC` generated files.

When set this is used instead of :prop_gbl:`AUTOGEN_SOURCE_GROUP` for
files generated by :prop_tgt:`AUTOUIC`.


code:
CMAKE_CUDA_KNOWN_FEATURES
-------------------------

.. versionadded:: 3.17

List of CUDA features known to this version of CMake.

The features listed in this global property may be known to be available to the
CUDA compiler.  If the feature is available with the C++ compiler, it will
be listed in the :variable:`CMAKE_CUDA_COMPILE_FEATURES` variable.

The features listed here may be used with the :command:`target_compile_features`
command.  See the :manual:`cmake-compile-features(7)` manual for information on
compile features and a list of supported compilers.

The features known to this version of CMake are:

``cuda_std_03``
  Compiler mode is at least CUDA/C++ 03.

``cuda_std_11``
  Compiler mode is at least CUDA/C++ 11.

``cuda_std_14``
  Compiler mode is at least CUDA/C++ 14.

``cuda_std_17``
  Compiler mode is at least CUDA/C++ 17.

``cuda_std_20``
  Compiler mode is at least CUDA/C++ 20.

``cuda_std_23``
  .. versionadded:: 3.20

  Compiler mode is at least CUDA/C++ 23.

``cuda_std_26``
  .. versionadded:: 3.25

  Compiler mode is at least CUDA/C++ 26.

.. include:: CMAKE_LANG_STD_FLAGS.txt