Ninja: Support embedding of CMake as subninja project

Add a `CMAKE_NINJA_OUTPUT_PATH_PREFIX` variable.  When it is set, CMake
generates a `build.ninja` file suitable for embedding into another ninja
project potentially generated by an alien generator.

3 files changed, 34 insertions, 0 deletions

diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 181fbbcd1f..ec741ae12c 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -281,6 +281,7 @@ Variables that Control the Build
    /variable/CMAKE_MAP_IMPORTED_CONFIG_CONFIG
    /variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG
    /variable/CMAKE_MODULE_LINKER_FLAGS
+   /variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX
    /variable/CMAKE_NO_BUILTIN_CHRPATH
    /variable/CMAKE_NO_SYSTEM_FROM_IMPORTED
    /variable/CMAKE_OSX_ARCHITECTURES
diff --git a/Help/release/dev/ninja-output-path-prefix.rst b/Help/release/dev/ninja-output-path-prefix.rst
new file mode 100644
index 0000000000..47a96603a1
--- /dev/null
+++ b/Help/release/dev/ninja-output-path-prefix.rst
@@ -0,0 +1,6 @@
+ninja-output-path-prefix
+------------------------
+
+* The :generator:`Ninja` generator learned to read a new
+  :variable:`CMAKE_NINJA_OUTPUT_PATH_PREFIX` variable to configure
+  the generated ``build.ninja`` file for use as a ``subninja``.
diff --git a/Help/variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX.rst b/Help/variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX.rst
new file mode 100644
index 0000000000..64091aaaf5
--- /dev/null
+++ b/Help/variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX.rst
@@ -0,0 +1,27 @@
+CMAKE_NINJA_OUTPUT_PATH_PREFIX
+------------------------------
+
+Set output files path prefix for the :generator:`Ninja` generator.
+
+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::
+
+  cd top-build-dir/sub &&
+  cmake -G Ninja -DCMAKE_NINJA_OUTPUT_PATH_PREFIX=sub/ path/to/source
+
+can be embedded in ``top-build-dir/build.ninja`` 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``.
+
+.. 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.