1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
|
message
-------
Log a message.
Synopsis
^^^^^^^^
.. parsed-literal::
`General messages`_
message([<mode>] "message text" ...)
`Reporting checks`_
message(<checkState> "message text" ...)
`Configure Log`_
message(CONFIGURE_LOG <text>...)
General messages
^^^^^^^^^^^^^^^^
.. code-block:: cmake
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, which
influences the way the message is handled:
``FATAL_ERROR``
CMake Error, stop processing and generation.
The :manual:`cmake(1)` executable will return a non-zero
:ref:`exit code <CMake Exit Code>`.
``SEND_ERROR``
CMake Error, continue processing, but skip generation.
``WARNING``
CMake Warning, continue processing.
``AUTHOR_WARNING``
CMake Warning (dev), continue processing.
``DEPRECATION``
CMake Deprecation Error or Warning if variable
:variable:`CMAKE_ERROR_DEPRECATED` or :variable:`CMAKE_WARN_DEPRECATED`
is enabled, respectively, else no message.
(none) or ``NOTICE``
Important message printed to stderr to attract user's attention.
``STATUS``
The main interesting messages that project users might be interested in.
Ideally these should be concise, no more than a single line, but still
informative.
``VERBOSE``
Detailed informational messages intended for project users. These messages
should provide additional details that won't be of interest in most cases,
but which may be useful to those building the project when they want deeper
insight into what's happening.
``DEBUG``
Detailed informational messages intended for developers working on the
project itself as opposed to users who just want to build it. These messages
will not typically be of interest to other users building the project and
will often be closely related to internal implementation details.
``TRACE``
Fine-grained messages with very low-level implementation details. Messages
using this log level would normally only be temporary and would expect to be
removed before releasing the project, packaging up the files, etc.
.. versionadded:: 3.15
Added the ``NOTICE``, ``VERBOSE``, ``DEBUG``, and ``TRACE`` levels.
The CMake command-line tool displays ``STATUS`` to ``TRACE`` messages on stdout
with the message preceded by two hyphens and a space. All other message types
are sent to stderr and are not prefixed with hyphens. The
:manual:`CMake GUI <cmake-gui(1)>` displays all messages in its log area.
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 :option:`--log-level <cmake --log-level>`
command-line option to each of these tools can be used to control which
messages will be shown.
.. versionadded:: 3.17
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.
.. versionadded:: 3.16
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.
.. versionadded:: 3.17
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 :option:`cmake --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
^^^^^^^^^^^^^^^^
.. versionadded:: 3.17
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
Configure Log
^^^^^^^^^^^^^
.. versionadded:: 3.26
.. code-block:: cmake
message(CONFIGURE_LOG <text>...)
Record a :ref:`configure-log message event <message configure-log event>`
with the specified ``<text>``. By convention, if the text contains more
than one line, the first line should be a summary of the event.
This mode is intended to record the details of a system inspection check
or other one-time operation guarded by a cache entry, but that is not
performed using :command:`try_compile` or :command:`try_run`, which
automatically log their details. Projects should avoid calling it every
time CMake runs. For example:
.. code-block:: cmake
if (NOT DEFINED MY_CHECK_RESULT)
# Print check summary in configure output.
message(CHECK_START "My Check")
# ... perform system inspection, e.g., with execute_process ...
# Cache the result so we do not run the check again.
set(MY_CHECK_RESULT "${MY_CHECK_RESULT}" CACHE INTERNAL "My Check")
# Record the check details in the cmake-configure-log.
message(CONFIGURE_LOG
"My Check Result: ${MY_CHECK_RESULT}\n"
"${details}"
)
# Print check result in configure output.
if(MY_CHECK_RESULT)
message(CHECK_PASS "passed")
else()
message(CHECK_FAIL "failed")
endif()
endif()
If no project is currently being configured, such as in
:ref:`cmake -P <Script Processing Mode>` script mode,
this command does nothing.
See Also
^^^^^^^^
* :command:`cmake_language(GET_MESSAGE_LOG_LEVEL)`
|
