message: New message types to mark checks performed by CMake

Closes #19638.

Co-Authored-By: Craig Scott <craig.scott@crascit.com>

1 files changed, 101 insertions, 3 deletions

diff --git a/Help/command/message.rst b/Help/command/message.rst
index beb820a..6bc0e4c 100644
--- a/Help/command/message.rst
+++ b/Help/command/message.rst
@@ -1,13 +1,33 @@
 message
 -------
 
-Display a message to the user.
+Log a message.
+
+Synopsis
+^^^^^^^^
+
+.. parsed-literal::
+
+  `General messages`_
+    message([<mode>] "message text" ...)
+
+  `Reporting checks`_
+    message(<checkState> "message text" ...)
+
+
+General messages
+^^^^^^^^^^^^^^^^
 
 .. code-block:: cmake
 
-  message([<mode>] "message to display" ...)
+  message([<mode>] "message text" ...)
+
+Record the specified message text in the log.  If more than one message
+string is given, they are concatenated into a single message with no
+separator between the strings.
 
-The optional ``<mode>`` keyword determines the type of message:
+The optional ``<mode>`` keyword determines the type of message, which
+influences the way the message is handled:
 
 ``FATAL_ERROR``
   CMake Error, stop processing and generation.
@@ -82,3 +102,81 @@ usage examples.
 CMake Warning and Error message text displays using a simple markup
 language.  Non-indented text is formatted in line-wrapped paragraphs
 delimited by newlines.  Indented text is considered pre-formatted.
+
+
+Reporting checks
+^^^^^^^^^^^^^^^^
+
+A common pattern in CMake output is a message indicating the start of some
+sort of check, followed by another message reporting the result of that check.
+For example:
+
+.. code-block:: cmake
+
+  message(STATUS "Looking for someheader.h")
+  #... do the checks, set checkSuccess with the result
+  if(checkSuccess)
+    message(STATUS "Looking for someheader.h - found")
+  else()
+    message(STATUS "Looking for someheader.h - not found")
+  endif()
+
+This can be more robustly and conveniently expressed using the ``CHECK_...``
+keyword form of the ``message()`` command:
+
+.. code-block:: cmake
+
+  message(<checkState> "message" ...)
+
+where ``<checkState>`` must be one of the following:
+
+  ``CHECK_START``
+    Record a concise message about the check about to be performed.
+
+  ``CHECK_PASS``
+    Record a successful result for a check.
+
+  ``CHECK_FAIL``
+    Record an unsuccessful result for a check.
+
+When recording a check result, the command repeats the message from the most
+recently started check for which no result has yet been reported, then some
+separator characters and then the message text provided after the
+``CHECK_PASS`` or ``CHECK_FAIL`` keyword.  Check messages are always reported
+at ``STATUS`` log level.
+
+Checks may be nested and every ``CHECK_START`` should have exactly one
+matching ``CHECK_PASS`` or ``CHECK_FAIL``.
+The :variable:`CMAKE_MESSAGE_INDENT` variable can also be used to add
+indenting to nested checks if desired.  For example:
+
+.. code-block:: cmake
+
+  message(CHECK_START "Finding my things")
+  list(APPEND CMAKE_MESSAGE_INDENT "  ")
+  unset(missingComponents)
+
+  message(CHECK_START "Finding partA")
+  # ... do check, assume we find A
+  message(CHECK_PASS "found")
+
+  message(CHECK_START "Finding partB")
+  # ... do check, assume we don't find B
+  list(APPEND missingComponents B)
+  message(CHECK_FAIL "not found")
+
+  list(POP_BACK CMAKE_MESSAGE_INDENT)
+  if(missingComponents)
+    message(CHECK_FAIL "missing components: ${missingComponents}")
+  else()
+    message(CHECK_PASS "all components found")
+  endif()
+
+Output from the above would appear something like the following::
+
+  -- Finding my things
+  --   Finding partA
+  --   Finding partA - found
+  --   Finding partB
+  --   Finding partB - not found
+  -- Finding my things - missing components: B