Help: Clarify usage of CMAKE_NINJA_OUTPUT_PATH_PREFIX

Issue: #24566

1 files changed, 24 insertions, 13 deletions

diff --git a/Help/variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX.rst b/Help/variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX.rst
index a8c4035..79a65b8 100644
--- a/Help/variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX.rst
+++ b/Help/variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX.rst
@@ -3,27 +3,38 @@ CMAKE_NINJA_OUTPUT_PATH_PREFIX
 
 .. versionadded:: 3.6
 
-Set output files path prefix for the :generator:`Ninja` generator.
+Tell the :ref:`Ninja Generators` to add a prefix to every output path in
+``build.ninja``.  A trailing slash is appended to the prefix, if missing.
 
-Every output files listed in the generated ``build.ninja`` will be
-prefixed by the contents of this variable (a trailing slash is
-appended if missing).  This is useful when the generated ninja file is
-meant to be embedded as a ``subninja`` file into a *super* ninja
-project.  For example, a ninja build file generated with a command
-like::
+This is useful when the generated ninja file is meant to be embedded as a
+``subninja`` file into a *super* ninja project.  For example, the command:
 
-  cd top-build-dir/sub &&
-  cmake -G Ninja -DCMAKE_NINJA_OUTPUT_PATH_PREFIX=sub/ path/to/source
+.. code-block:: shell
 
-can be embedded in ``top-build-dir/build.ninja`` with a directive like
-this::
+  cd super-build-dir &&
+  cmake -G Ninja -S /path/to/src -B sub -DCMAKE_NINJA_OUTPUT_PATH_PREFIX=sub/
+  #                                 ^^^---------- these match -----------^^^
+
+generates a build directory with its top-level (:variable:`CMAKE_BINARY_DIR`)
+in ``super-build-dir/sub``.  The path to the build directory ends in the
+output path prefix.  This makes it suitable for use in a separately-written
+``super-build-dir/build.ninja`` file with a directive like this::
 
   subninja sub/build.ninja
 
-The ``auto-regeneration`` rule in ``top-build-dir/build.ninja`` must have an
-order-only dependency on ``sub/build.ninja``.
+The ``auto-regeneration`` rule in ``super-build-dir/build.ninja`` must
+have an order-only dependency on ``sub/build.ninja``.
+
+.. versionadded:: 3.27
+
+  The :generator:`Ninja Multi-Config` generator supports this variable.
 
 .. note::
   When ``CMAKE_NINJA_OUTPUT_PATH_PREFIX`` is set, the project generated
   by CMake cannot be used as a standalone project.  No default targets
   are specified.
+
+  The value of ``CMAKE_NINJA_OUTPUT_PATH_PREFIX`` must match one or more
+  path components at the *end* of :variable:`CMAKE_BINARY_DIR`, or the
+  behavior is undefined.  However, this requirement is not checked
+  automatically.