CMake/Help/command/message.rst

message
-------

Display a message to the user.

.. code-block:: cmake

  message([<mode>] "message to display" ...)

The optional ``<mode>`` keyword determines the type of message:

``FATAL_ERROR``
  CMake Error, stop processing and generation.

``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.

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 ``--log-level`` command-line option to each of
these tools can be used to control which messages will be shown.
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.

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.

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 :manual:`cmake <cmake(1)>` ``--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.