summaryrefslogtreecommitdiffstats
path: root/Help/command/message.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Help/command/message.rst')
-rw-r--r--Help/command/message.rst120
1 files changed, 116 insertions, 4 deletions
diff --git a/Help/command/message.rst b/Help/command/message.rst
index c614286..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.
@@ -59,12 +79,104 @@ The :manual:`curses interface <ccmake(1)>` shows ``STATUS`` to ``TRACE``
messages one at a time on a status line and other messages in an
interactive pop-up box. The ``--log-level`` command-line option to each of
these tools can be used to control which messages will be shown.
+To make a log level persist between CMake runs, the
+:variable:`CMAKE_MESSAGE_LOG_LEVEL` variable can be set instead.
+Note that the command line option takes precedence over the cache variable.
-Messages of log levels ``NOTICE`` and below will also have each line preceded
+Messages of log levels ``NOTICE`` and below will have each line preceded
by the content of the :variable:`CMAKE_MESSAGE_INDENT` variable (converted to
a single string by concatenating its list items). For ``STATUS`` to ``TRACE``
messages, this indenting content will be inserted after the hyphens.
+Messages of log levels ``NOTICE`` and below can also have each line preceded
+with context of the form ``[some.context.example]``. The content between the
+square brackets is obtained by converting the :variable:`CMAKE_MESSAGE_CONTEXT`
+list variable to a dot-separated string. The message context will always
+appear before any indenting content but after any automatically added leading
+hyphens. By default, message context is not shown, it has to be explicitly
+enabled by giving the :manual:`cmake <cmake(1)>` ``--log-context``
+command-line option or by setting the :variable:`CMAKE_MESSAGE_CONTEXT_SHOW`
+variable to true. See the :variable:`CMAKE_MESSAGE_CONTEXT` documentation for
+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