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.
- Added intro code blocks showing how to use find modules.
- Synced modules documentation.
- Extended few examples to make the intro code blocks fit into the
modules descriptions.
- Synced some RST formatting, variables descriptions and positions.
- Removed few redundant internal comments.
Issue: #26555
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.
Before calling pkg_check_modules, modules must check PKG_CONFIG_FOUND.
When FindPkgConfig.cmake is loaded, pkg_check_modules is always defined
regardless of pkg-config being present. However, the whole module might
be disabled on user request with CMAKE_DISABLE_FIND_PACKAGE_PkgConfig.
This must not break Find modules which just look for a hint or similar.
