Follow-up from "Help: Restructure the find_package() docs"
The following discussion from !6542 (merged) should be addressed:
-
@ferdnyc started a discussion: (+4 comments) Whoops! I was just reading over the new doc (a huge improvement, I feel) and was about to comment on one section — and I see I've just missed the merge.
It was then suggested I open this issue, instead.
The thing I wanted to bring up is that, while I feel the reorganized docs are a big improvement over the previous version, it still seems to me that, by starting off discussing the "Search Modes" (name of the entire first section, now!) they still focus too much on what, for a user just trying to add dependencies to their CMake project, amounts to nuance.
IOW, ending the "Search Modes" section with this feels like burying the lead:
Where possible, user code should generally look for packages using the basic signature, since that allows the package to be found with either mode. Project maintainers wishing to provide a config package should understand the bigger picture, as explained in Full Signature and all subsequent sections on this page.
That note shouldn't come after the discussion of modes, IMHO it should precede that discussion (and basically head users off before they even dive into it, when they may not have to care).
For beginning users or users unfamiliar with CMake, they shouldn't worry about search modes at all when using find_package()
— they should just add find_package(<Name> [<Version>] [REQUIRED] [COMPONENTS ...])
to their CMakeLists.txt
and let CMake deal with discovering the dependency however it's able. Whether the configuration comes from an installed NameConfig.cmake
file, or if it was generated by a FindName.cmake
module, honestly it's all the same to them.
Once users start doing more advanced things with dependencies, or once they start creating their own EXPORTED
configurations for their own projects, then it's time to delve a little more into what's going on behind-the-scenes with find_package()
.