Since commit ffc06c1239 (Teach find_(library|file|path) to get prefixes
from PATH, 2015-02-18, v3.3.0-rc1~430^2) we search in `<prefix>/include`
and `<prefix>/lib` directories for prefixes with `bin` directories in
the `PATH` environment variable. The motivation was to search the
installation prefixes of MSYS and MinGW development environments
automatically.
This behavior can search undesired prefixes that happen to be in the
`PATH` for unrelated reasons. It was reverted for non-Windows hosts
within a year by commit b30b32a493 (Drop find_(library|file|path)
prefixes from PATH on non-Windows, 2016-05-09, v3.6.0-rc1~82^2) but was
kept on Windows hosts to support its motivating use case. However,
similar problems have since been observed on Windows. For example,
commit 955d6245c1 (MSVC: Revert "Teach find_library to consider the
'libfoo.a' naming convention", 2022-11-28, v3.25.1~6^2) was primarily
due to undesired discovery of libraries in `PATH`-derived prefixes.
Since commit 5e5132e1b1 (MinGW: Search for packages in standard MSYSTEM
environment prefixes, 2023-09-11) we search MSYS and MinGW environments'
prefixes explicitly, so `PATH`-derived prefixes are no longer needed for
the original motivating use case.
Fixes: #24216
The documentation of the find-commands was pointing to the
cmake variables CMAKE_PREFIX_PATH, CMAKE_INCLUDE_PATH etc.
also in the section for environment variables. Now they point
to the documentation for the respective environment variables.
Extend commit eb35d8884b (find_package: Use PackageName_ROOT variables
as search prefixes, 2018-03-15, v3.12.0-rc1~349^2) to also check
upper-case `<PACKAGENAME>_ROOT` variables. Add policy `CMP0144` to
enable the behavior in a compatible way.
Fixes: #24403
In commit 8d7e80cf3d (find_* commands: add control over Windows registry
views, 2022-04-16) we added documentation that is repeated by multiple
find commands. Move it to a dedicated manual section to avoid duplication.
Not all the behaviors of CMake variables for ignoring search
locations by find_...() commands were fully documented.
Add the missing effects, clarify the wording and restructure the
way the details are assembled to reduce duplication.
Also improve the cross-referencing to ensure all the related
variables are more discoverable.
Issue: #20878
This change ony concerns directives that appear in the document body.
The guidelines for inserting version directives:
* Baseline version is CMake 3.0, i.e. directives start at 3.1.
* Always use `.. versionadded::` directive, avoid ad-hoc version
references. Exception: policy pages.
* For new command signatures, put `versionadded` on a separate line
after the signature.
* For a group of new signatures in a new document section,
a single version note at the beginning of the section is sufficient.
* For new options, put `versionadded` on a separate line before
option description.
* If all the option descriptions in the list are short one-liners,
it's fine to put `versionadded` on the same line as the description.
* If multiple option descriptions in close proximity would have
the same ..versionadded directive, consider adding a single
directive after the list, mentioning all added options.
* For compact value lists and sub-option lists, put a single
`versionadded` directive after the list mentioning all additions.
* When a change is described in a single paragraph, put
`versionadded` into that paragraph.
* When only part of the paragraph has changed, separate the changed
part if it doesn't break the flow. Otherwise, write a follow-up
clarification paragraph and apply version directive to that.
* When multiple version directives are close by, order earlier
additions before later additions.
* Indent related lists and code blocks to include them in the scope
of `versionadded` directive.
Issue: #19715
In the same spirit as the REQUIRED keyword on find_package, this will
stop cmake execution with an error on a failed find_program, find_file,
find_path or find_library.
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.
