1CMAKE_MESSAGE_CONTEXT 2--------------------- 3 4.. versionadded:: 3.17 5 6When enabled by the :manual:`cmake <cmake(1)>` ``--log-context`` command line 7option or the :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` variable, the 8:command:`message` command converts the ``CMAKE_MESSAGE_CONTEXT`` list into a 9dot-separated string surrounded by square brackets and prepends it to each line 10for messages of log levels ``NOTICE`` and below. 11 12For 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. 15Projects should not assume the message context at the top of the source tree 16is 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 26Example: 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 56Which 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` 65