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