reactos/CMake
1
0
Fork 0
mirror of https://github.com/reactos/CMake.git synced 2025-01-20 18:34:22 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Help: Add explicit <PackageName>_ROOT variable documentation

Browse Source 
Add documentation for both the CMake variable and environment variable
of this name pattern.  Update references to these names to link to their
documents.  Clarify the pattern used to construct their names.
This commit is contained in:
Brad King 2018-07-19 14:19:42 -04:00
parent f84c15ef2f
commit 492ade276b
10 changed files with 64 additions and 23 deletions
Show Stats 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.