code:
.. cmake-manual-description: CMake Language Reference

cmake-language(7)
*****************

.. only:: html

   .. contents::

Organization
============

CMake input files are written in the "CMake Language" in source files
named ``CMakeLists.txt`` or ending in a ``.cmake`` file name extension.

CMake Language source files in a project are organized into:

* `Directories`_ (``CMakeLists.txt``),
* `Scripts`_ (``<script>.cmake``), and
* `Modules`_ (``<module>.cmake``).

Directories
-----------

When CMake processes a project source tree, the entry point is
a source file called ``CMakeLists.txt`` in the top-level source
directory.  This file may contain the entire build specification
or use the :command:`add_subdirectory` command to add subdirectories
to the build.  Each subdirectory added by the command must also
contain a ``CMakeLists.txt`` file as the entry point to that
directory.  For each source directory whose ``CMakeLists.txt`` file
is processed CMake generates a corresponding directory in the build
tree to act as the default working and output directory.

Scripts
-------

An individual ``<script>.cmake`` source file may be processed
in *script mode* by using the :manual:`cmake(1)` command-line tool
with the :option:`-P <cmake -P>` option.  Script mode simply runs
the commands in the given CMake Language source file and does not
generate a build system.  It does not allow CMake commands that
define build targets or actions.

Modules
-------

CMake Language code in either `Directories`_ or `Scripts`_ may
use the :command:`include` command to load a ``<module>.cmake``
source file in the scope of the including context.
See the :manual:`cmake-modules(7)` manual page for documentation
of modules included with the CMake distribution.
Project source trees may also provide their own modules and
specify their location(s) in the :variable:`CMAKE_MODULE_PATH`
variable.

Syntax
======

.. _`CMake Language Encoding`:

Encoding
--------

A CMake Language source file may be written in 7-bit ASCII text for
maximum portability across all supported platforms.  Newlines may be
encoded as either ``\n`` or ``\r\n`` but will be converted to ``\n``
as input files are read.

Note that the implementation is 8-bit clean so source files may
be encoded as UTF-8 on platforms with system APIs supporting this
encoding.  In addition, CMake 3.2 and above support source files
encoded in UTF-8 on Windows (using UTF-16 to call system APIs).
Furthermore, CMake 3.0 and above allow a leading UTF-8
`Byte-Order Mark`_ in source files.

.. _Byte-Order Mark: https://en.wikipedia.org/wiki/Byte_order_mark

Source Files
------------

A CMake Language source file consists of zero or more
`Command Invocations`_ separated by newlines and optionally
spaces and `Comments`_:

.. raw:: latex

   \begin{small}

.. productionlist::
 file: `file_element`*
 file_element: `command_invocation` `line_ending` |
             : (`bracket_comment`|`space`)* `line_ending`
 line_ending: `line_comment`? `newline`
 space: <match '[ \t]+'>
 newline: <match '\n'>

.. raw:: latex

   \end{small}

Note that any source file line not inside `Command Arguments`_ or
a `Bracket Comment`_ can end in a `Line Comment`_.

.. _`Command Invocations`:

Command Invocations
-------------------

A *command invocation* is a name followed by paren-enclosed arguments
separated by whitespace:

.. raw:: latex

   \begin{small}

.. productionlist::
 command_invocation: `space`* `identifier` `space`* '(' `arguments` ')'
 identifier: <match '[A-Za-z_][A-Za-z0-9_]*'>
 arguments: `argument`? `separated_arguments`*
 separated_arguments: `separation`+ `argument`? |
                    : `separation`* '(' `arguments` ')'
 separation: `space` | `line_ending`

.. raw:: latex

   \end{small}

For example:

.. code-block:: cmake

 add_executable(hello world.c)

Command names are case-insensitive.
Nested unquoted parentheses in the arguments must balance.
Each ``(`` or ``)`` is given to the command invocation as
a literal `Unquoted Argument`_.  This may be used in calls
to the :command:`if` command to enclose conditions.
For example:

.. code-block:: cmake

 if(FALSE AND (FALSE OR TRUE)) # evaluates to FALSE

.. note::
 CMake versions prior to 3.0 require command name identifiers
 to be at least 2 characters.

 CMake versions prior to 2.8.12 silently accept an `Unquoted Argument`_
 or a `Quoted Argument`_ immediately following a `Quoted Argument`_ and
 not separated by any whitespace.  For compatibility, CMake 2.8.12 and
 higher accept such code but produce a warning.

Command Arguments
-----------------

There are three types of arguments within `Command Invocations`_:

.. raw:: latex

   \begin{small}

.. productionlist::
 argument: `bracket_argument` | `quoted_argument` | `unquoted_argument`

.. raw:: latex

   \end{small}

.. _`Bracket Argument`:

Bracket Argument
^^^^^^^^^^^^^^^^

A *bracket argument*, inspired by `Lua`_ long bracket syntax,
encloses content between opening and closing "brackets" of the
same length:

.. raw:: latex

   \begin{small}

.. productionlist::
 bracket_argument: `bracket_open` `bracket_content` `bracket_close`
 bracket_open: '[' '='* '['
 bracket_content: <any text not containing a `bracket_close` with
                :  the same number of '=' as the `bracket_open`>
 bracket_close: ']' '='* ']'

.. raw:: latex

   \end{small}

An opening bracket is written ``[`` followed by zero or more ``=`` followed
by ``[``.  The corresponding closing bracket is written ``]`` followed
by the same number of ``=`` followed by ``]``.
Brackets do not nest.  A unique length may always be chosen
for the opening and closing brackets to contain closing brackets
of other lengths.

Bracket argument content consists of all text between the opening
and closing brackets, except that one newline immediately following
the opening bracket, if any, is ignored.  No evaluation of the
enclosed content, such as `Escape Sequences`_ or `Variable References`_,
is performed.  A bracket argument is always given to the command
invocation as exactly one argument.

.. ATTENTION No code-block syntax highlighting in the following example
   (long string literal not supported by our cmake.py)

For example::

 message([=[
 This is the first line in a bracket argument with bracket length 1.
 No \-escape sequences or ${variable} references are evaluated.
 This is always one argument even though it contains a ; character.
 The text does not end on a closing bracket of length 0 like ]].
 It does end in a closing bracket of length 1.
 ]=])

.. note::
 CMake versions prior to 3.0 do not support bracket arguments.
 They interpret the opening bracket as the start of an
 `Unquoted Argument`_.

.. _`Lua`: https://www.lua.org/

.. _`Quoted Argument`:

Quoted Argument
^^^^^^^^^^^^^^^

A *quoted argument* encloses content between opening and closing
double-quote characters:

.. raw:: latex

   \begin{small}

.. productionlist::
 quoted_argument: '"' `quoted_element`* '"'
 quoted_element: <any character except '\' or '"'> |
                 : `escape_sequence` |
                 : `quoted_continuation`
 quoted_continuation: '\' `newline`

.. raw:: latex

   \end{small}

Quoted argument content consists of all text between opening and
closing quotes.  Both `Escape Sequences`_ and `Variable References`_
are evaluated.  A quoted argument is always given to the command
invocation as exactly one argument.

.. ATTENTION No code-block syntax highlighting in the following example
   (escape \" not supported by our cmake.py)

For example:

.. code-block:: cmake

  message("This is a quoted argument containing multiple lines.
  This is always one argument even though it contains a ; character.
  Both \\-escape sequences and ${variable} references are evaluated.
  The text does not end on an escaped double-quote like \".
  It does end in an unescaped double quote.
  ")

.. ATTENTION No code-block syntax highlighting in the following example
   (for conformity with the two above examples)

The final ``\`` on any line ending in an odd number of backslashes
is treated as a line continuation and ignored along with the
immediately following newline character.  For example:

.. code-block:: cmake

  message("\
  This is the first line of a quoted argument. \
  In fact it is the only line but since it is long \
  the source code uses line continuation.\
  ")

.. note::
 CMake versions prior to 3.0 do not support continuation with ``\``.
 They report errors in quoted arguments containing lines ending in
 an odd number of ``\`` characters.

.. _`Unquoted Argument`:

Unquoted Argument
^^^^^^^^^^^^^^^^^

An *unquoted argument* is not enclosed by any quoting syntax.
It may not contain any whitespace, ``(``, ``)``, ``#``, ``"``, or ``\``
except when escaped by a backslash:

.. raw:: latex

   \begin{small}

.. productionlist::
 unquoted_argument: `unquoted_element`+ | `unquoted_legacy`
 unquoted_element: <any character except whitespace or one of '()#"\'> |
                 : `escape_sequence`
 unquoted_legacy: <see note in text>

.. raw:: latex

   \end{small}

Unquoted argument content consists of all text in a contiguous block
of allowed or escaped characters.  Both `Escape Sequences`_ and
`Variable References`_ are evaluated.  The resulting value is divided
in the same way `Lists`_ divide into elements.  Each non-empty element
is given to the command invocation as an argument.  Therefore an
unquoted argument may be given to a command invocation as zero or
more arguments.

For example:

.. code-block:: cmake

 foreach(arg
     NoSpace
     Escaped\ Space
     This;Divides;Into;Five;Arguments
     Escaped\;Semicolon
     )
   message("${arg}")
 endforeach()

.. note::
 To support legacy CMake code, unquoted arguments may also contain
 double-quoted strings (``"..."``, possibly enclosing horizontal
 whitespace), and make-style variable references (``$(MAKEVAR)``).

 Unescaped double-quotes must balance, may not appear at the
 beginning of an unquoted argument, and are treated as part of the
 content.  For example, the unquoted arguments ``-Da="b c"``,
 ``-Da=$(v)``, and ``a" "b"c"d`` are each interpreted literally.
 They may instead be written as quoted arguments ``"-Da=\"b c\""``,
 ``"-Da=$(v)"``, and ``"a\" \"b\"c\"d"``, respectively.

 Make-style references are treated literally as part of the content
 and do not undergo variable expansion.  They are treated as part
 of a single argument (rather than as separate ``$``, ``(``,
 ``MAKEVAR``, and ``)`` arguments).

 The above "unquoted_legacy" production represents such arguments.
 We do not recommend using legacy unquoted arguments in new code.
 Instead use a `Quoted Argument`_ or a `Bracket Argument`_ to
 represent the content.

.. _`Escape Sequences`:

Escape Sequences
----------------

An *escape sequence* is a ``\`` followed by one character:

.. raw:: latex

   \begin{small}

.. productionlist::
 escape_sequence: `escape_identity` | `escape_encoded` | `escape_semicolon`
 escape_identity: '\' <match '[^A-Za-z0-9;]'>
 escape_encoded: '\t' | '\r' | '\n'
 escape_semicolon: '\;'

.. raw:: latex

   \end{small}

A ``\`` followed by a non-alphanumeric character simply encodes the literal
character without interpreting it as syntax.  A ``\t``, ``\r``, or ``\n``
encodes a tab, carriage return, or newline character, respectively. A ``\;``
outside of any `Variable References`_  encodes itself but may be used in an
`Unquoted Argument`_ to encode the ``;`` without dividing the argument
value on it.  A ``\;`` inside `Variable References`_ encodes the literal
``;`` character.  (See also policy :policy:`CMP0053` documentation for
historical considerations.)

.. _`Variable References`:

Variable References
-------------------

A *variable reference* has the form ``${<variable>}`` and is
evaluated inside a `Quoted Argument`_ or an `Unquoted Argument`_.
A variable reference is replaced by the value of the specified
variable or cache entry, or if neither is set, by the empty string.
Variable references can nest and are evaluated from the
inside out, e.g. ``${outer_${inner_variable}_variable}``.

Literal variable references may consist of alphanumeric characters,
the characters ``/_.+-``, and `Escape Sequences`_.  Nested references
may be used to evaluate variables of any name.  See also policy
:policy:`CMP0053` documentation for historical considerations and reasons why
the ``$`` is also technically permitted but is discouraged.

The `Variables`_ section documents the scope of variable names
and how their values are set.

An *environment variable reference* has the form ``$ENV{<variable>}``.
See the `Environment Variables`_ section for more information.

A *cache variable reference* has the form ``$CACHE{<variable>}``,
and is replaced by the value of the specified cache entry without
checking for a normal variable of the same name.  If the cache
entry does not exist, it is replaced by the empty string.
See :variable:`CACHE` for more information.

The :command:`if` command has a special condition syntax that
allows for variable references in the short form ``<variable>``
instead of ``${<variable>}``.  However, environment variables
always need to be referenced as ``$ENV{<variable>}``.

Comments
--------

A comment starts with a ``#`` character that is not inside a
`Bracket Argument`_, `Quoted Argument`_, or escaped with ``\``
as part of an `Unquoted Argument`_.  There are two types of
comments: a `Bracket Comment`_ and a `Line Comment`_.

.. _`Bracket Comment`:

Bracket Comment
^^^^^^^^^^^^^^^

A ``#`` immediately followed by a :token:`bracket_open` forms a
*bracket comment* consisting of the entire bracket enclosure:

.. raw:: latex

   \begin{small}

.. productionlist::
 bracket_comment: '#' `bracket_argument`

.. raw:: latex

   \end{small}

For example:

::

 #[[This is a bracket comment.
 It runs until the close bracket.]]
 message("First Argument\n" #[[Bracket Comment]] "Second Argument")

.. note::
 CMake versions prior to 3.0 do not support bracket comments.
 They interpret the opening ``#`` as the start of a `Line Comment`_.

.. _`Line Comment`:

Line Comment
^^^^^^^^^^^^

A ``#`` not immediately followed by a :token:`bracket_open` forms a
*line comment* that runs until the end of the line:

.. raw:: latex

   \begin{small}

.. productionlist::
 line_comment: '#' <any text not starting in a `bracket_open`
             :      and not containing a `newline`>

.. raw:: latex

   \end{small}

For example:

.. code-block:: cmake

 # This is a line comment.
 message("First Argument\n" # This is a line comment :)
         "Second Argument") # This is a line comment.

Control Structures
==================

Conditional Blocks
------------------

The :command:`if`/:command:`elseif`/:command:`else`/:command:`endif`
commands delimit code blocks to be executed conditionally.

Loops
-----

The :command:`foreach`/:command:`endforeach` and
:command:`while`/:command:`endwhile` commands delimit code
blocks to be executed in a loop.  Inside such blocks the
:command:`break` command may be used to terminate the loop
early whereas the :command:`continue` command may be used
to start with the next iteration immediately.

Command Definitions
-------------------

The :command:`macro`/:command:`endmacro`, and
:command:`function`/:command:`endfunction` commands delimit
code blocks to be recorded for later invocation as commands.

.. _`CMake Language Variables`:

Variables
=========

Variables are the basic unit of storage in the CMake Language.
Their values are always of string type, though some commands may
interpret the strings as values of other types.
The :command:`set` and :command:`unset` commands explicitly
set or unset a variable, but other commands have semantics
that modify variables as well.
Variable names are case-sensitive and may consist of almost
any text, but we recommend sticking to names consisting only
of alphanumeric characters plus ``_`` and ``-``.

Variables have dynamic scope.  Each variable "set" or "unset"
creates a binding in the current scope:

Block Scope
 The :command:`block` command may create a new scope for variable bindings.

Function Scope
 `Command Definitions`_ created by the :command:`function` command
 create commands that, when invoked, process the recorded commands
 in a new variable binding scope.  A variable "set" or "unset"
 binds in this scope and is visible for the current function and
 any nested calls within it, but not after the function returns.

Directory Scope
 Each of the `Directories`_ in a source tree has its own variable
 bindings.  Before processing the ``CMakeLists.txt`` file for a
 directory, CMake copies all variable bindings currently defined
 in the parent directory, if any, to initialize the new directory
 scope.  CMake `Scripts`_, when processed with :option:`cmake -P`,
 bind variables in one "directory" scope.

 A variable "set" or "unset" not inside a function call binds
 to the current directory scope.

Persistent Cache
 CMake stores a separate set of "cache" variables, or "cache entries",
 whose values persist across multiple runs within a project build
 tree.  Cache entries have an isolated binding scope modified only
 by explicit request, such as by the ``CACHE`` option of the
 :command:`set` and :command:`unset` commands.

When evaluating `Variable References`_, CMake first searches the
function call stack, if any, for a binding and then falls back
to the binding in the current directory scope, if any.  If a
"set" binding is found, its value is used.  If an "unset" binding
is found, or no binding is found, CMake then searches for a
cache entry.  If a cache entry is found, its value is used.
Otherwise, the variable reference evaluates to an empty string.
The ``$CACHE{VAR}`` syntax can be used to do direct cache entry
lookups.

The :manual:`cmake-variables(7)` manual documents the many variables
that are provided by CMake or have meaning to CMake when set
by project code.

.. include:: ID_RESERVE.txt

.. _`CMake Language Environment Variables`:

Environment Variables
=====================

Environment Variables are like ordinary `Variables`_, with the
following differences:

Scope
 Environment variables have global scope in a CMake process.
 They are never cached.

References
 `Variable References`_ have the form ``$ENV{<variable>}``, using the
 :variable:`ENV` operator.

Initialization
 Initial values of the CMake environment variables are those of
 the calling process.
 Values can be changed using the :command:`set` and :command:`unset`
 commands.
 These commands only affect the running CMake process,
 not the system environment at large.
 Changed values are not written back to the calling process,
 and they are not seen by subsequent build or test processes.

 See the :option:`cmake -E env <cmake-E env>` command-line
 tool to run a command in a modified environment.

Inspection
 See the :option:`cmake -E environment <cmake-E environment>` command-line
 tool to display all current environment variables.

The :manual:`cmake-env-variables(7)` manual documents environment
variables that have special meaning to CMake.

.. _`CMake Language Lists`:

Lists
=====

Although all values in CMake are stored as strings, a string
may be treated as a list in certain contexts, such as during
evaluation of an `Unquoted Argument`_.  In such contexts, a string
is divided into list elements by splitting on ``;`` characters not
following an unequal number of ``[`` and ``]`` characters and not
immediately preceded by a ``\``.  The sequence ``\;`` does not
divide a value but is replaced by ``;`` in the resulting element.

A list of elements is represented as a string by concatenating
the elements separated by ``;``.  For example, the :command:`set`
command stores multiple values into the destination variable
as a list:

.. code-block:: cmake

 set(srcs a.c b.c c.c) # sets "srcs" to "a.c;b.c;c.c"

Lists are meant for simple use cases such as a list of source
files and should not be used for complex data processing tasks.
Most commands that construct lists do not escape ``;`` characters
in list elements, thus flattening nested lists:

.. code-block:: cmake

 set(x a "b;c") # sets "x" to "a;b;c", not "a;b\;c"

In general, lists do not support elements containing ``;`` characters.
To avoid problems, consider the following advice:

* The interfaces of many CMake commands, variables, and properties accept
  semicolon-separated lists.  Avoid passing lists with elements containing
  semicolons to these interfaces unless they document either direct support
  or some way to escape or encode semicolons.

* When constructing a list, substitute an otherwise-unused placeholder
  for ``;`` in elements when.  Then substitute ``;`` for the placeholder
  when processing list elements.
  For example, the following code uses ``|`` in place of ``;`` characters:

  .. code-block:: cmake

    set(mylist a "b|c")
    foreach(entry IN LISTS mylist)
      string(REPLACE "|" ";" entry "${entry}")
      # use "${entry}" normally
    endforeach()

  The :module:`ExternalProject` module's ``LIST_SEPARATOR`` option is an
  example of an interface built using this approach.

* In lists of :manual:`generator expressions <cmake-generator-expressions(7)>`,
  use the :genex:`$<SEMICOLON>` generator expression.

* In command calls, use `Quoted Argument`_ syntax whenever possible.
  The called command will receive the content of the argument with
  semicolons preserved.  An `Unquoted Argument`_ will be split on
  semicolons.

* In :command:`function` implementations, avoid ``ARGV`` and ``ARGN``,
  which do not distinguish semicolons in values from those separating values.
  Instead, prefer using named positional arguments and the ``ARGC`` and
  ``ARGV#`` variables.
  When using :command:`cmake_parse_arguments` to parse arguments, prefer
  its ``PARSE_ARGV`` signature, which uses the ``ARGV#`` variables.

  Note that this approach does not apply to :command:`macro` implementations
  because they reference arguments using placeholders, not real variables.


code:
.. cmake-manual-description: CMake Modules Reference

cmake-modules(7)
****************

The modules listed here are part of the CMake distribution.
Projects may provide further modules; their location(s)
can be specified in the :variable:`CMAKE_MODULE_PATH` variable.

Utility Modules
^^^^^^^^^^^^^^^

These modules are loaded using the :command:`include` command.

.. toctree::
   :maxdepth: 1

   /module/AndroidTestUtilities
   /module/BundleUtilities
   /module/CheckCCompilerFlag
   /module/CheckCompilerFlag
   /module/CheckCSourceCompiles
   /module/CheckCSourceRuns
   /module/CheckCXXCompilerFlag
   /module/CheckCXXSourceCompiles
   /module/CheckCXXSourceRuns
   /module/CheckCXXSymbolExists
   /module/CheckFortranCompilerFlag
   /module/CheckFortranFunctionExists
   /module/CheckFortranSourceCompiles
   /module/CheckFortranSourceRuns
   /module/CheckFunctionExists
   /module/CheckIncludeFileCXX
   /module/CheckIncludeFile
   /module/CheckIncludeFiles
   /module/CheckIPOSupported
   /module/CheckLanguage
   /module/CheckLibraryExists
   /module/CheckLinkerFlag
   /module/CheckOBJCCompilerFlag
   /module/CheckOBJCSourceCompiles
   /module/CheckOBJCSourceRuns
   /module/CheckOBJCXXCompilerFlag
   /module/CheckOBJCXXSourceCompiles
   /module/CheckOBJCXXSourceRuns
   /module/CheckPIESupported
   /module/CheckPrototypeDefinition
   /module/CheckSourceCompiles
   /module/CheckSourceRuns
   /module/CheckStructHasMember
   /module/CheckSymbolExists
   /module/CheckTypeSize
   /module/CheckVariableExists
   /module/CMakeAddFortranSubdirectory
   /module/CMakeBackwardCompatibilityCXX
   /module/CMakeDependentOption
   /module/CMakeFindDependencyMacro
   /module/CMakeFindFrameworks
   /module/CMakeFindPackageMode
   /module/CMakeGraphVizOptions
   /module/CMakePackageConfigHelpers
   /module/CMakePrintHelpers
   /module/CMakePrintSystemInformation
   /module/CMakePushCheckState
   /module/CMakeVerifyManifest
   /module/CPack
   /module/CPackComponent
   /module/CPackIFW
   /module/CPackIFWConfigureFile
   /module/CSharpUtilities
   /module/CTest
   /module/CTestCoverageCollectGCOV
   /module/CTestScriptMode
   /module/CTestUseLaunchers
   /module/DeployQt4
   /module/ExternalData
   /module/ExternalProject
   /module/FeatureSummary
   /module/FetchContent
   /module/FindPackageHandleStandardArgs
   /module/FindPackageMessage
   /module/FortranCInterface
   /module/GenerateExportHeader
   /module/GNUInstallDirs
   /module/GoogleTest
   /module/InstallRequiredSystemLibraries
   /module/ProcessorCount
   /module/SelectLibraryConfigurations
   /module/SquishTestScript
   /module/TestForANSIForScope
   /module/TestForANSIStreamHeaders
   /module/TestForSSTREAM
   /module/TestForSTDNamespace
   /module/UseEcos
   /module/UseJava
   /module/UseSWIG
   /module/UsewxWidgets

Find Modules
^^^^^^^^^^^^

These modules search for third-party software.
They are normally called through the :command:`find_package` command.

.. toctree::
   :maxdepth: 1

   /module/FindALSA
   /module/FindArmadillo
   /module/FindASPELL
   /module/FindAVIFile
   /module/FindBacktrace
   /module/FindBISON
   /module/FindBLAS
   /module/FindBoost
   /module/FindBullet
   /module/FindBZip2
   /module/FindCABLE
   /module/FindCoin3D
   /module/FindCUDAToolkit
   /module/FindCups
   /module/FindCURL
   /module/FindCurses
   /module/FindCVS
   /module/FindCxxTest
   /module/FindCygwin
   /module/FindDCMTK
   /module/FindDevIL
   /module/FindDoxygen
   /module/FindEnvModules
   /module/FindEXPAT
   /module/FindFLEX
   /module/FindFLTK
   /module/FindFLTK2
   /module/FindFontconfig
   /module/FindFreetype
   /module/FindGCCXML
   /module/FindGDAL
   /module/FindGettext
   /module/FindGIF
   /module/FindGit
   /module/FindGLEW
   /module/FindGLUT
   /module/FindGnuplot
   /module/FindGnuTLS
   /module/FindGSL
   /module/FindGTest
   /module/FindGTK
   /module/FindGTK2
   /module/FindHDF5
   /module/FindHg
   /module/FindHSPELL
   /module/FindHTMLHelp
   /module/FindIce
   /module/FindIconv
   /module/FindIcotool
   /module/FindICU
   /module/FindImageMagick
   /module/FindIntl
   /module/FindJasper
   /module/FindJava
   /module/FindJNI
   /module/FindJPEG
   /module/FindKDE3
   /module/FindKDE4
   /module/FindLAPACK
   /module/FindLATEX
   /module/FindLibArchive
   /module/FindLibinput
   /module/FindLibLZMA
   /module/FindLibXml2
   /module/FindLibXslt
   /module/FindLTTngUST
   /module/FindLua
   /module/FindLua50
   /module/FindLua51
   /module/FindMatlab
   /module/FindMFC
   /module/FindMotif
   /module/FindMPEG
   /module/FindMPEG2
   /module/FindMPI
   /module/FindMsys
   /module/FindODBC
   /module/FindOpenACC
   /module/FindOpenAL
   /module/FindOpenCL
   /module/FindOpenGL
   /module/FindOpenMP
   /module/FindOpenSceneGraph
   /module/FindOpenSP
   /module/FindOpenSSL
   /module/FindOpenThreads
   /module/Findosg
   /module/Findosg_functions
   /module/FindosgAnimation
   /module/FindosgDB
   /module/FindosgFX
   /module/FindosgGA
   /module/FindosgIntrospection
   /module/FindosgManipulator
   /module/FindosgParticle
   /module/FindosgPresentation
   /module/FindosgProducer
   /module/FindosgQt
   /module/FindosgShadow
   /module/FindosgSim
   /module/FindosgTerrain
   /module/FindosgText
   /module/FindosgUtil
   /module/FindosgViewer
   /module/FindosgVolume
   /module/FindosgWidget
   /module/FindPatch
   /module/FindPerl
   /module/FindPerlLibs
   /module/FindPHP4
   /module/FindPhysFS
   /module/FindPike
   /module/FindPkgConfig
   /module/FindPNG
   /module/FindPostgreSQL
   /module/FindProducer
   /module/FindProtobuf
   /module/FindPython
   /module/FindPython2
   /module/FindPython3
   /module/FindQt3
   /module/FindQt4
   /module/FindQuickTime
   /module/FindRTI
   /module/FindRuby
   /module/FindSDL
   /module/FindSDL_image
   /module/FindSDL_gfx
   /module/FindSDL_mixer
   /module/FindSDL_net
   /module/FindSDL_sound
   /module/FindSDL_ttf
   /module/FindSelfPackers
   /module/FindSquish
   /module/FindSQLite3
   /module/FindSubversion
   /module/FindSWIG
   /module/FindTCL
   /module/FindTclsh
   /module/FindTclStub
   /module/FindThreads
   /module/FindTIFF
   /module/FindVulkan
   /module/FindWget
   /module/FindWish
   /module/FindwxWidgets
   /module/FindX11
   /module/FindXalanC
   /module/FindXCTest
   /module/FindXercesC
   /module/FindXMLRPC
   /module/FindZLIB

Deprecated Modules
^^^^^^^^^^^^^^^^^^^

Deprecated Utility Modules
==========================

.. toctree::
   :maxdepth: 1

   /module/AddFileDependencies
   /module/CMakeDetermineVSServicePack
   /module/CMakeExpandImportedTargets
   /module/CMakeForceCompiler
   /module/CMakeParseArguments
   /module/Dart
   /module/Documentation
   /module/GetPrerequisites
   /module/MacroAddFileDependencies
   /module/TestBigEndian
   /module/TestCXXAcceptsFlag
   /module/UseJavaClassFilelist
   /module/UseJavaSymlinks
   /module/UsePkgConfig
   /module/Use_wxWindows
   /module/WriteBasicConfigVersionFile
   /module/WriteCompilerDetectionHeader

Deprecated Find Modules
=======================

.. toctree::
   :maxdepth: 1

   /module/FindCUDA
   /module/FindDart
   /module/FindITK
   /module/FindPythonInterp
   /module/FindPythonLibs
   /module/FindQt
   /module/FindUnixCommands
   /module/FindVTK
   /module/FindwxWindows

Legacy CPack Modules
====================

These modules used to be mistakenly exposed to the user, and have been moved
out of user visibility. They are for CPack internal use, and should never be
used directly.

.. toctree::
   :maxdepth: 1

   /module/CPackArchive
   /module/CPackBundle
   /module/CPackCygwin
   /module/CPackDeb
   /module/CPackDMG
   /module/CPackFreeBSD
   /module/CPackNSIS
   /module/CPackNuGet
   /module/CPackProductBuild
   /module/CPackRPM
   /module/CPackWIX

repo_name: lazytadpole/codenamesilverfish

license: mit


code:
.. cmake-manual-description: CMake Packages Reference

cmake-packages(7)
*****************

.. only:: html

   .. contents::

Introduction
============

Packages provide dependency information to CMake based buildsystems.  Packages
are found with the :command:`find_package` command.  The result of
using :command:`find_package` is either a set of :prop_tgt:`IMPORTED` targets, or
a set of variables corresponding to build-relevant information.

Using Packages
==============

CMake provides direct support for two forms of packages,
`Config-file Packages`_ and `Find-module Packages`_.
Indirect support for ``pkg-config`` packages is also provided via
the :module:`FindPkgConfig` module.  In all cases, the basic form
of :command:`find_package` calls is the same:

.. code-block:: cmake

  find_package(Qt4 4.7.0 REQUIRED) # CMake provides a Qt4 find-module
  find_package(Qt5Core 5.1.0 REQUIRED) # Qt provides a Qt5 package config file.
  find_package(LibXml2 REQUIRED) # Use pkg-config via the LibXml2 find-module

In cases where it is known that a package configuration file is provided by
upstream, and only that should be used, the ``CONFIG`` keyword may be passed
to :command:`find_package`:

.. code-block:: cmake

  find_package(Qt5Core 5.1.0 CONFIG REQUIRED)
  find_package(Qt5Gui 5.1.0 CONFIG)

Similarly, the ``MODULE`` keyword says to use only a find-module:

.. code-block:: cmake

  find_package(Qt4 4.7.0 MODULE REQUIRED)

Specifying the type of package explicitly improves the error message shown to
the user if it is not found.

Both types of packages also support specifying components of a package,
either after the ``REQUIRED`` keyword:

.. code-block:: cmake

  find_package(Qt5 5.1.0 CONFIG REQUIRED Widgets Xml Sql)

or as a separate ``COMPONENTS`` list:

.. code-block:: cmake

  find_package(Qt5 5.1.0 COMPONENTS Widgets Xml Sql)

or as a separate ``OPTIONAL_COMPONENTS`` list:

.. code-block:: cmake

  find_package(Qt5 5.1.0 COMPONENTS Widgets
                         OPTIONAL_COMPONENTS Xml Sql
  )

Handling of ``COMPONENTS`` and ``OPTIONAL_COMPONENTS`` is defined by the
package.

By setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to
``TRUE``, the ``<PackageName>`` package will not be searched, and will always
be ``NOTFOUND``. Likewise, setting the
:variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` to ``TRUE`` will make the
package REQUIRED.

.. _`Config File Packages`:

Config-file Packages
--------------------

A config-file package is a set of files provided by upstreams for downstreams
to use. CMake searches in a number of locations for package configuration files, as
described in the :command:`find_package` documentation.  The most simple way for
a CMake user to tell :manual:`cmake(1)` to search in a non-standard prefix for
a package is to set the ``CMAKE_PREFIX_PATH`` cache variable.

Config-file packages are provided by upstream vendors as part of development
packages, that is, they belong with the header files and any other files
provided to assist downstreams in using the package.

A set of variables which provide package status information are also set
automatically when using a config-file package.  The ``<PackageName>_FOUND``
variable is set to true or false, depending on whether the package was
found.  The ``<PackageName>_DIR`` cache variable is set to the location of the
package configuration file.

Find-module Packages
--------------------

A find module is a file with a set of rules for finding the required pieces of
a dependency, primarily header files and libraries.  Typically, a find module
is needed when the upstream is not built with CMake, or is not CMake-aware
enough to otherwise provide a package configuration file.  Unlike a package configuration
file, it is not shipped with upstream, but is used by downstream to find the
files by guessing locations of files with platform-specific hints.

Unlike the case of an upstream-provided package configuration file, no single point
of reference identifies the package as being found, so the ``<PackageName>_FOUND``
variable is not automatically set by the :command:`find_package` command.  It
can still be expected to be set by convention however and should be set by
the author of the Find-module.  Similarly there is no ``<PackageName>_DIR`` variable,
but each of the artifacts such as library locations and header file locations
provide a separate cache variable.

See the :manual:`cmake-developer(7)` manual for more information about creating
Find-module files.

Package Layout
==============

A config-file package consists of a `Package Configuration File`_ and
optionally a `Package Version File`_ provided with the project distribution.

Package Configuration File
--------------------------

Consider a project ``Foo`` that installs the following files::

  <prefix>/include/foo-1.2/foo.h
  <prefix>/lib/foo-1.2/libfoo.a

It may also provide a CMake package configuration file::

  <prefix>/lib/cmake/foo-1.2/FooConfig.cmake

with content defining :prop_tgt:`IMPORTED` targets, or defining variables, such
as:

.. code-block:: cmake

  # ...
  # (compute PREFIX relative to file location)
  # ...
  set(Foo_INCLUDE_DIRS ${PREFIX}/include/foo-1.2)
  set(Foo_LIBRARIES ${PREFIX}/lib/foo-1.2/libfoo.a)

If another project wishes to use ``Foo`` it need only to locate the ``FooConfig.cmake``
file and load it to get all the information it needs about package content
locations.  Since the package configuration file is provided by the package
installation it already knows all the file locations.

The :command:`find_package` command may be used to search for the package
configuration file.  This command constructs a set of installation prefixes
and searches under each prefix in several locations.  Given the name ``Foo``,
it looks for a file called ``FooConfig.cmake`` or ``foo-config.cmake``.
The full set of locations is specified in the :command:`find_package` command
documentation. One place it looks is::

 <prefix>/lib/cmake/Foo*/

where ``Foo*`` is a case-insensitive globbing expression.  In our example the
globbing expression will match ``<prefix>/lib/cmake/foo-1.2`` and the package
configuration file will be found.

Once found, a package configuration file is immediately loaded.  It, together
with a package version file, contains all the information the project needs to
use the package.

Package Version File
--------------------

When the :command:`find_package` command finds a candidate package configuration
file it looks next to it for a version file. The version file is loaded to test
whether the package version is an acceptable match for the version requested.
If the version file claims compatibility the configuration file is accepted.
Otherwise it is ignored.

The name of the package version file must match that of the package configuration
file but has either ``-version`` or ``Version`` appended to the name before
the ``.cmake`` extension.  For example, the files::

 <prefix>/lib/cmake/foo-1.3/foo-config.cmake
 <prefix>/lib/cmake/foo-1.3/foo-config-version.cmake

and::

 <prefix>/lib/cmake/bar-4.2/BarConfig.cmake
 <prefix>/lib/cmake/bar-4.2/BarConfigVersion.cmake

are each pairs of package configuration files and corresponding package version
files.

When the :command:`find_package` command loads a version file it first sets the
following variables:

``PACKAGE_FIND_NAME``
 The ``<PackageName>``

``PACKAGE_FIND_VERSION``
 Full requested version string

``PACKAGE_FIND_VERSION_MAJOR``
 Major version if requested, else 0

``PACKAGE_FIND_VERSION_MINOR``
 Minor version if requested, else 0

``PACKAGE_FIND_VERSION_PATCH``
 Patch version if requested, else 0

``PACKAGE_FIND_VERSION_TWEAK``
 Tweak version if requested, else 0

``PACKAGE_FIND_VERSION_COUNT``
 Number of version components, 0 to 4

The version file must use these variables to check whether it is compatible or
an exact match for the requested version and set the following variables with
results:

``PACKAGE_VERSION``
 Full provided version string

``PACKAGE_VERSION_EXACT``
 True if version is exact match

``PACKAGE_VERSION_COMPATIBLE``
 True if version is compatible

``PACKAGE_VERSION_UNSUITABLE``
 True if unsuitable as any version

Version files are loaded in a nested scope so they are free to set any variables
they wish as part of their computation. The find_package command wipes out the
scope when the version file has completed and it has checked the output
variables. When the version file claims to be an acceptable match for the
requested version the find_package command sets the following variables for
use by the project:

``<PackageName>_VERSION``
 Full provided version string

``<PackageName>_VERSION_MAJOR``
 Major version if provided, else 0

``<PackageName>_VERSION_MINOR``
 Minor version if provided, else 0

``<PackageName>_VERSION_PATCH``
 Patch version if provided, else 0

``<PackageName>_VERSION_TWEAK``
 Tweak version if provided, else 0

``<PackageName>_VERSION_COUNT``
 Number of version components, 0 to 4

The variables report the version of the package that was actually found.
The ``<PackageName>`` part of their name matches the argument given to the
:command:`find_package` command.

.. _`Creating Packages`:

Creating Packages
=================

Usually, the upstream depends on CMake itself and can use some CMake facilities
for creating the package files. Consider an upstream which provides a single
shared library:

.. code-block:: cmake

  project(UpstreamLib)

  set(CMAKE_INCLUDE_CURRENT_DIR ON)
  set(CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE ON)

  set(Upstream_VERSION 3.4.1)

  include(GenerateExportHeader)

  add_library(ClimbingStats SHARED climbingstats.cpp)
  generate_export_header(ClimbingStats)
  set_property(TARGET ClimbingStats PROPERTY VERSION ${Upstream_VERSION})
  set_property(TARGET ClimbingStats PROPERTY SOVERSION 3)
  set_property(TARGET ClimbingStats PROPERTY
    INTERFACE_ClimbingStats_MAJOR_VERSION 3)
  set_property(TARGET ClimbingStats APPEND PROPERTY
    COMPATIBLE_INTERFACE_STRING ClimbingStats_MAJOR_VERSION
  )

  install(TARGETS ClimbingStats EXPORT ClimbingStatsTargets
    LIBRARY DESTINATION lib
    ARCHIVE DESTINATION lib
    RUNTIME DESTINATION bin
    INCLUDES DESTINATION include
  )
  install(
    FILES
      climbingstats.h
      "${CMAKE_CURRENT_BINARY_DIR}/climbingstats_export.h"
    DESTINATION
      include
    COMPONENT
      Devel
  )

  include(CMakePackageConfigHelpers)
  write_basic_package_version_file(
    "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsConfigVersion.cmake"
    VERSION ${Upstream_VERSION}
    COMPATIBILITY AnyNewerVersion
  )

  export(EXPORT ClimbingStatsTargets
    FILE "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsTargets.cmake"
    NAMESPACE Upstream::
  )
  configure_file(cmake/ClimbingStatsConfig.cmake
    "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsConfig.cmake"
    COPYONLY
  )

  set(ConfigPackageLocation lib/cmake/ClimbingStats)
  install(EXPORT ClimbingStatsTargets
    FILE
      ClimbingStatsTargets.cmake
    NAMESPACE
      Upstream::
    DESTINATION
      ${ConfigPackageLocation}
  )
  install(
    FILES
      cmake/ClimbingStatsConfig.cmake
      "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsConfigVersion.cmake"
    DESTINATION
      ${ConfigPackageLocation}
    COMPONENT
      Devel
  )

The :module:`CMakePackageConfigHelpers` module provides a macro for creating
a simple ``ConfigVersion.cmake`` file.  This file sets the version of the
package.  It is read by CMake when :command:`find_package` is called to
determine the compatibility with the requested version, and to set some
version-specific variables ``<PackageName>_VERSION``, ``<PackageName>_VERSION_MAJOR``,
``<PackageName>_VERSION_MINOR`` etc.  The :command:`install(EXPORT)` command is
used to export the targets in the ``ClimbingStatsTargets`` export-set, defined
previously by the :command:`install(TARGETS)` command. This command generates
the ``ClimbingStatsTargets.cmake`` file to contain :prop_tgt:`IMPORTED`
targets, suitable for use by downstreams and arranges to install it to
``lib/cmake/ClimbingStats``.  The generated ``ClimbingStatsConfigVersion.cmake``
and a ``cmake/ClimbingStatsConfig.cmake`` are installed to the same location,
completing the package.

The generated :prop_tgt:`IMPORTED` targets have appropriate properties set
to define their :ref:`usage requirements <Target Usage Requirements>`, such as
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`,
:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` and other relevant built-in
``INTERFACE_`` properties.  The ``INTERFACE`` variant of user-defined
properties listed in :prop_tgt:`COMPATIBLE_INTERFACE_STRING` and
other :ref:`Compatible Interface Properties` are also propagated to the
generated :prop_tgt:`IMPORTED` targets.  In the above case,
``ClimbingStats_MAJOR_VERSION`` is defined as a string which must be
compatible among the dependencies of any depender.  By setting this custom
defined user property in this version and in the next version of
``ClimbingStats``, :manual:`cmake(1)` will issue a diagnostic if there is an
attempt to use version 3 together with version 4.  Packages can choose to
employ such a pattern if different major versions of the package are designed
to be incompatible.

A ``NAMESPACE`` with double-colons is specified when exporting the targets
for installation.  This convention of double-colons gives CMake a hint that
the name is an :prop_tgt:`IMPORTED` target when it is used by downstreams
with the :command:`target_link_libraries` command.  This way, CMake can
issue a diagnostic if the package providing it has not yet been found.

In this case, when using :command:`install(TARGETS)` the ``INCLUDES DESTINATION``
was specified.  This causes the ``IMPORTED`` targets to have their
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` populated with the ``include``
directory in the :variable:`CMAKE_INSTALL_PREFIX`.  When the ``IMPORTED``
target is used by downstream, it automatically consumes the entries from
that property.

Creating a Package Configuration File
-------------------------------------

In this case, the ``ClimbingStatsConfig.cmake`` file could be as simple as:

.. code-block:: cmake

  include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")

As this allows downstreams to use the ``IMPORTED`` targets.  If any macros
should be provided by the ``ClimbingStats`` package, they should
be in a separate file which is installed to the same location as the
``ClimbingStatsConfig.cmake`` file, and included from there.

This can also be extended to cover dependencies:

.. code-block:: cmake

  # ...
  add_library(ClimbingStats SHARED climbingstats.cpp)
  generate_export_header(ClimbingStats)

  find_package(Stats 2.6.4 REQUIRED)
  target_link_libraries(ClimbingStats PUBLIC Stats::Types)

As the ``Stats::Types`` target is a ``PUBLIC`` dependency of ``ClimbingStats``,
downstreams must also find the ``Stats`` package and link to the ``Stats::Types``
library.  The ``Stats`` package should be found in the ``ClimbingStatsConfig.cmake``
file to ensure this.  The ``find_dependency`` macro from the
:module:`CMakeFindDependencyMacro` helps with this by propagating
whether the package is ``REQUIRED``, or ``QUIET`` etc.  All ``REQUIRED``
dependencies of a package should be found in the ``Config.cmake`` file:

.. code-block:: cmake

  include(CMakeFindDependencyMacro)
  find_dependency(Stats 2.6.4)

  include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")
  include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsMacros.cmake")

The ``find_dependency`` macro also sets ``ClimbingStats_FOUND`` to ``False`` if
the dependency is not found, along with a diagnostic that the ``ClimbingStats``
package can not be used without the ``Stats`` package.

If ``COMPONENTS`` are specified when the downstream uses :command:`find_package`,
they are listed in the ``<PackageName>_FIND_COMPONENTS`` variable. If a particular
component is non-optional, then the ``<PackageName>_FIND_REQUIRED_<comp>`` will
be true. This can be tested with logic in the package configuration file:

.. code-block:: cmake

  include(CMakeFindDependencyMacro)
  find_dependency(Stats 2.6.4)

  include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")
  include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsMacros.cmake")

  set(_ClimbingStats_supported_components Plot Table)

  foreach(_comp ${ClimbingStats_FIND_COMPONENTS})
    if (NOT ";${_ClimbingStats_supported_components};" MATCHES ";${_comp};")
      set(ClimbingStats_FOUND False)
      set(ClimbingStats_NOT_FOUND_MESSAGE "Unsupported component: ${_comp}")
    endif()
    include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStats${_comp}Targets.cmake")
  endforeach()

Here, the ``ClimbingStats_NOT_FOUND_MESSAGE`` is set to a diagnosis that the package
could not be found because an invalid component was specified.  This message
variable can be set for any case where the ``_FOUND`` variable is set to ``False``,
and will be displayed to the user.

Creating a Package Configuration File for the Build Tree
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The :command:`export(EXPORT)` command creates an :prop_tgt:`IMPORTED` targets
definition file which is specific to the build-tree, and is not relocatable.
This can similarly be used with a suitable package configuration file and
package version file to define a package for the build tree which may be used
without installation.  Consumers of the build tree can simply ensure that the
:variable:`CMAKE_PREFIX_PATH` contains the build directory, or set the
``ClimbingStats_DIR`` to ``<build_dir>/ClimbingStats`` in the cache.

.. _`Creating Relocatable Packages`:

Creating Relocatable Packages
-----------------------------

A relocatable package must not reference absolute paths of files on
the machine where the package is built that will not exist on the
machines where the package may be installed.

Packages created by :command:`install(EXPORT)` are designed to be relocatable,
using paths relative to the location of the package itself.  When defining
the interface of a target for ``EXPORT``, keep in mind that the include
directories should be specified as relative paths which are relative to the
:variable:`CMAKE_INSTALL_PREFIX`:

.. code-block:: cmake

  target_include_directories(tgt INTERFACE
    # Wrong, not relocatable:
    $<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include/TgtName>
  )

  target_include_directories(tgt INTERFACE
    # Ok, relocatable:
    $<INSTALL_INTERFACE:include/TgtName>
  )

The ``$<INSTALL_PREFIX>``
:manual:`generator expression <cmake-generator-expressions(7)>` may be used as
a placeholder for the install prefix without resulting in a non-relocatable
package.  This is necessary if complex generator expressions are used:

.. code-block:: cmake

  target_include_directories(tgt INTERFACE
    # Ok, relocatable:
    $<INSTALL_INTERFACE:$<$<CONFIG:Debug>:$<INSTALL_PREFIX>/include/TgtName>>
  )

This also applies to paths referencing external dependencies.
It is not advisable to populate any properties which may contain
paths, such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and
:prop_tgt:`INTERFACE_LINK_LIBRARIES`, with paths relevant to dependencies.
For example, this code may not work well for a relocatable package:

.. code-block:: cmake

  target_link_libraries(ClimbingStats INTERFACE
    ${Foo_LIBRARIES} ${Bar_LIBRARIES}
    )
  target_include_directories(ClimbingStats INTERFACE
    "$<INSTALL_INTERFACE:${Foo_INCLUDE_DIRS};${Bar_INCLUDE_DIRS}>"
    )

The referenced variables may contain the absolute paths to libraries
and include directories **as found on the machine the package was made on**.
This would create a package with hard-coded paths to dependencies and not
suitable for relocation.

Ideally such dependencies should be used through their own
:ref:`IMPORTED targets <Imported Targets>` that have their own
:prop_tgt:`IMPORTED_LOCATION` and usage requirement properties
such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` populated
appropriately.  Those imported targets may then be used with
the :command:`target_link_libraries` command for ``ClimbingStats``:

.. code-block:: cmake

  target_link_libraries(ClimbingStats INTERFACE Foo::Foo Bar::Bar)

With this approach the package references its external dependencies
only through the names of :ref:`IMPORTED targets <Imported Targets>`.
When a consumer uses the installed package, the consumer will run the
appropriate :command:`find_package` commands (via the ``find_dependency``
macro described above) to find the dependencies and populate the
imported targets with appropriate paths on their own machine.

Unfortunately many :manual:`modules <cmake-modules(7)>` shipped with
CMake do not yet provide :ref:`IMPORTED targets <Imported Targets>`
because their development pre-dated this approach.  This may improve
incrementally over time.  Workarounds to create relocatable packages
using such modules include:

* When building the package, specify each ``Foo_LIBRARY`` cache
  entry as just a library name, e.g. ``-DFoo_LIBRARY=foo``.  This
  tells the corresponding find module to populate the ``Foo_LIBRARIES``
  with just ``foo`` to ask the linker to search for the library
  instead of hard-coding a path.

* Or, after installing the package content but before creating the
  package installation binary for redistribution, manually replace
  the absolute paths with placeholders for substitution by the
  installation tool when the package is installed.

.. _`Package Registry`:

Package Registry
================

CMake provides two central locations to register packages that have
been built or installed anywhere on a system:

* `User Package Registry`_
* `System Package Registry`_

The registries are especially useful to help projects find packages in
non-standard install locations or directly in their own build trees.
A project may populate either the user or system registry (using its own
means, see below) to refer to its location.
In either case the package should store at the registered location a
`Package Configuration File`_ (``<PackageName>Config.cmake``) and optionally a
`Package Version File`_ (``<PackageName>ConfigVersion.cmake``).

The :command:`find_package` command searches the two package registries
as two of the search steps specified in its documentation.  If it has
sufficient permissions it also removes stale package registry entries
that refer to directories that do not exist or do not contain a matching
package configuration file.

.. _`User Package Registry`:

User Package Registry
---------------------

The User Package Registry is stored in a per-user location.
The :command:`export(PACKAGE)` command may be used to register a project
build tree in the user package registry.  CMake currently provides no
interface to add install trees to the user package registry.  Installers
must be manually taught to register their packages if desired.

On Windows the user package registry is stored in the Windows registry
under a key in ``HKEY_CURRENT_USER``.

A ``<PackageName>`` may appear under registry key::

  HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<PackageName>

as a ``REG_SZ`` value, with arbitrary name, that specifies the directory
containing the package configuration file.

On UNIX platforms the user package registry is stored in the user home
directory under ``~/.cmake/packages``.  A ``<PackageName>`` may appear under
the directory::

  ~/.cmake/packages/<PackageName>

as a file, with arbitrary name, whose content specifies the directory
containing the package configuration file.

.. _`System Package Registry`:

System Package Registry
-----------------------

The System Package Registry is stored in a system-wide location.
CMake currently provides no interface to add to the system package registry.
Installers must be manually taught to register their packages if desired.

On Windows the system package registry is stored in the Windows registry
under a key in ``HKEY_LOCAL_MACHINE``.  A ``<PackageName>`` may appear under
registry key::

  HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<PackageName>

as a ``REG_SZ`` value, with arbitrary name, that specifies the directory
containing the package configuration file.

There is no system package registry on non-Windows platforms.

.. _`Disabling the Package Registry`:

Disabling the Package Registry
------------------------------

In some cases using the Package Registries is not desirable. CMake
allows one to disable them using the following variables:

* The :command:`export(PACKAGE)` command does not populate the user
  package registry when :policy:`CMP0090` is set to ``NEW`` unless the
  :variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable explicitly enables it.
  When :policy:`CMP0090` is *not* set to ``NEW`` then
  :command:`export(PACKAGE)` populates the user package registry unless
  the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable explicitly
  disables it.
* :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` disables the
  User Package Registry in all the :command:`find_package` calls when
  set to ``FALSE``.
* Deprecated :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` disables the
  User Package Registry in all the :command:`find_package` calls when set
  to ``TRUE``. This variable is ignored when
  :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` has been set.
* :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` disables
  the System Package Registry in all the :command:`find_package` calls.

Package Registry Example
------------------------

A simple convention for naming package registry entries is to use content
hashes.  They are deterministic and unlikely to collide
(:command:`export(PACKAGE)` uses this approach).
The name of an entry referencing a specific directory is simply the content
hash of the directory path itself.

If a project arranges for package registry entries to exist, such as::

 > reg query HKCU\Software\Kitware\CMake\Packages\MyPackage
 HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\MyPackage
  45e7d55f13b87179bb12f907c8de6fc4 REG_SZ c:/Users/Me/Work/lib/cmake/MyPackage
  7b4a9844f681c80ce93190d4e3185db9 REG_SZ c:/Users/Me/Work/MyPackage-build

or::

 $ cat ~/.cmake/packages/MyPackage/7d1fb77e07ce59a81bed093bbee945bd
 /home/me/work/lib/cmake/MyPackage
 $ cat ~/.cmake/packages/MyPackage/f92c1db873a1937f3100706657c63e07
 /home/me/work/MyPackage-build

then the ``CMakeLists.txt`` code:

.. code-block:: cmake

  find_package(MyPackage)

will search the registered locations for package configuration files
(``MyPackageConfig.cmake``).  The search order among package registry
entries for a single package is unspecified and the entry names
(hashes in this example) have no meaning.  Registered locations may
contain package version files (``MyPackageConfigVersion.cmake``) to
tell :command:`find_package` whether a specific location is suitable
for the version requested.

Package Registry Ownership
--------------------------

Package registry entries are individually owned by the project installations
that they reference.  A package installer is responsible for adding its own
entry and the corresponding uninstaller is responsible for removing it.

The :command:`export(PACKAGE)` command populates the user package registry
with the location of a project build tree.  Build trees tend to be deleted by
developers and have no "uninstall" event that could trigger removal of their
entries.  In order to keep the registries clean the :command:`find_package`
command automatically removes stale entries it encounters if it has sufficient
permissions.  CMake provides no interface to remove an entry referencing an
existing build tree once :command:`export(PACKAGE)` has been invoked.
However, if the project removes its package configuration file from the build
tree then the entry referencing the location will be considered stale.


code:
.. cmake-manual-description: CMake Policies Reference

cmake-policies(7)
*****************

.. only:: html

   .. contents::

Introduction
============

Policies in CMake are used to preserve backward compatible behavior
across multiple releases.  When a new policy is introduced, newer CMake
versions will begin to warn about the backward compatible behavior.  It
is possible to disable the warning by explicitly requesting the OLD, or
backward compatible behavior using the :command:`cmake_policy` command.
It is also possible to request ``NEW``, or non-backward compatible behavior
for a policy, also avoiding the warning.  Each policy can also be set to
either ``NEW`` or ``OLD`` behavior explicitly on the command line with the
:variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable.

A policy is a deprecation mechanism and not a reliable feature toggle.
A policy should almost never be set to ``OLD``, except to silence warnings
in an otherwise frozen or stable codebase, or temporarily as part of a
larger migration path. The ``OLD`` behavior of each policy is undesirable
and will be replaced with an error condition in a future release.

The :command:`cmake_minimum_required` command does more than report an
error if a too-old version of CMake is used to build a project.  It
also sets all policies introduced in that CMake version or earlier to
``NEW`` behavior.  To manage policies without increasing the minimum required
CMake version, the :command:`if(POLICY)` command may be used:

.. code-block:: cmake

  if(POLICY CMP0990)
    cmake_policy(SET CMP0990 NEW)
  endif()

This has the effect of using the ``NEW`` behavior with newer CMake releases which
users may be using and not issuing a compatibility warning.

The setting of a policy is confined in some cases to not propagate to the
parent scope.  For example, if the files read by the :command:`include` command
or the :command:`find_package` command contain a use of :command:`cmake_policy`,
that policy setting will not affect the caller by default.  Both commands accept
an optional ``NO_POLICY_SCOPE`` keyword to control this behavior.

The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used
to determine whether to report an error on use of deprecated macros or
functions.

Policies Introduced by CMake 3.29
=================================

.. toctree::
   :maxdepth: 1

   CMP0161: CPACK_PRODUCTBUILD_DOMAINS defaults to true. </policy/CMP0161>
   CMP0160: More read-only target properties now error when trying to set them. </policy/CMP0160>
   CMP0159: file(STRINGS) with REGEX updates CMAKE_MATCH_<n>. </policy/CMP0159>
   CMP0158: add_test() honors CMAKE_CROSSCOMPILING_EMULATOR only when cross-compiling. </policy/CMP0158>
   CMP0157: Swift compilation mode is selected by an abstraction. </policy/CMP0157>
   CMP0156: De-duplicate libraries on link lines based on linker capabilities. </policy/CMP0156>

Policies Introduced by CMake 3.28
=================================

.. toctree::
   :maxdepth: 1

   CMP0155: C++ sources in targets with at least C++20 are scanned for imports when supported. </policy/CMP0155>
   CMP0154: Generated files are private by default in targets using file sets. </policy/CMP0154>
   CMP0153: The exec_program command should not be called. </policy/CMP0153>
   CMP0152: file(REAL_PATH) resolves symlinks before collapsing ../ components.  </policy/CMP0152>

Policies Introduced by CMake 3.27
=================================

.. toctree::
   :maxdepth: 1

   CMP0151: AUTOMOC include directory is a system include directory by default. </policy/CMP0151>
   CMP0150: ExternalProject_Add and FetchContent_Declare treat relative git repository paths as being relative to parent project's remote. </policy/CMP0150>
   CMP0149: Visual Studio generators select latest Windows SDK by default. </policy/CMP0149>
   CMP0148: The FindPythonInterp and FindPythonLibs modules are removed. </policy/CMP0148>
   CMP0147: Visual Studio generators build custom commands in parallel. </policy/CMP0147>
   CMP0146: The FindCUDA module is removed. </policy/CMP0146>
   CMP0145: The Dart and FindDart modules are removed. </policy/CMP0145>
   CMP0144: find_package uses upper-case PACKAGENAME_ROOT variables. </policy/CMP0144>

Policies Introduced by CMake 3.26
=================================

.. toctree::
   :maxdepth: 1

   CMP0143: USE_FOLDERS global property is treated as ON by default. </policy/CMP0143>

Policies Introduced by CMake 3.25
=================================

.. toctree::
   :maxdepth: 1

   CMP0142: The Xcode generator does not append per-config suffixes to library search paths. </policy/CMP0142>
   CMP0141: MSVC debug information format flags are selected by an abstraction. </policy/CMP0141>
   CMP0140: The return() command checks its arguments. </policy/CMP0140>

Policies Introduced by CMake 3.24
=================================

.. toctree::
   :maxdepth: 1

   CMP0139: The if() command supports path comparisons using PATH_EQUAL operator. </policy/CMP0139>
   CMP0138: CheckIPOSupported uses flags from calling project. </policy/CMP0138>
   CMP0137: try_compile() passes platform variables in project mode. </policy/CMP0137>
   CMP0136: Watcom runtime library flags are selected by an abstraction. </policy/CMP0136>
   CMP0135: ExternalProject ignores timestamps in archives by default for the URL download method. </policy/CMP0135>
   CMP0134: Fallback to "HOST" Windows registry view when "TARGET" view is not usable. </policy/CMP0134>
   CMP0133: The CPack module disables SLA by default in the CPack DragNDrop Generator. </policy/CMP0133>
   CMP0132: Do not set compiler environment variables on first run. </policy/CMP0132>
   CMP0131: LINK_LIBRARIES supports the LINK_ONLY generator expression. </policy/CMP0131>
   CMP0130: while() diagnoses condition evaluation errors. </policy/CMP0130>

Policies Introduced by CMake 3.23
=================================

.. toctree::
   :maxdepth: 1

   CMP0129: Compiler id for MCST LCC compilers is now LCC, not GNU. </policy/CMP0129>

Policies Introduced by CMake 3.22
=================================

.. toctree::
   :maxdepth: 1

   CMP0128: Selection of language standard and extension flags improved. </policy/CMP0128>
   CMP0127: cmake_dependent_option() supports full Condition Syntax. </policy/CMP0127>

Policies Introduced by CMake 3.21
=================================

.. toctree::
   :maxdepth: 1

   CMP0126: set(CACHE) does not remove a normal variable of the same name. </policy/CMP0126>
   CMP0125: find_(path|file|library|program) have consistent behavior for cache variables. </policy/CMP0125>
   CMP0124: foreach() loop variables are only available in the loop scope. </policy/CMP0124>
   CMP0123: ARMClang cpu/arch compile and link flags must be set explicitly. </policy/CMP0123>
   CMP0122: UseSWIG use standard library name conventions for csharp language. </policy/CMP0122>
   CMP0121: The list command detects invalid indices. </policy/CMP0121>

Policies Introduced by CMake 3.20
=================================

.. toctree::
   :maxdepth: 1

   CMP0120: The WriteCompilerDetectionHeader module is removed. </policy/CMP0120>
   CMP0119: LANGUAGE source file property explicitly compiles as language. </policy/CMP0119>
   CMP0118: The GENERATED source file property is now visible in all directories. </policy/CMP0118>
   CMP0117: MSVC RTTI flag /GR is not added to CMAKE_CXX_FLAGS by default. </policy/CMP0117>
   CMP0116: Ninja generators transform DEPFILEs from add_custom_command(). </policy/CMP0116>
   CMP0115: Source file extensions must be explicit. </policy/CMP0115>

Policies Introduced by CMake 3.19
=================================

.. toctree::
   :maxdepth: 1

   CMP0114: ExternalProject step targets fully adopt their steps. </policy/CMP0114>
   CMP0113: Makefile generators do not repeat custom commands from target dependencies. </policy/CMP0113>
   CMP0112: Target file component generator expressions do not add target dependencies. </policy/CMP0112>
   CMP0111: An imported target missing its location property fails during generation. </policy/CMP0111>
   CMP0110: add_test() supports arbitrary characters in test names. </policy/CMP0110>
   CMP0109: find_program() requires permission to execute but not to read. </policy/CMP0109>

Policies Introduced by CMake 3.18
=================================

.. toctree::
   :maxdepth: 1

   CMP0108: A target cannot link to itself through an alias. </policy/CMP0108>
   CMP0107: An ALIAS target cannot overwrite another target. </policy/CMP0107>
   CMP0106: The Documentation module is removed. </policy/CMP0106>
   CMP0105: Device link step uses the link options. </policy/CMP0105>
   CMP0104: CMAKE_CUDA_ARCHITECTURES now detected for NVCC, empty CUDA_ARCHITECTURES not allowed. </policy/CMP0104>
   CMP0103: Multiple export() with same FILE without APPEND is not allowed. </policy/CMP0103>

Policies Introduced by CMake 3.17
=================================

.. toctree::
   :maxdepth: 1

   CMP0102: mark_as_advanced() does nothing if a cache entry does not exist. </policy/CMP0102>
   CMP0101: target_compile_options honors BEFORE keyword in all scopes. </policy/CMP0101>
   CMP0100: Let AUTOMOC and AUTOUIC process .hh header files. </policy/CMP0100>
   CMP0099: Link properties are transitive over private dependency on static libraries. </policy/CMP0099>
   CMP0098: FindFLEX runs flex in CMAKE_CURRENT_BINARY_DIR when executing. </policy/CMP0098>

Policies Introduced by CMake 3.16
=================================

.. toctree::
   :maxdepth: 1

   CMP0097: ExternalProject_Add with GIT_SUBMODULES "" initializes no submodules. </policy/CMP0097>
   CMP0096: project() preserves leading zeros in version components. </policy/CMP0096>
   CMP0095: RPATH entries are properly escaped in the intermediary CMake install script. </policy/CMP0095>

Policies Introduced by CMake 3.15
=================================

.. toctree::
   :maxdepth: 1

   CMP0094: FindPython3, FindPython2 and FindPython use LOCATION for lookup strategy. </policy/CMP0094>
   CMP0093: FindBoost reports Boost_VERSION in x.y.z format. </policy/CMP0093>
   CMP0092: MSVC warning flags are not in CMAKE_{C,CXX}_FLAGS by default. </policy/CMP0092>
   CMP0091: MSVC runtime library flags are selected by an abstraction. </policy/CMP0091>
   CMP0090: export(PACKAGE) does not populate package registry by default. </policy/CMP0090>
   CMP0089: Compiler id for IBM Clang-based XL compilers is now XLClang. </policy/CMP0089>

Policies Introduced by CMake 3.14
=================================

.. toctree::
   :maxdepth: 1

   CMP0088: FindBISON runs bison in CMAKE_CURRENT_BINARY_DIR when executing. </policy/CMP0088>
   CMP0087: install(SCRIPT | CODE) supports generator expressions. </policy/CMP0087>
   CMP0086: UseSWIG honors SWIG_MODULE_NAME via -module flag. </policy/CMP0086>
   CMP0085: IN_LIST generator expression handles empty list items. </policy/CMP0085>
   CMP0084: The FindQt module does not exist for find_package(). </policy/CMP0084>
   CMP0083: Add PIE options when linking executable. </policy/CMP0083>
   CMP0082: Install rules from add_subdirectory() are interleaved with those in caller. </policy/CMP0082>

Policies Introduced by CMake 3.13
=================================

.. toctree::
   :maxdepth: 1

   CMP0081: Relative paths not allowed in LINK_DIRECTORIES target property. </policy/CMP0081>
   CMP0080: BundleUtilities cannot be included at configure time. </policy/CMP0080>
   CMP0079: target_link_libraries allows use with targets in other directories. </policy/CMP0079>
   CMP0078: UseSWIG generates standard target names. </policy/CMP0078>
   CMP0077: option() honors normal variables. </policy/CMP0077>
   CMP0076: target_sources() command converts relative paths to absolute. </policy/CMP0076>

Policies Introduced by CMake 3.12
=================================

.. toctree::
   :maxdepth: 1

   CMP0075: Include file check macros honor CMAKE_REQUIRED_LIBRARIES. </policy/CMP0075>
   CMP0074: find_package uses PackageName_ROOT variables. </policy/CMP0074>
   CMP0073: Do not produce legacy _LIB_DEPENDS cache entries. </policy/CMP0073>

Policies Introduced by CMake 3.11
=================================

.. toctree::
   :maxdepth: 1

   CMP0072: FindOpenGL prefers GLVND by default when available. </policy/CMP0072>

Policies Introduced by CMake 3.10
=================================

.. toctree::
   :maxdepth: 1

   CMP0071: Let AUTOMOC and AUTOUIC process GENERATED files. </policy/CMP0071>
   CMP0070: Define file(GENERATE) behavior for relative paths. </policy/CMP0070>

Policies Introduced by CMake 3.9
================================

.. toctree::
   :maxdepth: 1

   CMP0069: INTERPROCEDURAL_OPTIMIZATION is enforced when enabled. </policy/CMP0069>
   CMP0068: RPATH settings on macOS do not affect install_name. </policy/CMP0068>

Policies Introduced by CMake 3.8
================================

.. toctree::
   :maxdepth: 1

   CMP0067: Honor language standard in try_compile() source-file signature. </policy/CMP0067>

Policies Introduced by CMake 3.7
================================

.. toctree::
   :maxdepth: 1

   CMP0066: Honor per-config flags in try_compile() source-file signature. </policy/CMP0066>

Policies Introduced by CMake 3.4
================================

.. toctree::
   :maxdepth: 1

   CMP0065: Do not add flags to export symbols from executables without the ENABLE_EXPORTS target property. </policy/CMP0065>
   CMP0064: Support new TEST if() operator. </policy/CMP0064>

Policies Introduced by CMake 3.3
================================

.. toctree::
   :maxdepth: 1

   CMP0063: Honor visibility properties for all target types. </policy/CMP0063>
   CMP0062: Disallow install() of export() result. </policy/CMP0062>
   CMP0061: CTest does not by default tell make to ignore errors (-i). </policy/CMP0061>
   CMP0060: Link libraries by full path even in implicit directories. </policy/CMP0060>
   CMP0059: Do not treat DEFINITIONS as a built-in directory property. </policy/CMP0059>
   CMP0058: Ninja requires custom command byproducts to be explicit. </policy/CMP0058>
   CMP0057: Support new IN_LIST if() operator. </policy/CMP0057>

Policies Introduced by CMake 3.2
================================

.. toctree::
   :maxdepth: 1

   CMP0056: Honor link flags in try_compile() source-file signature. </policy/CMP0056>
   CMP0055: Strict checking for break() command. </policy/CMP0055>

Policies Introduced by CMake 3.1
================================

.. toctree::
   :maxdepth: 1

   CMP0054: Only interpret if() arguments as variables or keywords when unquoted. </policy/CMP0054>
   CMP0053: Simplify variable reference and escape sequence evaluation. </policy/CMP0053>
   CMP0052: Reject source and build dirs in installed INTERFACE_INCLUDE_DIRECTORIES. </policy/CMP0052>
   CMP0051: List TARGET_OBJECTS in SOURCES target property. </policy/CMP0051>

Policies Introduced by CMake 3.0
================================

.. toctree::
   :maxdepth: 1

   CMP0050: Disallow add_custom_command SOURCE signatures. </policy/CMP0050>
   CMP0049: Do not expand variables in target source entries. </policy/CMP0049>
   CMP0048: project() command manages VERSION variables. </policy/CMP0048>
   CMP0047: Use QCC compiler id for the qcc drivers on QNX. </policy/CMP0047>
   CMP0046: Error on non-existent dependency in add_dependencies. </policy/CMP0046>
   CMP0045: Error on non-existent target in get_target_property. </policy/CMP0045>
   CMP0044: Case sensitive Lang_COMPILER_ID generator expressions. </policy/CMP0044>
   CMP0043: Ignore COMPILE_DEFINITIONS_Config properties. </policy/CMP0043>
   CMP0042: MACOSX_RPATH is enabled by default. </policy/CMP0042>
   CMP0041: Error on relative include with generator expression. </policy/CMP0041>
   CMP0040: The target in the TARGET signature of add_custom_command() must exist. </policy/CMP0040>
   CMP0039: Utility targets may not have link dependencies. </policy/CMP0039>
   CMP0038: Targets may not link directly to themselves. </policy/CMP0038>
   CMP0037: Target names should not be reserved and should match a validity pattern. </policy/CMP0037>
   CMP0036: The build_name command should not be called. </policy/CMP0036>
   CMP0035: The variable_requires command should not be called. </policy/CMP0035>
   CMP0034: The utility_source command should not be called. </policy/CMP0034>
   CMP0033: The export_library_dependencies command should not be called. </policy/CMP0033>
   CMP0032: The output_required_files command should not be called. </policy/CMP0032>
   CMP0031: The load_command command should not be called. </policy/CMP0031>
   CMP0030: The use_mangled_mesa command should not be called. </policy/CMP0030>
   CMP0029: The subdir_depends command should not be called. </policy/CMP0029>
   CMP0028: Double colon in target name means ALIAS or IMPORTED target. </policy/CMP0028>
   CMP0027: Conditionally linked imported targets with missing include directories. </policy/CMP0027>
   CMP0026: Disallow use of the LOCATION target property. </policy/CMP0026>
   CMP0025: Compiler id for Apple Clang is now AppleClang. </policy/CMP0025>
   CMP0024: Disallow include export result. </policy/CMP0024>

Policies Introduced by CMake 2.8
================================

.. toctree::
   :maxdepth: 1

   CMP0023: Plain and keyword target_link_libraries signatures cannot be mixed. </policy/CMP0023>
   CMP0022: INTERFACE_LINK_LIBRARIES defines the link interface. </policy/CMP0022>
   CMP0021: Fatal error on relative paths in INCLUDE_DIRECTORIES target property. </policy/CMP0021>
   CMP0020: Automatically link Qt executables to qtmain target on Windows. </policy/CMP0020>
   CMP0019: Do not re-expand variables in include and link information. </policy/CMP0019>
   CMP0018: Ignore CMAKE_SHARED_LIBRARY_Lang_FLAGS variable. </policy/CMP0018>
   CMP0017: Prefer files from the CMake module directory when including from there. </policy/CMP0017>
   CMP0016: target_link_libraries() reports error if its only argument is not a target. </policy/CMP0016>
   CMP0015: link_directories() treats paths relative to the source dir. </policy/CMP0015>
   CMP0014: Input directories must have CMakeLists.txt. </policy/CMP0014>
   CMP0013: Duplicate binary directories are not allowed. </policy/CMP0013>
   CMP0012: if() recognizes numbers and boolean constants. </policy/CMP0012>

Policies Introduced by CMake 2.6
================================

.. toctree::
   :maxdepth: 1

   CMP0011: Included scripts do automatic cmake_policy PUSH and POP. </policy/CMP0011>
   CMP0010: Bad variable reference syntax is an error. </policy/CMP0010>
   CMP0009: FILE GLOB_RECURSE calls should not follow symlinks by default. </policy/CMP0009>
   CMP0008: Libraries linked by full-path must have a valid library file name. </policy/CMP0008>
   CMP0007: list command no longer ignores empty elements. </policy/CMP0007>
   CMP0006: Installing MACOSX_BUNDLE targets requires a BUNDLE DESTINATION. </policy/CMP0006>
   CMP0005: Preprocessor definition values are now escaped automatically. </policy/CMP0005>
   CMP0004: Libraries linked may not have leading or trailing whitespace. </policy/CMP0004>
   CMP0003: Libraries linked via full path no longer produce linker search paths. </policy/CMP0003>
   CMP0002: Logical target names must be globally unique. </policy/CMP0002>
   CMP0001: CMAKE_BACKWARDS_COMPATIBILITY should no longer be used. </policy/CMP0001>
   CMP0000: A minimum required CMake version must be specified. </policy/CMP0000>