The explanation of the basic and full signatures was interwoven tightly
with that of the Module and Config search modes. Config mode is
supported by both signatures, which made the structure of the
command documentation a bit confusing.
Add a section at the start which unambiguously describes the two
modes, including the fallback functionality between them. Move the
text about this out of the basic signature section, leaving just a
description of the basic syntax with a note that it is supported by both
search modes. This makes the basic signature section more focused.
Drop the Module and Config mode parts of the titles for the basic and
full signature sections. Those are now more precisely covered by the
new opening section, so the Basic Signature and Full Signature sections
are now clearer in what they cover.
Swap the order of the Search Procedure and Version Selection sections
to improve the logical flow. Also add "Config Mode" to their titles to
make it clearer what they apply to. Add a note at the start of both
sections to highlight their relationship to the basic and full signatures.
Add a `CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable is complement
to `CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` with just the opposite
behaviour: it turns non-required find_package call into the required one.
While optional package dependencies usually result in simple and clean
build logic, sometimes people want to be sure those optional
dependencies will be found and used. Examples are reproducible builds
and build instructions for 3rd parties. People choose to make
find_package calls REQUIRED and put them behind an option(). Such
workarounds blend build logic with build environment management and do
not look elegant.
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
Extend the change from commit 1d00ba9ccf (Find: find_package prefers
variable CMAKE_FIND_USE_REGISTRY, 2018-11-13, v3.16.0-rc1~461^2~1)
to cover the system package registry too.
Fixes: #19890
CMake's find control flags should all have a consistent name.
To make this happen we are introducing `CMAKE_FIND_USE_REGISTRY`
and deprecating `CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY`.
Add a `CMAKE_FIND_PACKAGE_PREFER_CONFIG` variable to tell
`find_package` calls to look for a package configuration file
first even if a find module is available.
Fixes: #16805, #19236
Teach find_package() to resolve symlinks when constructing
relocatable prefix paths from discovered cmake config files.
The `CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS` variable enables
this behavior when set to `TRUE`.
Fixes: #18704
Revise docs for all "Scripting Commands", except four find_XXX
that use a macro suite of their own.
* Take full advantage of the improved syntax highlighting.
* Make consequential use of <..> placeholders.
* Clarify things here and there in the text.
Specific improvements to some command docs:
* "math": Correct description of novel hexadecimal capability.
* "if", "foreach", "while": Provide link to "endif" etc
* "foreach", "while": Mention "break" and "continue".
* "foreach": Simplify explanation of ``RANGE`` and ``IN`` signatures;
advise against negative arguments or reverse ranges (compare issue #18461)
* "endif", "endfunction" etc: Explain that the argument is optional and
maintained for compatibility only
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
Add `CMAKE_FIND_PACKAGE_SORT_{ORDER,DIRECTION}` variables to specify
sort order and direction.
When multiple package with the same name have been found in the same
location sorting option can be used to force a specific version to be
loaded (e.g. libA_1.12.0 instead of libA_1.1.0). Currently sorting by
NAME and by NATURAL order have been implemented.
Natural ordering makes use of the `strverscmp(3)` ordering.
Find packages that install their cmake package configuration files in
`lib/cmake/<name>` when they are installed in the default Windows
CMAKE_INSTALL_PREFIX, `C:/Program Files/<name>`.
Closes: #16212
The find_package command, on Windows, has always searched build trees
recently visited by cmake-gui (or CMakeSetup at one time). This was
done when the command was created with the intention of simplifying
workflows involving building multiple dependent projects. However,
this behavior depends on recent developer interaction and therefore
can create different find results based on transient system states.
It can lead to surprising results and user confusion.
Since this behavior was first added CMake has gained many more search
options, better error messages when a package is not found, and a
package registry. The latter in particular allows projects to make
their build trees available for dependent projects to find without
user intervention. Therefore the originally intended workflow can
be achieved in other, more stable ways.
After the above evoluion of find_package we have now decided that
the magic search-where-cmake-gui-was behavior does more harm than
good. Drop it. We do not need a policy for this behavior change
because it only affects interactive use.
When a project is packaged for redistribution the local package
registries should not be updated or consulted. They are for developers.
Add variables to disable use of package registries globally:
* CMAKE_EXPORT_NO_PACKAGE_REGISTRY that disables the export(PACKAGE)
command
* CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY that disables the User Package
Registry in all the find_package calls.
* CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY that disables the
System Package Registry in all the find_package calls.
Update documentation and unit tests.
Recently used cmake-gui locations are searched only on Windows because
the Windows registry is used to record the values. This behavior is
historical and may be removed by a policy in the future so rather than
implementing it on other platforms simply document the current behavior.
