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
- 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
Since commit d74210a8bd (CMP0017: Remove support for OLD behavior,
2024-11-17) we can rely on CMP0017's NEW behavior unconditionally.
Calling `include(FindPackageHandleStandardArgs)` in a builtin module
will always get the builtin `FindPackageHandleStandardArgs`.
If `OpenACC_C_FLAGS` contains `-h acc`, the flag pair needs to
be preserved as a shell command fragment, and must not be split by
de-duplication with other `target_compile_options`.
Fixes: #24963
Modify some additional modules that ship with CMake to use the new
SOURCES_FROM_* arguments to try_compile / try_run as added by commits
cb14ae2b87 (try_compile: Add SOURCE_FROM_{ARG,VAR}, 2022-09-21) and
611d801790 (try_compile: Add SOURCE_FROM_FILE, 2022-09-22). This covers
modules that need to read and alter a template source file, which were
not addressed in the previous commit.
Note that FindOpenACC.cmake does not actually need configure_file
functionality; it appears to have inherited the (gratuitous) use thereof
from FindOpenMP.cmake, with which its code bears significant similarity.
Modify most of the modules that ship with CMake to use the new
try_compile / try_run signatures added by commit aa9220d3a0
(try_compile: Add keyword-dispatched signature, 2022-09-02). This
improves debugging by each invocation using its own directory so that
the results of multiple invocations can be retained.
This does not cover any invocations which provide an entire project, as
that flavor of try_compile has not yet been updated.
Previously the FindOpenACC module had issues where the contents of
OpenACC_<lang>_FLAGS could not be used with target_compile_options
when it contained multiple compiler flags.
The original Fortran snippet would fail to compile with the error
message of:
```
return 0;
1
Error: Alternate RETURN statement at (1) is only allowed within a SUBROUTINE
```
We solve this by removing the early termination logic.
