This is a full re-write of the CMake Tutorial for CMake 3.23, both
the functionality it provides, as well as the modern workflows that
developers use when interfacing with CMake.
Issue: #22663, #23086, #23799, #26053, #26105, #26153, #26914
Changes:
- Added intro code blocks showing how to include these modules.
- Added examples sections.
- Used "command" instead of "macro".
- Commands sections added to have a clearer overview of the modules at
first encounter.
- Reworded commands arguments a bit.
- Added a rubric title for variables that affect the checks.
- CheckFortranSourceCompiles: Added CMake version when SRC_EXT option
was introduced.
- Listed CMAKE_TRY_COMPILE_TARGET_TYPE variable in the rubric together
with CMAKE_REQUIRED_* variables and added an include RST file for it.
- Used lowercase style for check_fortran_source_compiles().
Propagate the refactor in Step 10 MathFunctions through all of the
steps. Use MathFunctions/MathFunctions.cxx instead of Tutorial.cxx
to determine which sqrt library is called. Adds .h files which
correspond to their .cxx files by name.
Since commit 07223c5c27 (Tutorial: Update Step 5 to work on Windows,
2020-02-18, v3.18.0-rc1~655^2) the logic does not work on non-Windows
platforms when cmake is re-run on an existing build tree. It is also
more complicated than we'd like for a tutorial example. Avoid the need
to consider the `m` library case by performing the check as C++.
Since `check_cxx_symbol_exists` cannot handle overloaded functions
like `exp` and `log`, check with `check_cxx_source_compiles` instead.
This also presents a more general-purpose example in the tutorial.
Fixes: #23524
Extend the change from commit 9e5bbb69ea (Tutorial: Add captions for
code blocks, 2021-06-11) to also add a Sphinx named target to code
blocks. Name each target after the change the code block makes.
