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
When more than one value is given to the NAMES option this command by
default will consider one name at a time and search every directory for
it. Add a NAMES_PER_DIR option to tell this command to consider one
directory at a time and search for all names in it.
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.
