This marks all `<PACKAGENAME>_FOUND` result variables as deprecated
where possible (for `<PackageName>` find modules) to make it clearer
which variable to use.
In CMake 3.3, the FindPackageHandleStandardArgs module was refactored to
set both `<PackageName>_FOUND` and uppercase `<PACKAGENAME>_FOUND`
result variables to the same values. Before that, the FOUND_VAR argument
could be used to set the result variable.
* FindMatlab: Uppercased MATLAB_FOUND is not mentioned as it was never
documented.
* Documentation for FindPythonInterp and FindPythonLibs modules synced
accordingly to their deprecation (3.12 instead of 4.2).
* OPENGL_FOUND: deprecation version synced with other find modules.
* DevIL_FOUND was introduced in CMake 3.8. The uppercased variant not
mentioned as it was previously never documented.
Fixes: #27242
Since most of the find modules use the `<PackageName>_FOUND` result
variables, this now also syncs it for the FindPkgConfig module. The
`PkgConfig_FOUND` result variable is available since CMake 3.3 and
contains the same value. There is also `PKGCONFIG_FOUND` result variable
automatically set with the same value but for simplicity isn't
documented. The uppercased `<PACKAGENAME>_FOUND` result variables set by
find modules are also considered legacy variables.
- Used "commands" instead of "functions".
- Added separate examples section.
- Moved FOUND_VAR argument to the bottom as it is deprecated.
- Reworded descriptions.
Changes:
- The Foo_VERSION_STRING variable is a legacy variable name and should
be set in find modules only if the existing module is replacing some
of its previous version. Meaning new modules/code shouldn't introduce
such variable from scratch.
- Reworded some sentences to remove "you" making the documentation more
neutral and less direct.
Covers almost all blocks containing actual code, except:
* Parsed-literal blocks can't be highlighted, including many command
summaries and substitution-heavy docs like find_... commands.
This is a Sphinx limitation.
* Code with errors, like CMP0049, DEPLOYMENT_ADDITIONAL_FILES,
DEPLOYMENT_REMOTE_DIRECTORY, @PACKAGE_INIT@ substitution in the
tutorial, bracket arguments/comments in cmake-language.7 and
cmake-developer.7.
* FindQt4 module, which needs reformatting.
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.
Peter Kokot