The `find_package_handle_standard_args(FOUND_VAR)` is deprecated as of
CMake 3.3 and both the `<PackageName>_FOUND` and the upper-cased
`<PACKAGE_NAME>_FOUND` are set with or without using this option.
Additionally, find modules and docs are also synced with this to make it
clearer.
The Xxx_ROOT_DIR is optional result variable set by find module when
package is found. It is the base directory of the Xxx installation. The
`Xxx_ROOT` is a hint variable set by the user where to look for the
`Xxx` package.
When pkg-config is available and package is found with it, HINTS are a
better place where to hint the PC_Foo_* variables than PATHS. HINTS are
looked before the system default paths and those listed in PATHS.
Re-organize the section to explicitly describe target-specific
commands, build properties, and usage requirement properties.
Add builtin transitive properties that have been created since
the document was first written.
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.
Remove this content from the `cmake-developer(7)` manual because it
is relevant only to developers working on CMake itself. Move it to
a guide in the developer documentation.
We no longer add granular compile features. Only language standard
meta features like `cxx_std_##`` need to be added, and these can
be done by following existing patterns.
Some of our "cmake" code blocks do not use fully valid CMake syntax
because they have placeholders for human reference. Sphinx has
never been able to properly lex and highlight these, but now warns.
Fix each block's syntax or change to a non-cmake block as appropriate.
Replace use of cmsys::auto_ptr with a CM_AUTO_PTR macro that maps to
our own implementation adopted from the KWSys auto_ptr implementation.
Later we may be able to map CM_AUTO_PTR to std::auto_ptr on compilers
that do not warn about it.
Automate the client site conversions:
git grep -l auto_ptr -- Source/ | grep -v Source/kwsys/ | xargs sed -i \
's|cmsys::auto_ptr|CM_AUTO_PTR|;s|cmsys/auto_ptr.hxx|cm_auto_ptr.hxx|'
Pre-C++98 compilers required that the template argument be
used in the function parameters. Those compilers are no longer
supported as hosts, so drop the workaround.
Define an empty string in CMAKE_<LANG>_STANDARD_DEFAULT to mean that
the toolchain has no notion of lanuage standard levels. In this case
the <LANG>_STANDARD[_REQUIRED] properties will have no effect.
Update the RunCMake.CompileFeatures test to exclude the
LinkImplementationFeatureCycle test when there is no standard default.
It can never fail because no use of specific features will adjust the
CXX_STANDARD level required for any target since the standard levels
have no meaning in this case.
The use of FeatureSummary inside a find module is not a convention
yet used by upstream CMake modules. Drop the example from the
documentation about how to write find modules. If in the future
we add use of FeatureSummary to many of the upstream find modules
then this example can be restored as part of establishing the
convention.
An IMPORTED target in either type of package can equally depend on
an IMPORTED target in a Find module, which must be found as a
dependency, which is presumably the problem being implied. This is
not a distinction of creating an IMPORTED target in a Find module.
Update the wording of some examples to avoid long lines in code blocks.
Otherwise the formatted documentation can exceed certain column width
limitations.
Explicitly specify the sequence of underline characters we use in the
CMake documentation. It is the same sequence as that suggested in the
Sphinx documentation, but we have our own descriptions.
This is the convention suggested in the Sphinx documentation and is
already used in several other places in the CMake documentation.
Update a few places where we were using other characters.
