From 492ade276b9a54ad61ba5eed4eea77897fdb74c1 Mon Sep 17 00:00:00 2001 From: Brad King Date: Thu, 19 Jul 2018 14:19:42 -0400 Subject: Help: Add explicit _ROOT variable documentation 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. --- Help/command/FIND_XXX.txt | 24 ++++++++++++++-------- Help/command/find_package.rst | 6 ++++-- Help/envvar/PackageName_ROOT.rst | 15 ++++++++++++++ Help/manual/cmake-env-variables.7.rst | 1 + Help/manual/cmake-variables.7.rst | 1 + Help/policy/CMP0074.rst | 15 +++++++------- Help/release/3.12.rst | 5 +++-- Help/variable/PackageName_ROOT.rst | 14 +++++++++++++ Source/cmPolicies.h | 4 ++-- .../RunCMake/find_package/CMP0074-WARN-stderr.txt | 2 +- 10 files changed, 64 insertions(+), 23 deletions(-) create mode 100644 Help/envvar/PackageName_ROOT.rst create mode 100644 Help/variable/PackageName_ROOT.rst diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 48a1a71..38c231a 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 ```` in ``PackageName_ROOT`` if called - from within a find module + |prefix_XXX_SUBDIR| for each ```` in the + :variable:`_ROOT` CMake variable and the + :envvar:`_ROOT` environment variable if + called from within a find module loaded by + :command:`find_package()` .. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace:: |prefix_XXX_SUBDIR| for each ```` 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 ```` 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()`, search prefixes unique to the + current package being found. Specifically look in the + :variable:`_ROOT` CMake variable and the + :envvar:`_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. ``_ROOT``, ``ENV{_ROOT}``, + ``_ROOT``, ``ENV{_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 53f3819..a4416ab 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:`_ROOT` CMake + variable and the :envvar:`_ROOT` environment variable, + where ```` 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 0000000..e01009b --- /dev/null +++ b/Help/envvar/PackageName_ROOT.rst @@ -0,0 +1,15 @@ +_ROOT +------------------ + +Calls to :command:`find_package()` will search in prefixes +specified by the ``_ROOT`` environment variable, where +```` 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:`_ROOT` CMake variable. diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index 2d17bb5..42aeabc 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 edfff6c..f6bf0bd 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 ffac4a7..896936b 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 ``_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()` command now +searches prefixes specified by the :variable:`_ROOT` CMake +variable and the :envvar:`_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. +``_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 ``_ROOT`` +variables. The ``NEW`` behavior for this policy is to use +``_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 f6fdb5a..f00be3e 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:`_ROOT` CMake variable and the + :envvar:`_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 0000000..4f6c25b --- /dev/null +++ b/Help/variable/PackageName_ROOT.rst @@ -0,0 +1,14 @@ +_ROOT +------------------ + +Calls to :command:`find_package()` will search in prefixes +specified by the ``_ROOT`` CMake variable, where +```` 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 ` of multiple prefixes. + +See also the :envvar:`_ROOT` environment variable. diff --git a/Source/cmPolicies.h b/Source/cmPolicies.h index 3fe0c84..1ef1813 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 _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 27fbb86..fc08163 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 :/foo/cmake_root ENV{Foo_ROOT} :/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 _ROOT variables. Run "cmake --help-policy CMP0074" for policy details. Use the cmake_policy command to set the policy and suppress this warning. -- cgit v0.12