The guide previously only focused on the find_package() command,
with a bias towards libraries. FetchContent was not mentioned at all.
Reorganise and update the existing content. Add new sections to cover
providing dependencies with FetchContent and dependency providers.
Improve discoverability of the guide by mentioning it at the beginning
of the find_package(), FetchContent and dependency provider docs.
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.
Allow FetchContent_MakeAvailable() to try a call to
find_package() first, or redirect a find_package() call to
FetchContent_MakeAvailable(). The user can set variables
to control which of these are allowed or tried by default.
Fixes: #21687
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
Allow find package to promote scope of imported targets by specifying
an argument to `find_package` or by specifying a CMake variable.
* Add support for CMAKE_GLOBAL_IMPORT_SCOPE variable
* Add support for GLOBAL argument to find_package
Additionally add testing for above features.
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
