Commit a575fbc3 authored by Brad King's avatar Brad King
Browse files

Merge branch 'docs-find-vars' into release-3.16

Merge-request: !3952
parents 62267715 a0a7a45d
......@@ -79,15 +79,16 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
|prefix_XXX_SUBDIR| for each ``<prefix>`` in
:variable:`CMAKE_SYSTEM_PREFIX_PATH`
1. If called from within a find module loaded by
1. If called from within a find module or any other script loaded by a call to
:command:`find_package(<PackageName>)`, search prefixes unique to the
current package being found. Specifically look in the
current package being found. Specifically, look in the
:variable:`<PackageName>_ROOT` CMake variable and the
:envvar:`<PackageName>_ROOT` environment variable.
The package root variables are maintained as a stack so if called from
nested find modules, root paths from the parent's find module will be
searched after paths from the current module,
i.e. ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``,
The package root variables are maintained as a stack, so if called from
nested find modules or config packages, root paths from the parent's find
module or config package will be searched after paths from the current
module or package. In other words, the search order would be
``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``,
``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc.
This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting
the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``.
......
......@@ -7,9 +7,9 @@ In CMake 3.12 and above the :command:`find_package(<PackageName>)` command now
searches prefixes specified by the :variable:`<PackageName>_ROOT` CMake
variable and the :envvar:`<PackageName>_ROOT` environment variable.
Package roots are maintained as a stack so nested calls to all ``find_*``
commands inside find modules also search the roots as prefixes. This policy
provides compatibility with projects that have not been updated to avoid using
``<PackageName>_ROOT`` variables for other purposes.
commands inside find modules and config packages also search the roots as
prefixes. 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. The ``NEW`` behavior for this policy is to use
......
......@@ -75,28 +75,27 @@ Commands
* The :command:`find_file`, :command:`find_library`, :command:`find_path`,
:command:`find_package`, and :command:`find_program` commands have learned to
check the following variables to control searching
check the following variables to control the default behavior for groups of
search locations:
* :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` - Controls the searching
the cmake-specific environment variables.
* :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` - Controls the default
behavior of searching the :variable:`<PackageName>_ROOT` variables.
* :variable:`CMAKE_FIND_USE_CMAKE_PATH` - Controls the searching the
cmake-specific cache variables.
* :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` - Controls the default
behavior of searching the CMake-specific environment variables.
* :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` - Controls the searching
cmake platform specific variables.
* :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` - Controls the default
behavior of searching the standard system environment variables.
* :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` - Controls the searching of
:variable:`<PackageName>_ROOT` variables.
* :variable:`CMAKE_FIND_USE_CMAKE_PATH` - Controls the default behavior of
searching the CMake-specific cache variables.
* :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` - Controls the searching
the standard system environment variables.
* :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` - Controls the default
behavior of searching the platform-specific CMake variables.
* The :command:`find_package` command has learned to check the following
variables to control searching
* :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` - Controls the searching the
cmake user registry.
* The :command:`find_package` command has learned to check the
:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` variable to control the default
behavior of searching the CMake user package registry.
* The :command:`message` command learned indentation control with the new
:variable:`CMAKE_MESSAGE_INDENT` variable.
......
......@@ -8,8 +8,8 @@ CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY
By default this variable is not set. If neither
:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` nor
``CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY`` is set, then
:command:`find_package()` will use the `User Package Registry` unless the
`NO_CMAKE_PACKAGE_REGISTRY` option is provided.
:command:`find_package()` will use the :ref:`User Package Registry`
unless the ``NO_CMAKE_PACKAGE_REGISTRY`` option is provided.
``CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY`` is ignored if
:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` is set.
......
CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH
-------------------------------------
Controls the searching the cmake-specific environment variables by the
:command:`find_program`, :command:`find_library`, :command:`find_file`,
:command:`find_path`, and command:`find_package` commands.
Controls the default behavior of the following commands for whether or not to
search paths provided by cmake-specific environment variables:
* :command:`find_program`
* :command:`find_library`
* :command:`find_file`
* :command:`find_path`
* :command:`find_package`
This is useful in cross-compiling environments.
By default this variable is not set, which is equivalent to it having
a value of ``TRUE``. Explicit options given to the :command:`find_program`,
:command:`find_library`, :command:`find_file`, and :command:`find_path`
commands take precedence over this variable.
a value of ``TRUE``. Explicit options given to the above commands
take precedence over this variable.
See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`,
:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`,
......
CMAKE_FIND_USE_CMAKE_PATH
-------------------------
Controls the searching the cmake-specific cache variables by the
:command:`find_program`, :command:`find_library`, :command:`find_file`,
:command:`find_path`, and command:`find_package` commands.
Controls the default behavior of the following commands for whether or not to
search paths provided by cmake-specific cache variables:
* :command:`find_program`
* :command:`find_library`
* :command:`find_file`
* :command:`find_path`
* :command:`find_package`
This is useful in cross-compiling environments.
By default this variable is not set, which is equivalent to it having
a value of ``TRUE``. Explicit options given to the :command:`find_program`,
:command:`find_library`, :command:`find_file`, and :command:`find_path`
commands take precedence over this variable.
a value of ``TRUE``. Explicit options given to the above commands
take precedence over this variable.
See also the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`,
:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`,
......
CMAKE_FIND_USE_CMAKE_SYSTEM_PATH
--------------------------------
Controls the searching cmake platform specific variables by the
:command:`find_program`, :command:`find_library`, :command:`find_file`,
:command:`find_path`, and command:`find_package` commands.
Controls the default behavior of the following commands for whether or not to
search paths provided by platform-specific cmake variables:
* :command:`find_program`
* :command:`find_library`
* :command:`find_file`
* :command:`find_path`
* :command:`find_package`
This is useful in cross-compiling environments.
By default this variable is not set, which is equivalent to it having
a value of ``TRUE``. Explicit options given to the :command:`find_program`,
:command:`find_library`, :command:`find_file`, and :command:`find_path`
commands take precedence over this variable.
a value of ``TRUE``. Explicit options given to the above commands
take precedence over this variable.
See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`,
:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`,
......
CMAKE_FIND_USE_PACKAGE_REGISTRY
-------------------------------
Controls the searching the :ref:`User Package Registry` by the :command:`find_package`
command.
Controls the default behavior of the :command:`find_package` command for
whether or not to search paths provided by the :ref:`User Package Registry`.
By default this variable is not set and the behavior will fall back
to that determined by the deprecated :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY`
variable. If that is also not set, then `find_package()` will use the
`User Package Registry` unless the `NO_CMAKE_PACKAGE_REGISTRY` option
to that determined by the deprecated
:variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` variable. If that is
also not set, then :command:`find_package` will use the
:ref:`User Package Registry` unless the ``NO_CMAKE_PACKAGE_REGISTRY`` option
is provided.
This variable takes precedence over :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY`
when both are set.
This variable takes precedence over
:variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` when both are set.
In some cases, for example to locate only system wide installations, it
is not desirable to use the :ref:`User Package Registry` when searching
for packages. If the :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`
for packages. If the :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`
variable is ``FALSE``, all the :command:`find_package` commands will skip
the :ref:`User Package Registry` as if they were called with the
``NO_CMAKE_PACKAGE_REGISTRY`` argument.
See also :ref:`Disabling the Package Registry`.
See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`,
See also :ref:`Disabling the Package Registry` and the
:variable:`CMAKE_FIND_USE_CMAKE_PATH`,
:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`,
:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`,
:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`,
......
CMAKE_FIND_USE_PACKAGE_ROOT_PATH
--------------------------------
Controls the searching of :variable:`<PackageName>_ROOT` variables by the
:command:`find_program`, :command:`find_library`, :command:`find_file`,
:command:`find_path`, and command:`find_package` commands.
This is useful in cross-compiling environments.
Controls the default behavior of the following commands for whether or not to
search paths provided by :variable:`<PackageName>_ROOT` variables:
* :command:`find_program`
* :command:`find_library`
* :command:`find_file`
* :command:`find_path`
* :command:`find_package`
By default this variable is not set, which is equivalent to it having
a value of ``TRUE``. Explicit options given to the :command:`find_program`,
:command:`find_library`, :command:`find_file`, and :command:`find_path`
commands take precedence over this variable.
a value of ``TRUE``. Explicit options given to the above commands
take precedence over this variable.
See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`,
:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`,
......
CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH
--------------------------------------
Controls the searching the standard system environment variables by the
:command:`find_program`, :command:`find_library`, :command:`find_file`,
:command:`find_path`, and command:`find_package` commands.
Controls the default behavior of the following commands for whether or not to
search paths provided by standard system environment variables:
* :command:`find_program`
* :command:`find_library`
* :command:`find_file`
* :command:`find_path`
* :command:`find_package`
This is useful in cross-compiling environments.
By default this variable is not set, which is equivalent to it having
a value of ``TRUE``. Explicit options given to the :command:`find_program`,
:command:`find_library`, :command:`find_file`, and :command:`find_path`
commands take precedence over this variable.
a value of ``TRUE``. Explicit options given to the above commands
take precedence over this variable.
See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`,
:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`,
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment