mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-06 21:59:54 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'doc-find_package-root' into release-3.12

Browse Source 
Merge-request: !2225
This commit is contained in:
Brad King
2018-07-20 09:45:04 -04:00
parent 8cefa2cba4 492ade276b
commit f478176236
10 changed files with 64 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
Help/command/FIND_XXX.txt
View File

@@ -62,8 +62,11 @@ added to the search.
If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| replace::
|prefix_XXX_SUBDIR| for each ``<prefix>`` in ``PackageName_ROOT`` if called
from within a find module
|prefix_XXX_SUBDIR| for each ``<prefix>`` in the
:variable:`<PackageName>_ROOT` CMake variable and the
:envvar:`<PackageName>_ROOT` environment variable if
called from within a find module loaded by
:command:`find_package(<PackageName>)`
.. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace::
|prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_PREFIX_PATH`
@@ -76,13 +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, search prefix paths unique to the
current package being found. Specifically look in the ``PackageName_ROOT``
CMake and environment variables. 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}``,
``ParentPackage_ROOT``, ``ENV{ParentPackage_ROOT}``, etc.
1. If called from within a find module loaded by
:command:`find_package(<PackageName>)`, search prefixes unique to 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}``,
``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc.
This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed.
See policy :policy:`CMP0074`.

6
Help/command/find_package.rst
View File

@@ -262,8 +262,10 @@ The set of installation prefixes is constructed using the following
steps. If ``NO_DEFAULT_PATH`` is specified all ``NO_*`` options are
enabled.
1. Search paths specified in the ``PackageName_ROOT`` CMake and environment
variables. The package root variables are maintained as a stack so if
1. Search paths specified in the :variable:`<PackageName>_ROOT` CMake
variable and the :envvar:`<PackageName>_ROOT` environment variable,
where ``<PackageName>`` is the package to be found.
The package root variables are maintained as a stack so if
called from within a find module, root paths from the parent's find
module will also be searched after paths for the current package.
This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed.

15
Help/envvar/PackageName_ROOT.rst Normal file
View File

@@ -0,0 +1,15 @@
<PackageName>_ROOT
------------------
Calls to :command:`find_package(<PackageName>)` will search in prefixes
specified by the ``<PackageName>_ROOT`` environment variable, where
``<PackageName>`` is the name given to the ``find_package`` call
and ``_ROOT`` is literal. For example, ``find_package(Foo)`` will search
prefixes specified in the ``Foo_ROOT`` environment variable (if set).
See policy :policy:`CMP0074`.
This variable may hold a single prefix or a list of prefixes separated
by ``:`` on UNIX or ``;`` on Windows (the same as the ``PATH`` environment
variable convention on those platforms).
See also the :variable:`<PackageName>_ROOT` CMake variable.

1
Help/manual/cmake-env-variables.7.rst
View File

@@ -20,6 +20,7 @@ Environment Variables that Control the Build
/envvar/DESTDIR
/envvar/LDFLAGS
/envvar/MACOSX_DEPLOYMENT_TARGET
/envvar/PackageName_ROOT
Environment Variables for Languages
===================================

1
Help/manual/cmake-variables.7.rst
View File

@@ -204,6 +204,7 @@ Variables that Change Behavior
/variable/CMAKE_WARN_DEPRECATED
/variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION
/variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY
/variable/PackageName_ROOT
Variables that Describe the System
==================================

15
Help/policy/CMP0074.rst
View File

@@ -1,18 +1,19 @@
CMP0074
-------
:command:`find_package` uses ``PackageName_ROOT`` variables.
:command:`find_package` uses ``<PackageName>_ROOT`` variables.
In CMake 3.12 and above the ``find_package(PackageName)`` command now searches
a prefix specified by a ``PackageName_ROOT`` CMake or environment variable.
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.
``<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 ``PackageName_ROOT``
variables.
The ``OLD`` behavior for this policy is to ignore ``<PackageName>_ROOT``
variables. The ``NEW`` behavior for this policy is to use
``<PackageName>_ROOT`` variables.
This policy was introduced in CMake version 3.12. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior.

5
Help/release/3.12.rst
View File

@@ -46,8 +46,9 @@ Commands
were added to expose ``TOUCH`` functionality without having to use
CMake's command-line tool mode with :command:`execute_process`.
* The :command:`find_package` command now searches a prefix specified by
a ``PackageName_ROOT`` CMake or environment variable. Package roots are
* The :command:`find_package` command now searches prefixes specified by
the :variable:`<PackageName>_ROOT` CMake variable and the
:envvar:`<PackageName>_ROOT` environment variable. Package roots are
maintained as a stack so nested calls to all ``find_*`` commands inside
find modules also search the roots as prefixes.
See policy :policy:`CMP0074`.

14
Help/variable/PackageName_ROOT.rst Normal file
View File

@@ -0,0 +1,14 @@
<PackageName>_ROOT
------------------
Calls to :command:`find_package(<PackageName>)` will search in prefixes
specified by the ``<PackageName>_ROOT`` CMake variable, where
``<PackageName>`` is the name given to the ``find_package`` call
and ``_ROOT`` is literal. For example, ``find_package(Foo)`` will search
prefixes specified in the ``Foo_ROOT`` CMake variable (if set).
See policy :policy:`CMP0074`.
This variable may hold a single prefix or a
:ref:`;-list <CMake Language Lists>` of multiple prefixes.
See also the :envvar:`<PackageName>_ROOT` environment variable.

4
Source/cmPolicies.h
View File

@@ -219,8 +219,8 @@ class cmMakefile;
SELECT(POLICY, CMP0073, \
"Do not produce legacy _LIB_DEPENDS cache entries.", 3, 12, 0, \
cmPolicies::WARN) \
SELECT(POLICY, CMP0074, "find_package uses PackageName_ROOT variables.", 3, \
12, 0, cmPolicies::WARN) \
SELECT(POLICY, CMP0074, "find_package uses <PackageName>_ROOT variables.", \
3, 12, 0, cmPolicies::WARN) \
SELECT(POLICY, CMP0075, \
"Include file check macros honor CMAKE_REQUIRED_LIBRARIES.", 3, 12, \
0, cmPolicies::WARN)

2
Tests/RunCMake/find_package/CMP0074-WARN-stderr.txt
View File

@@ -3,7 +3,7 @@ Foo_ROOT :<base>/foo/cmake_root
ENV{Foo_ROOT} :<base>/foo/env_root
+
CMake Warning \(dev\) at CMP0074-common.cmake:[0-9]+ \(find_package\):
Policy CMP0074 is not set: find_package uses PackageName_ROOT variables.
Policy CMP0074 is not set: find_package uses <PackageName>_ROOT variables.
Run "cmake --help-policy CMP0074" for policy details. Use the cmake_policy
command to set the policy and suppress this warning.