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 :option:`--log-level <cmake --log-level>`
  87 command-line option to each of these tools can be used to control which
  88 messages will be shown.
  89
  90 .. versionadded:: 3.17
  91   To make a log level persist between CMake runs, the
  92   :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable can be set instead.
  93   Note that the command line option takes precedence over the cache variable.
  94
  95 .. versionadded:: 3.16
  96   Messages of log levels ``NOTICE`` and below will have each line preceded
  97   by the content of the :variable:`CMAKE_MESSAGE_INDENT` variable (converted to
  98   a single string by concatenating its list items).  For ``STATUS`` to ``TRACE``
  99   messages, this indenting content will be inserted after the hyphens.
 100
 101 .. versionadded:: 3.17
 102   Messages of log levels ``NOTICE`` and below can also have each line preceded
 103   with context of the form ``[some.context.example]``.  The content between the
 104   square brackets is obtained by converting the :variable:`CMAKE_MESSAGE_CONTEXT`
 105   list variable to a dot-separated string.  The message context will always
 106   appear before any indenting content but after any automatically added leading
 107   hyphens. By default, message context is not shown, it has to be explicitly
 108   enabled by giving the :option:`cmake --log-context`
 109   command-line option or by setting the :variable:`CMAKE_MESSAGE_CONTEXT_SHOW`
 110   variable to true.  See the :variable:`CMAKE_MESSAGE_CONTEXT` documentation for
 111   usage examples.
 112
 113 CMake Warning and Error message text displays using a simple markup
 114 language.  Non-indented text is formatted in line-wrapped paragraphs
 115 delimited by newlines.  Indented text is considered pre-formatted.
 116
 117
 118 Reporting checks
 119 ^^^^^^^^^^^^^^^^
 120
 121 .. versionadded:: 3.17
 122
 123 A common pattern in CMake output is a message indicating the start of some
 124 sort of check, followed by another message reporting the result of that check.
 125 For example:
 126
 127 .. code-block:: cmake
 128
 129   message(STATUS "Looking for someheader.h")
 130   #... do the checks, set checkSuccess with the result
 131   if(checkSuccess)
 132     message(STATUS "Looking for someheader.h - found")
 133   else()
 134     message(STATUS "Looking for someheader.h - not found")
 135   endif()
 136
 137 This can be more robustly and conveniently expressed using the ``CHECK_...``
 138 keyword form of the ``message()`` command:
 139
 140 .. code-block:: cmake
 141
 142   message(<checkState> "message" ...)
 143
 144 where ``<checkState>`` must be one of the following:
 145
 146   ``CHECK_START``
 147     Record a concise message about the check about to be performed.
 148
 149   ``CHECK_PASS``
 150     Record a successful result for a check.
 151
 152   ``CHECK_FAIL``
 153     Record an unsuccessful result for a check.
 154
 155 When recording a check result, the command repeats the message from the most
 156 recently started check for which no result has yet been reported, then some
 157 separator characters and then the message text provided after the
 158 ``CHECK_PASS`` or ``CHECK_FAIL`` keyword.  Check messages are always reported
 159 at ``STATUS`` log level.
 160
 161 Checks may be nested and every ``CHECK_START`` should have exactly one
 162 matching ``CHECK_PASS`` or ``CHECK_FAIL``.
 163 The :variable:`CMAKE_MESSAGE_INDENT` variable can also be used to add
 164 indenting to nested checks if desired.  For example:
 165
 166 .. code-block:: cmake
 167
 168   message(CHECK_START "Finding my things")
 169   list(APPEND CMAKE_MESSAGE_INDENT "  ")
 170   unset(missingComponents)
 171
 172   message(CHECK_START "Finding partA")
 173   # ... do check, assume we find A
 174   message(CHECK_PASS "found")
 175
 176   message(CHECK_START "Finding partB")
 177   # ... do check, assume we don't find B
 178   list(APPEND missingComponents B)
 179   message(CHECK_FAIL "not found")
 180
 181   list(POP_BACK CMAKE_MESSAGE_INDENT)
 182   if(missingComponents)
 183     message(CHECK_FAIL "missing components: ${missingComponents}")
 184   else()
 185     message(CHECK_PASS "all components found")
 186   endif()
 187
 188 Output from the above would appear something like the following::
 189
 190   -- Finding my things
 191   --   Finding partA
 192   --   Finding partA - found
 193   --   Finding partB
 194   --   Finding partB - not found
 195   -- Finding my things - missing components: B