Adds a "Step 0" to the tutorial which discusses minutia about where to
get CMake, how to run it, and most importantly deals at length with
various generator issues which aren't covered elsewhere.
Restore commit 4cb616fed6 (Tutorial: Provide a source archive when
published on cmake.org, 2022-04-27, v3.23.2~22^2). Its effects were
accidentally reverted by commit 9784834b4c (Help: Use `*.rst` extension
for included files, 2025-04-07, v4.1.0-rc1~354^2).
Reported-by: Vito Gamberini <vito.gamberini@kitware.com>
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().
* Remove `CTEST_PROJECT_NAME`, as it is no longer used.
* Set `CTEST_SUBMIT_URL` instead of `CTEST_DROP_*`.
* Remove `CTEST_SUBMIT_URL`, as it is not used.
Run the `clang-format.bash` script to update all our C and C++ code to a
new style defined by `.clang-format`, now with "east const" enforcement.
Use `clang-format` version 18.
* If you reached this commit for a line in `git blame`, re-run the blame
operation starting at the parent of this commit to see older history
for the content.
* See the parent commit for instructions to rebase a change across this
style transition commit.
Issue: #26123
* Fix typo in Step 2
* Fix incorrect code referenced in Step 3, TODO 7. Update comments in
MathFunctions/CMakeLists.txt to unique strings.
* Resolve inconsistencies between steps in MathFunctions/CMakeLists.txt
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 6e58a01f4e (Tutorial: Update step 6 style, 2022-10-06) the
`literalinclude` included an extra comment from step 6 instructions.
Fix the include bounds to remove the extra text.
In commit 80f5d28813 (Tutorial: Update step 2 style, 2022-07-25,
v3.25.0-rc1~226^2) we replaced some uses of `USE_MYMATH` with `MY_MATH`.
Restore the former name for consistency with the rest of the tutorial.
