diff options
| -rw-r--r-- | Help/command/FIND_XXX.txt | 24 | ||||
| -rw-r--r-- | Help/command/find_package.rst | 6 | ||||
| -rw-r--r-- | Help/envvar/PackageName_ROOT.rst | 15 | ||||
| -rw-r--r-- | Help/manual/cmake-env-variables.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 1 | ||||
| -rw-r--r-- | Help/policy/CMP0074.rst | 15 | ||||
| -rw-r--r-- | Help/release/3.12.rst | 5 | ||||
| -rw-r--r-- | Help/variable/PackageName_ROOT.rst | 14 | ||||
| -rw-r--r-- | Source/cmPolicies.h | 4 | ||||
| -rw-r--r-- | Tests/RunCMake/find_package/CMP0074-WARN-stderr.txt | 2 |
10 files changed, 64 insertions, 23 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 48a1a71243..38c231a670 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -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`. diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 53f3819b34..a4416abd39 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -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. diff --git a/Help/envvar/PackageName_ROOT.rst b/Help/envvar/PackageName_ROOT.rst new file mode 100644 index 0000000000..e01009bc75 --- /dev/null +++ b/Help/envvar/PackageName_ROOT.rst @@ -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. diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index 2d17bb5401..42aeabc898 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -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 =================================== diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index edfff6cc0a..f6bf0bd92d 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -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 ================================== diff --git a/Help/policy/CMP0074.rst b/Help/policy/CMP0074.rst index ffac4a7cb6..896936b212 100644 --- a/Help/policy/CMP0074.rst +++ b/Help/policy/CMP0074.rst @@ -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. diff --git a/Help/release/3.12.rst b/Help/release/3.12.rst index f6fdb5aa92..f00be3e79a 100644 --- a/Help/release/3.12.rst +++ b/Help/release/3.12.rst @@ -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`. diff --git a/Help/variable/PackageName_ROOT.rst b/Help/variable/PackageName_ROOT.rst new file mode 100644 index 0000000000..4f6c25b341 --- /dev/null +++ b/Help/variable/PackageName_ROOT.rst @@ -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. diff --git a/Source/cmPolicies.h b/Source/cmPolicies.h index 3fe0c844d1..1ef1813c2b 100644 --- a/Source/cmPolicies.h +++ b/Source/cmPolicies.h @@ -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) diff --git a/Tests/RunCMake/find_package/CMP0074-WARN-stderr.txt b/Tests/RunCMake/find_package/CMP0074-WARN-stderr.txt index 27fbb86363..fc08163cdc 100644 --- a/Tests/RunCMake/find_package/CMP0074-WARN-stderr.txt +++ b/Tests/RunCMake/find_package/CMP0074-WARN-stderr.txt @@ -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. |