5 files changed, 104 insertions, 2 deletions
diff --git a/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst
index 8776279..4548abc 100644
--- a/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst
+++ b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst
@@ -28,3 +28,7 @@ form.  The format of the JSON file looks like:
 .. note::
   This option is implemented only by :ref:`Makefile Generators`
   and the :generator:`Ninja`.  It is ignored on other generators.
+
+  This option currently does not work well in combination with
+  the :prop_tgt:`UNITY_BUILD` target property or the
+  :variable:`CMAKE_UNITY_BUILD` variable.
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.
diff --git a/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst b/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst
new file mode 100644
index 0000000..1d4cfe6
--- /dev/null
+++ b/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst
@@ -0,0 +1,15 @@
+CMAKE_MESSAGE_LOG_LEVEL
+-----------------------
+
+When set, this variable specifies the logging level used by the
+:command:`message` command.  Valid values are the same as those for the
+``--log-level`` command line option of the :manual:`cmake(1)` program.
+If this variable is set and the ``--log-level`` command line option is
+given, the command line option takes precedence.
+
+The main advantage to using this variable is to make a log level persist
+between CMake runs.  Setting it as a cache variable will ensure that
+subsequent CMake runs will continue to use the chosen log level.
+
+Projects should not set this variable, it is intended for users so that
+they may control the log level according to their own needs.
diff --git a/Help/variable/CMAKE_UNITY_BUILD.rst b/Help/variable/CMAKE_UNITY_BUILD.rst
index 3096954..bbcfd68 100644
--- a/Help/variable/CMAKE_UNITY_BUILD.rst
+++ b/Help/variable/CMAKE_UNITY_BUILD.rst
@@ -1,6 +1,12 @@
 CMAKE_UNITY_BUILD
 -----------------
 
-Default value for :prop_tgt:`UNITY_BUILD` of targets.
+Initializes the :prop_tgt:`UNITY_BUILD` target property on targets
+as they are created.  Set to ``ON`` to batch compilation of multiple
+sources within each target.  This feature is known as "Unity build",
+or "Jumbo build".  By default this variable is not set and so does
+not enable unity builds on targets.
 
-By default ``CMAKE_UNITY_BUILD`` is ``OFF``.
+.. note::
+  This option currently does not work well in combination with
+  the :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable.