The original intent of <PackageName>_ROOT may have been for it
to apply only to Find modules, but the implementation of the
find_package() command treats modules and config packages the
same. Both result in a <PackageName>_ROOT variable being
pushed onto the stack of package roots. A config package can
also call other find_...() commands, the behavior doesn't apply
just to find modules.
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 feature was originally added by commit v3.9.0-rc1~71^2~2 (find_*:
Add a new PackageRoot search path group, 2017-05-03) and documented by
commit v3.9.0-rc1~71^2 (find_*: Add docs for PackageRoot search path
group, 2017-05-03). However, we had to disable the feature and remove
the documentation in commit v3.9.1~2^2 (find_*: Disable the PACKAGE_ROOT
search path group for CMake 3.9, 2017-08-08) due to breaking projects
that used `PackageName_ROOT` variables themselves.
Add policy `CMP0074` to restore the `PackageName_ROOT` variable behavior
in a compatible way. Also revise the stack of root paths to store the
paths themselves rather than the package names. This way the policy can
be considered at the `find_package` call site instead of individual
`find_` calls inside a find module.
Co-Author: Chuck Atkins <chuck.atkins@kitware.com>
Issue: #17144
Disable the feature added by commit v3.9.0-rc1~71^2~2 (find_*: Add a new
PackageRoot search path group, 2017-05-03) and remove documentation
added by commit v3.9.0-rc1~71^2 (find_*: Add docs for PackageRoot search
path group, 2017-05-03). Unfortunately the name `<pkg>_ROOT` may
already be set by projects for their own incompatible purposes. Disable
the behavior change for now to fix the regression for CMake 3.9. We can
restore it later with a policy.
In order to keep the implementation and tests working, add an
undocumented variable we can use in the tests to enable the behavior
before the policy is introduced.
Fixes: #17144
The `find_*` commands read search paths from both CMake variables
and from environment variables. Document how multiple values in
these variables should be separated.
Fixes: #16800
The find_package command already knows how to compute installation
prefixes from PATH. Use the same approach to establish prefixes for
find_library, find_file, and find_path to use to look in directories
like "<prefix>/lib[/<arch>]" and "<prefix>/include" for libraries and
headers. This will reduce the amount of configuration end users need to
do to establish a work environment rooted under a specific prefix.
These documents were represented in the builtin documentation using a
common starting point with placeholders substituted by each command.
Convert them back to this approach using the reStructuredText include
directive and substitutions to avoid duplication.
