Help/variable/CMAKE_MESSAGE_CONTEXT.rst

   1 CMAKE_MESSAGE_CONTEXT
   2 ---------------------
   3
   4 .. versionadded:: 3.17
   5
   6 When enabled by the :option:`cmake --log-context` command line
   7 option or the :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` variable, the
   8 :command:`message` command converts the ``CMAKE_MESSAGE_CONTEXT`` list into a
   9 dot-separated string surrounded by square brackets and prepends it to each line
  10 for messages of log levels ``NOTICE`` and below.
  11
  12 For logging contexts to work effectively, projects should generally
  13 ``APPEND`` and ``POP_BACK`` an item to the current value of
  14 ``CMAKE_MESSAGE_CONTEXT`` rather than replace it.
  15 Projects should not assume the message context at the top of the source tree
  16 is empty, as there are scenarios where the context might have already been set
  17 (e.g. hierarchical projects).
  18
  19 .. warning::
  20
  21   Valid context names are restricted to anything that could be used
  22   as a CMake variable name.  All names that begin with an underscore
  23   or the string ``cmake_`` are also reserved for use by CMake and
  24   should not be used by projects.
  25
  26 Example:
  27
  28 .. code-block:: cmake
  29
  30   function(bar)
  31     list(APPEND CMAKE_MESSAGE_CONTEXT "bar")
  32     message(VERBOSE "bar VERBOSE message")
  33   endfunction()
  34
  35   function(baz)
  36     list(APPEND CMAKE_MESSAGE_CONTEXT "baz")
  37     message(DEBUG "baz DEBUG message")
  38   endfunction()
  39
  40   function(foo)
  41     list(APPEND CMAKE_MESSAGE_CONTEXT "foo")
  42     bar()
  43     message(TRACE "foo TRACE message")
  44     baz()
  45   endfunction()
  46
  47   list(APPEND CMAKE_MESSAGE_CONTEXT "top")
  48
  49   message(VERBOSE "Before `foo`")
  50   foo()
  51   message(VERBOSE "After `foo`")
  52
  53   list(POP_BACK CMAKE_MESSAGE_CONTEXT)
  54
  55
  56 Which results in the following output:
  57
  58 .. code-block:: none
  59
  60   -- [top] Before `foo`
  61   -- [top.foo.bar] bar VERBOSE message
  62   -- [top.foo] foo TRACE message
  63   -- [top.foo.baz] baz DEBUG message
  64   -- [top] After `foo`