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