8 files changed, 99 insertions, 19 deletions
diff --git a/Help/envvar/DESTDIR.rst b/Help/envvar/DESTDIR.rst
index d2144ae..94cae4a 100644
--- a/Help/envvar/DESTDIR.rst
+++ b/Help/envvar/DESTDIR.rst
@@ -5,17 +5,26 @@ DESTDIR
 
 On UNIX one can use the ``DESTDIR`` mechanism in order to relocate the
 whole installation.  ``DESTDIR`` means DESTination DIRectory.  It is
-commonly used by makefile users in order to install software at
-non-default location.  It is usually invoked like this:
+commonly used by packagers to install software in a staging directory.
 
-::
+For example, running
 
- make DESTDIR=/home/john install
+.. code-block:: shell
 
-which will install the concerned software using the installation
-prefix, e.g.  ``/usr/local`` prepended with the ``DESTDIR`` value which
-finally gives ``/home/john/usr/local``.
+  make DESTDIR=/package/stage install
 
-WARNING: ``DESTDIR`` may not be used on Windows because installation
-prefix usually contains a drive letter like in ``C:/Program Files``
-which cannot be prepended with some other prefix.
+will install the software using the installation prefix, e.g. ``/usr/local``,
+prepended with the ``DESTDIR`` value which gives ``/package/stage/usr/local``.
+The packaging tool may then construct the package from the content of the
+``/package/stage`` directory.
+
+See the :variable:`CMAKE_INSTALL_PREFIX` variable to control the
+installation prefix when configuring a build tree.  Or, when using
+the :manual:`cmake(1)` command-line tool's ``--install`` mode,
+one may specify a different prefix using the ``--prefix`` option.
+
+.. note::
+
+  ``DESTDIR`` may not be used on Windows because installation
+  prefix usually contains a drive letter like in ``C:/Program Files``
+  which cannot be prepended with some other prefix.
diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index e8048b3..65f9248 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -404,6 +404,7 @@ Properties on Targets
    /prop_tgt/VS_JUST_MY_CODE_DEBUGGING
    /prop_tgt/VS_KEYWORD
    /prop_tgt/VS_MOBILE_EXTENSIONS_VERSION
+   /prop_tgt/VS_NO_COMPILE_BATCHING
    /prop_tgt/VS_NO_SOLUTION_DEPLOY
    /prop_tgt/VS_PACKAGE_REFERENCES
    /prop_tgt/VS_PLATFORM_TOOLSET
diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index c2b4d68..54eb244 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -298,7 +298,8 @@ Options
          "cmd": "add_executable",
          "args": ["foo", "bar"],
          "time": 1579512535.9687231,
-         "frame": 2
+         "frame": 2,
+         "global_frame": 4
        }
 
      The members are:
@@ -325,7 +326,13 @@ Options
        Timestamp (seconds since epoch) of the function call.
 
      ``frame``
-       Stack frame depth of the function that was called.
+       Stack frame depth of the function that was called, within the
+       context of the  ``CMakeLists.txt`` being processed currently.
+
+     ``global_frame``
+       Stack frame depth of the function that was called, tracked globally
+       across all ``CMakeLists.txt`` files involved in the trace. This field
+       was added in minor version 2 of the ``json-v1`` format.
 
      Additionally, the first JSON document outputted contains the
      ``version`` key for the current major and minor version of the
@@ -337,7 +344,7 @@ Options
        {
          "version": {
            "major": 1,
-           "minor": 1
+           "minor": 2
          }
        }
 
@@ -646,11 +653,17 @@ Available commands are:
     ``true`` if cmake supports server-mode and ``false`` otherwise.
     Always false since CMake 3.20.
 
-``cat <files>...``
+``cat [--] <files>...``
   .. versionadded:: 3.18
 
   Concatenate files and print on the standard output.
 
+  .. versionadded:: 3.24
+    Added support for the double dash argument ``--``. This basic implementation
+    of ``cat`` does not support any options, so using a option starting with
+    ``-`` will result in an error. Use ``--`` to indicate the end of options, in
+    case a file starts with ``-``.
+
 ``chdir <dir> <cmd> [<arg>...]``
   Change the current working directory and run a command.
 
@@ -719,11 +732,16 @@ Available commands are:
 ``echo_append [<string>...]``
   Displays arguments as text but no new line.
 
-``env [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...``
+``env [--unset=NAME ...] [NAME=VALUE ...] [--] <command> [<arg>...]``
   .. versionadded:: 3.1
 
   Run command in a modified environment.
 
+  .. versionadded:: 3.24
+    Added support for the double dash argument ``--``. Use ``--`` to stop
+    interpreting options/environment variables and treat the next argument as
+    the command, even if it start with ``-`` or contains a ``=``.
+
 ``environment``
   Display the current environment variables.
 
@@ -816,16 +834,16 @@ Available commands are:
   Rename a file or directory (on one volume). If file with the ``<newname>`` name
   already exists, then it will be silently replaced.
 
-``rm [-rRf] <file> <dir>...``
+``rm [-rRf] [--] <file|dir>...``
   .. versionadded:: 3.17
 
   Remove the files ``<file>`` or directories ``<dir>``.
-
   Use ``-r`` or ``-R`` to remove directories and their contents recursively.
   If any of the listed files/directories do not exist, the command returns a
   non-zero exit code, but no message is logged. The ``-f`` option changes
   the behavior to return a zero exit code (i.e. success) in such
-  situations instead.
+  situations instead. Use ``--`` to stop interpreting options and treat all
+  remaining arguments as paths, even if they start with ``-``.
 
 ``server``
   Launch :manual:`cmake-server(7)` mode.
diff --git a/Help/prop_tgt/VS_NO_COMPILE_BATCHING.rst b/Help/prop_tgt/VS_NO_COMPILE_BATCHING.rst
new file mode 100644
index 0000000..f8a9fa6
--- /dev/null
+++ b/Help/prop_tgt/VS_NO_COMPILE_BATCHING.rst
@@ -0,0 +1,21 @@
+VS_NO_COMPILE_BATCHING
+----------------------
+
+.. versionadded:: 3.24
+
+Turn off compile batching for the target. Usually MSBuild calls the compiler
+with multiple c/cpp files and compiler starts subprocesses for each file to
+make the build parallel. If you want compiler to be invoked with one file at
+a time set VS_NO_COMPILE_BATCHING to ON. If this flag is set MSBuild will call
+compiler with one c/cpp file at a time. Useful when you want to use tool that
+replaces the compiler, for example some build caching tool.
+
+Example
+^^^^^^^
+
+This shows setting the variable for the target foo.
+
+.. code-block:: cmake
+
+  add_library(foo SHARED foo.cpp)
+  set_property(TARGET foo PROPERTY VS_NO_COMPILE_BATCHING ON)
diff --git a/Help/release/dev/cmcmd-end-of-options-delimiter.rst b/Help/release/dev/cmcmd-end-of-options-delimiter.rst
new file mode 100644
index 0000000..bc9cc21
--- /dev/null
+++ b/Help/release/dev/cmcmd-end-of-options-delimiter.rst
@@ -0,0 +1,7 @@
+cmcmd-end-of-options-delimiter
+------------------------------
+
+* The :manual:`cmake(1)` ``-E`` commands ``cat`` and ``env`` learned to respect
+  a double dash (``--``) argument that acts as a delimiter indicating the end of
+  options. Any following arguments are treated as operands/positional arguments,
+  even if they begin with a dash ``-`` character.
diff --git a/Help/release/dev/trace-global-frame.rst b/Help/release/dev/trace-global-frame.rst
new file mode 100644
index 0000000..fdc4b5c
--- /dev/null
+++ b/Help/release/dev/trace-global-frame.rst
@@ -0,0 +1,8 @@
+trace-global-frame
+------------------
+
+* Add the field ``global_frame`` to the json-v1 trace format. This
+  frame tracks the depth of the call stack globally across all
+  ``CMakeLists.txt`` files involved in the trace, and will let tools
+  reconstruct stack traces that span from the top-level ``CMakeLists.txt``
+  file of the project.
diff --git a/Help/release/dev/vs_buildcache_support.rst b/Help/release/dev/vs_buildcache_support.rst
new file mode 100644
index 0000000..bdda675
--- /dev/null
+++ b/Help/release/dev/vs_buildcache_support.rst
@@ -0,0 +1,6 @@
+vs_buildcache_support
+---------------------
+
+* The :prop_tgt:`VS_NO_COMPILE_BATCHING` target property was added to
+  tell :ref:`Visual Studio Generators` whether to disable compiler parallelism
+  and call the compiler with one c/cpp file at a time.
diff --git a/Help/variable/CMAKE_INSTALL_PREFIX.rst b/Help/variable/CMAKE_INSTALL_PREFIX.rst
index 02ba645..b92d3ef 100644
--- a/Help/variable/CMAKE_INSTALL_PREFIX.rst
+++ b/Help/variable/CMAKE_INSTALL_PREFIX.rst
@@ -10,7 +10,8 @@ See :variable:`CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT` for how a
 project might choose its own default.
 
 On UNIX one can use the ``DESTDIR`` mechanism in order to relocate the
-whole installation. See :envvar:`DESTDIR` for more information.
+whole installation to a staging area.  See the :envvar:`DESTDIR` environment
+variable for more information.
 
 The installation prefix is also added to :variable:`CMAKE_SYSTEM_PREFIX_PATH`
 so that :command:`find_package`, :command:`find_program`,
@@ -21,3 +22,12 @@ will search the prefix for other software.
 
   Use the :module:`GNUInstallDirs` module to provide GNU-style
   options for the layout of directories within the installation.
+
+The ``CMAKE_INSTALL_PREFIX`` may be defined when configuring a build tree
+to set its installation prefix.  Or, when using the :manual:`cmake(1)`
+command-line tool's ``--install`` mode, one may specify a different prefix
+using the ``--prefix`` option:
+
+.. code-block:: shell
+
+  cmake --install . --prefix /my/install/prefix