message¶
Log a message.
Synopsis¶
General messages message([<mode>] "message text" ...) Reporting checks message(<checkState> "message text" ...)
General messages¶
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.
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
CMAKE_ERROR_DEPRECATED
orCMAKE_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.
New in version 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
CMake GUI
displays all messages in its log area.
The curses interface
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.
New in version 3.17: To make a log level persist between CMake runs, the
CMAKE_MESSAGE_LOG_LEVEL
variable can be set instead.
Note that the command line option takes precedence over the cache variable.
New in version 3.16: Messages of log levels NOTICE
and below will have each line preceded
by the content of the 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.
New in version 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 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 cmake
--log-context
command-line option or by setting the CMAKE_MESSAGE_CONTEXT_SHOW
variable to true. See the 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¶
New in version 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:
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:
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 CMAKE_MESSAGE_INDENT
variable can also be used to add
indenting to nested checks if desired. For example:
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