Help/command/message.rst

   1 message
   2 -------
   3
   4 Log a message.
   5
   6 Synopsis
   7 ^^^^^^^^
   8
   9 .. parsed-literal::
  10
  11   `General messages`_
  12     message([<mode>] "message text" ...)
  13
  14   `Reporting checks`_
  15     message(<checkState> "message text" ...)
  16
  17
  18 General messages
  19 ^^^^^^^^^^^^^^^^
  20
  21 .. code-block:: cmake
  22
  23   message([<mode>] "message text" ...)
  24
  25 Record the specified message text in the log.  If more than one message
  26 string is given, they are concatenated into a single message with no
  27 separator between the strings.
  28
  29 The optional ``<mode>`` keyword determines the type of message, which
  30 influences the way the message is handled:
  31
  32 ``FATAL_ERROR``
  33   CMake Error, stop processing and generation.
  34
  35   The :manual:`cmake(1)` executable will return a non-zero
  36   :ref:`exit code <CMake Exit Code>`.
  37
  38 ``SEND_ERROR``
  39   CMake Error, continue processing, but skip generation.
  40
  41 ``WARNING``
  42   CMake Warning, continue processing.
  43
  44 ``AUTHOR_WARNING``
  45   CMake Warning (dev), continue processing.
  46
  47 ``DEPRECATION``
  48   CMake Deprecation Error or Warning if variable
  49   :variable:`CMAKE_ERROR_DEPRECATED` or :variable:`CMAKE_WARN_DEPRECATED`
  50   is enabled, respectively, else no message.
  51
  52 (none) or ``NOTICE``
  53   Important message printed to stderr to attract user's attention.
  54
  55 ``STATUS``
  56   The main interesting messages that project users might be interested in.
  57   Ideally these should be concise, no more than a single line, but still
  58   informative.
  59
  60 ``VERBOSE``
  61   Detailed informational messages intended for project users.  These messages
  62   should provide additional details that won't be of interest in most cases,
  63   but which may be useful to those building the project when they want deeper
  64   insight into what's happening.
  65
  66 ``DEBUG``
  67   Detailed informational messages intended for developers working on the
  68   project itself as opposed to users who just want to build it.  These messages
  69   will not typically be of interest to other users building the project and
  70   will often be closely related to internal implementation details.
  71
  72 ``TRACE``
  73   Fine-grained messages with very low-level implementation details.  Messages
  74   using this log level would normally only be temporary and would expect to be
  75   removed before releasing the project, packaging up the files, etc.
  76
  77 .. versionadded:: 3.15
  78   Added the ``NOTICE``, ``VERBOSE``, ``DEBUG``, and ``TRACE`` levels.
  79
  80 The CMake command-line tool displays ``STATUS`` to ``TRACE`` messages on stdout
  81 with the message preceded by two hyphens and a space.  All other message types
  82 are sent to stderr and are not prefixed with hyphens.  The
  83 :manual:`CMake GUI <cmake-gui(1)>` displays all messages in its log area.
  84 The :manual:`curses interface <ccmake(1)>` shows ``STATUS`` to ``TRACE``
  85 messages one at a time on a status line and other messages in an
  86 interactive pop-up box.  The ``--log-level`` command-line option to each of
  87 these tools can be used to control which messages will be shown.
  88
  89 .. versionadded:: 3.17
  90   To make a log level persist between CMake runs, the
  91   :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable can be set instead.
  92   Note that the command line option takes precedence over the cache variable.
  93
  94 .. versionadded:: 3.16
  95   Messages of log levels ``NOTICE`` and below will have each line preceded
  96   by the content of the :variable:`CMAKE_MESSAGE_INDENT` variable (converted to
  97   a single string by concatenating its list items).  For ``STATUS`` to ``TRACE``
  98   messages, this indenting content will be inserted after the hyphens.
  99
 100 .. versionadded:: 3.17
 101   Messages of log levels ``NOTICE`` and below can also have each line preceded
 102   with context of the form ``[some.context.example]``.  The content between the
 103   square brackets is obtained by converting the :variable:`CMAKE_MESSAGE_CONTEXT`
 104   list variable to a dot-separated string.  The message context will always
 105   appear before any indenting content but after any automatically added leading
 106   hyphens. By default, message context is not shown, it has to be explicitly
 107   enabled by giving the :manual:`cmake <cmake(1)>` ``--log-context``
 108   command-line option or by setting the :variable:`CMAKE_MESSAGE_CONTEXT_SHOW`
 109   variable to true.  See the :variable:`CMAKE_MESSAGE_CONTEXT` documentation for
 110   usage examples.
 111
 112 CMake Warning and Error message text displays using a simple markup
 113 language.  Non-indented text is formatted in line-wrapped paragraphs
 114 delimited by newlines.  Indented text is considered pre-formatted.
 115
 116
 117 Reporting checks
 118 ^^^^^^^^^^^^^^^^
 119
 120 .. versionadded:: 3.17
 121
 122 A common pattern in CMake output is a message indicating the start of some
 123 sort of check, followed by another message reporting the result of that check.
 124 For example:
 125
 126 .. code-block:: cmake
 127
 128   message(STATUS "Looking for someheader.h")
 129   #... do the checks, set checkSuccess with the result
 130   if(checkSuccess)
 131     message(STATUS "Looking for someheader.h - found")
 132   else()
 133     message(STATUS "Looking for someheader.h - not found")
 134   endif()
 135
 136 This can be more robustly and conveniently expressed using the ``CHECK_...``
 137 keyword form of the ``message()`` command:
 138
 139 .. code-block:: cmake
 140
 141   message(<checkState> "message" ...)
 142
 143 where ``<checkState>`` must be one of the following:
 144
 145   ``CHECK_START``
 146     Record a concise message about the check about to be performed.
 147
 148   ``CHECK_PASS``
 149     Record a successful result for a check.
 150
 151   ``CHECK_FAIL``
 152     Record an unsuccessful result for a check.
 153
 154 When recording a check result, the command repeats the message from the most
 155 recently started check for which no result has yet been reported, then some
 156 separator characters and then the message text provided after the
 157 ``CHECK_PASS`` or ``CHECK_FAIL`` keyword.  Check messages are always reported
 158 at ``STATUS`` log level.
 159
 160 Checks may be nested and every ``CHECK_START`` should have exactly one
 161 matching ``CHECK_PASS`` or ``CHECK_FAIL``.
 162 The :variable:`CMAKE_MESSAGE_INDENT` variable can also be used to add
 163 indenting to nested checks if desired.  For example:
 164
 165 .. code-block:: cmake
 166
 167   message(CHECK_START "Finding my things")
 168   list(APPEND CMAKE_MESSAGE_INDENT "  ")
 169   unset(missingComponents)
 170
 171   message(CHECK_START "Finding partA")
 172   # ... do check, assume we find A
 173   message(CHECK_PASS "found")
 174
 175   message(CHECK_START "Finding partB")
 176   # ... do check, assume we don't find B
 177   list(APPEND missingComponents B)
 178   message(CHECK_FAIL "not found")
 179
 180   list(POP_BACK CMAKE_MESSAGE_INDENT)
 181   if(missingComponents)
 182     message(CHECK_FAIL "missing components: ${missingComponents}")
 183   else()
 184     message(CHECK_PASS "all components found")
 185   endif()
 186
 187 Output from the above would appear something like the following::
 188
 189   -- Finding my things
 190   --   Finding partA
 191   --   Finding partA - found
 192   --   Finding partB
 193   --   Finding partB - not found
 194   -- Finding my things - missing components: B