message: Support logging a context with each message

2 files changed, 77 insertions, 0 deletions

diff --git a/Help/variable/CMAKE_MESSAGE_CONTEXT.rst b/Help/variable/CMAKE_MESSAGE_CONTEXT.rst
new file mode 100644
index 0000000..6b4ca40
--- /dev/null
+++ b/Help/variable/CMAKE_MESSAGE_CONTEXT.rst
@@ -0,0 +1,62 @@
+CMAKE_MESSAGE_CONTEXT
+---------------------
+
+When enabled by the :manual:`cmake <cmake(1)>` ``--log-context`` command line
+option or the :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` variable, the
+:command:`message` command converts the ``CMAKE_MESSAGE_CONTEXT`` list into a
+dot-separated string surrounded by square brackets and prepends it to each line
+for messages of log levels ``NOTICE`` and below.
+
+For logging contexts to work effectively, projects should generally
+``APPEND`` and ``POP_BACK`` an item to the current value of
+``CMAKE_MESSAGE_CONTEXT`` rather than replace it.
+Projects should not assume the message context at the top of the source tree
+is empty, as there are scenarios where the context might have already been set
+(e.g. hierarchical projects).
+
+.. warning::
+
+  Valid context names are restricted to anything that could be used
+  as a CMake variable name.  All names that begin with an underscore
+  or the string ``cmake_`` are also reserved for use by CMake and
+  should not be used by projects.
+
+Example:
+
+.. code-block:: cmake
+
+  function(bar)
+    list(APPEND CMAKE_MESSAGE_CONTEXT "bar")
+    message(VERBOSE "bar VERBOSE message")
+  endfunction()
+
+  function(baz)
+    list(APPEND CMAKE_MESSAGE_CONTEXT "baz")
+    message(DEBUG "baz DEBUG message")
+  endfunction()
+
+  function(foo)
+    list(APPEND CMAKE_MESSAGE_CONTEXT "foo")
+    bar()
+    message(TRACE "foo TRACE message")
+    baz()
+  endfunction()
+
+  list(APPEND CMAKE_MESSAGE_CONTEXT "top")
+
+  message(VERBOSE "Before `foo`")
+  foo()
+  message(VERBOSE "After `foo`")
+
+  list(POP_BACK CMAKE_MESSAGE_CONTEXT)
+
+
+Which results in the following output:
+
+.. code-block:: none
+
+  -- [top] Before `foo`
+  -- [top.foo.bar] bar VERBOSE message
+  -- [top.foo] foo TRACE message
+  -- [top.foo.baz] baz DEBUG message
+  -- [top] After `foo`
diff --git a/Help/variable/CMAKE_MESSAGE_CONTEXT_SHOW.rst b/Help/variable/CMAKE_MESSAGE_CONTEXT_SHOW.rst
new file mode 100644
index 0000000..7ec218e
--- /dev/null
+++ b/Help/variable/CMAKE_MESSAGE_CONTEXT_SHOW.rst
@@ -0,0 +1,15 @@
+CMAKE_MESSAGE_CONTEXT_SHOW
+--------------------------
+
+Setting this variable to true enables showing a context with each line
+logged by the :command:`message` command (see :variable:`CMAKE_MESSAGE_CONTEXT`
+for how the context itself is specified).
+
+This variable is an alternative to providing the ``--log-context`` option
+on the :manual:`cmake <cmake(1)>` command line.  Whereas the command line
+option will apply only to that one CMake run, setting
+``CMAKE_MESSAGE_CONTEXT_SHOW`` to true as a cache variable will ensure that
+subsequent CMake runs will continue to show the message context.
+
+Projects should not set ``CMAKE_MESSAGE_CONTEXT_SHOW``.  It is intended for
+users so that they may control whether or not to include context with messages.