Fixes: #18973

Fixes: #18521

* Replace '::' by '.. code-block:: cmake' wherever it makes sense.
* Convert to definition list where appropriate.
* Prefer '<placeholder>' over 'placeholder'.

Per-source copyright/license notice headers that spell out copyright holder
names and years are hard to maintain and often out-of-date or plain wrong.
Precise contributor information is already maintained automatically by the
version control tool.  Ultimately it is the receiver of a file who is
responsible for determining its licensing status, and per-source notices are
merely a convenience.  Therefore it is simpler and more accurate for
each source to have a generic notice of the license name and references to
more detailed information on copyright holders and full license terms.

Our `Copyright.txt` file now contains a list of Contributors whose names
appeared source-level copyright notices.  It also references version control
history for more precise information.  Therefore we no longer need to spell
out the list of Contributors in each source file notice.

Replace CMake per-source copyright/license notice headers with a short
description of the license and links to `Copyright.txt` and online information
available from "https://cmake.org/licensing".  The online URL also handles
cases of modules being copied out of our source into other projects, so we
can drop our notices about replacing links with full license text.

Run the `Utilities/Scripts/filter-notices.bash` script to perform the majority
of the replacements mechanically.  Manually fix up shebang lines and trailing
newlines in a few files.  Manually update the notices in a few files that the
script does not handle.

Change "succeded" to "succeeded" everywhere.

Otherwise callers may expect to be able to re-use result variables.

Prior to the existence of the if(DEFINED) condition, many of our Check
modules implemented the condition with a hack that takes advantage of
the auto-dereference behavior of the if() command to detect if a
variable is defined.  The hack has the form:

 if("${VAR} MATCHES "^${VAR}$")

where "${VAR}" is a macro argument reference.  However, this does not
work when the variable named in the macro argument contains characters
that have special meaning in regular expressions, such as '+'.  Run the
command

 git grep -E 'if\("\$\{.*\}" MATCHES "\^\$\{.*\}\$"\)' -- Modules/Check*

to identify lines with this problem.  Use if(NOT DEFINED) instead.

Setting this flag can silence messages from the Check*.cmake modules.
This can be used by Find*.cmake modules when they are in silent mode.

Run the convert-help.bash script to convert documentation:

 ./convert-help.bash "/path/to/CMake-build/bin"

Then remove it.

Imported targets are re-exported so that they can be used by the
try_compile generated code with target_link_libraries.

This makes the use of the cmake_expand_imported_targets macro
obsolete. The macro is not able to expand the generator expressions
which may appear in the IMPORTED_LINK_INTERFACE_LIBRARIES content.
Instead it just sees them as 'not a target'.

Ancient versions of CMake required else(), endif(), and similar block
termination commands to have arguments matching the command starting the
block.  This is no longer the preferred style.

Run the following shell code:

for c in else endif endforeach endfunction endmacro endwhile; do
    echo 's/\b'"$c"'\(\s*\)(.\+)/'"$c"'\1()/'
done >convert.sed &&
git ls-files -z -- bootstrap '*.cmake' '*.cmake.in' '*CMakeLists.txt' |
egrep -z -v '^(Utilities/cm|Source/kwsys/)' |
egrep -z -v 'Tests/CMakeTests/While-Endwhile-' |
xargs -0 sed -i -f convert.sed &&
rm convert.sed

Ancient CMake versions required upper-case commands.  Later command
names became case-insensitive.  Now the preferred style is lower-case.

Run the following shell code:

cmake --help-command-list |
grep -v "cmake version" |
while read c; do
    echo 's/\b'"$(echo $c | tr '[:lower:]' '[:upper:]')"'\(\s*\)(/'"$c"'\1(/g'
done >convert.sed &&
git ls-files -z -- bootstrap '*.cmake' '*.cmake.in' '*CMakeLists.txt' |
egrep -z -v '^(Utilities/cm|Source/kwsys/)' |
xargs -0 sed -i -f convert.sed &&
rm convert.sed

Add the function cmake_expand_imported_targets() to expand imported
targets in a list of libraries into their on-disk file names for a
particular configuration.  Adapt the implementation from KDE's
HANDLE_IMPORTED_TARGETS_IN_CMAKE_REQUIRED_LIBRARIES which has been in
use for over 2 years.  Call the function from all the Check*.cmake
macros to handle imported targets named in CMAKE_REQUIRED_LIBRARIES.

Alex

Alex

This adds copyright/license notification blocks CMake's non-find
modules.  Most of the modules had no notices at all.  Some had notices
referring to the BSD license already.  This commit normalizes existing
notices and adds missing notices.

This commit improves formatting and style of the documentation for the
general-purpose compiler check macros:

  CHECK_C_COMPILER_FLAG
  CHECK_C_SOURCE_COMPILES
  CHECK_C_SOURCE_RUNS
  CHECK_CXX_COMPILER_FLAG
  CHECK_CXX_SOURCE_COMPILES
  CHECK_CXX_SOURCE_RUNS

This sytle is more consistent with CMake command documentation.
It also looks nicer in the generated documentation text files.

one, but the first one was the correct one (i.e. the one which mentioned
that CheckC[XX]SourceRuns.cmake also tries to run the executable)

Alex

ENH: use the same CMAKE_SKIP_RPATH setting in CHECK_C/CXX_SOURCE_RUNS as in
the main project. I think it doesn't make sense if a project disables
RPATH, uses CHECK_C_SOURCE_RUNS() to see if something is able to run, and
this succeeds because it has been built with RPATH, but an executable built
within the project won't be able to run since it has been built without
RPATH.

Alex

STYLE: don't use FIND_INCLUDE_FILE() but only FIND_INCLUDE_FILES() in
FindThreads.h

BUG: improve CheckC(XX)SourceRuns.cmake so that it works with cross
compiling, the return value has to go in the cache but shouldn't overwrite
the actual return value, and it should go only in the cache if we have a
result from try_run() otherwise we won't get here again if we have a result
later on

Alex

BUG: the SET( ... CACHE INTERNAL) didn't work as expected, since the
variable is already added to the cache inside cmTryRunCommand.cxx, so the
value used here was ignored. Additionally the INTERNAL made it internal,
which shouldn't be done when cross compiling, since here the user is
required to edit this variable manually e.g. using ccmake.

Alex

ENH: improve TRY_RUN() for crosscompiling: instead of just failing, it now
creates two cache variables, one for the RUN_RESULT, one for the RUN_OUTPUT
(if required), which can be set or preset by the user. It has now also two
new arguments: RUN_OUTPUT_VARIABLE and COMPILE_OUTPUT_VARIABLE (the old
OUTPUT_VARIABLE merges both), so if only COMPILE_OUTPUT_VARIABLE is used the
run time output of the TRY_RUN is unused and the user doesn't have to care
about the output when crosscompiling. This is now used in FindThreads.cmake,
CheckC/CXXSourceRuns.cmake and TestBigEndian.cmake, which used the output
only for the logfile (compile output is still there). Test/TryCompile/ now
also tests the behaviour of OUTPUT_VARIABLE, RUN_OUTPUT_VARIABLE and
COMPILE_OUTPUT_VARIABLE.

Alex

ENH: Made Check* modules more consistent and well documented.  Added CMAKE_REQUIRED_DEFINITIONS option.