Help: Add documentation and release notes for multi-config Ninja

6 files changed, 98 insertions, 3 deletions

diff --git a/Help/generator/Ninja Multi-Config.rst b/Help/generator/Ninja Multi-Config.rst
new file mode 100644
index 0000000000..71cc392911
--- /dev/null
+++ b/Help/generator/Ninja Multi-Config.rst
@@ -0,0 +1,74 @@
+Ninja Multi-Config
+------------------
+
+Generates multiple ``build-<Config>.ninja`` files.
+
+This generator is very much like the :generator:`Ninja` generator, but with
+some key differences. Only these differences will be discussed in this
+document.
+
+Unlike the :generator:`Ninja` generator, ``Ninja Multi-Config`` generates
+multiple configurations at once with :variable:`CMAKE_CONFIGURATION_TYPES`
+instead of only one configuration with :variable:`CMAKE_BUILD_TYPE`. One
+``build-<Config>.ninja`` file will be generated for each of these
+configurations (with ``<Config>`` being the configuration name.) No
+``build.ninja`` file is generated, unless
+:variable:`CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE` is specified. You must specify
+the desired ``build-<Config>.ninja`` file with ``ninja -f``. Running
+``cmake --build . --config <Config> --target <target>`` will run Ninja with
+``build-<Config>.ninja`` as the ``-f`` file and ``<target>`` as the build
+target.
+
+Executables and libraries of any configuration can be built regardless of which
+``build-<Config>.ninja`` file is used, simply by specifying
+``<target>:<Config>`` as the Ninja target. You can also specify
+``<target>:all`` to build a target in all configurations. Each
+``build-<Config>.ninja`` file will additionally have ``<target>`` targets which
+are aliases for ``<target>:<Config>``. However, custom commands and custom
+targets will always use the configuration specified in
+``build-<Config>.ninja``. This is due to the fact that it is impossible in
+Ninja for the same file to be output with different commands in the same build
+graph.
+
+Consider the following example:
+
+.. code-block:: cmake
+
+  cmake_minimum_required(VERSION 3.16)
+  project(MultiConfigNinja C)
+
+  add_executable(generator generator.c)
+  add_custom_command(OUTPUT generated.c COMMAND generator generated.c)
+  add_library(generated ${CMAKE_BINARY_DIR}/generated.c)
+
+Now assume you configure the project with ``Ninja Multi-Config`` and run one of
+the following commands:
+
+.. code-block:: shell
+
+  ninja -f build-Debug.ninja generated
+  # OR
+  cmake --build . --config Debug --target generated
+
+This would build the ``Debug`` configuration of ``generator``, which would be
+used to generate ``generated.c``, which would be used to build the ``Debug``
+configuration of ``generated``.
+
+But if you run the following instead:
+
+.. code-block:: shell
+
+  ninja -f build-Release.ninja generated:Debug
+  # OR
+  cmake --build . --config Release --target generated:Debug
+
+This would build the ``Release`` configuration of ``generator``, which would be
+used to generate ``generated.c``, which would be used to build the ``Debug``
+configuration of ``generated``. This is useful for running a release-optimized
+version of a generator utility while still building the debug version of the
+targets built with the generated code.
+
+As a convenience, ``Ninja Multi-Config`` offers a
+:variable:`CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE` setting. If this variable is
+specified, a ``build.ninja`` file will be generated which points to the
+specified ``build-<Config>.ninja`` file.
diff --git a/Help/generator/Ninja.rst b/Help/generator/Ninja.rst
index c75d2c4cf3..275055d73a 100644
--- a/Help/generator/Ninja.rst
+++ b/Help/generator/Ninja.rst
@@ -1,7 +1,7 @@
 Ninja
 -----
 
-Generates build.ninja files.
+Generates ``build.ninja`` files.
 
 A ``build.ninja`` file is generated into the build tree.  Use the ninja
 program to build the project through the ``all`` target and install the
@@ -38,3 +38,9 @@ features have not been integrated into upstream Ninja.  Kitware maintains
 a branch of Ninja with the required features on `github.com/Kitware/ninja`_.
 
 .. _`github.com/Kitware/ninja`: https://github.com/Kitware/ninja/tree/features-for-fortran#readme
+
+See Also
+^^^^^^^^
+
+The :generator:`Ninja Multi-Config` generator is similar to the ``Ninja``
+generator, but generates multiple configurations at once.
diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst
index 41f7652201..6f88c0a093 100644
--- a/Help/manual/cmake-generators.7.rst
+++ b/Help/manual/cmake-generators.7.rst
@@ -52,13 +52,14 @@ Makefile Generators
    /generator/Unix Makefiles
    /generator/Watcom WMake
 
-Ninja Generator
-^^^^^^^^^^^^^^^
+Ninja Generators
+^^^^^^^^^^^^^^^^
 
 .. toctree::
    :maxdepth: 1
 
    /generator/Ninja
+   /generator/Ninja Multi-Config
 
 .. _`IDE Build Tool Generators`:
 
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 7a5e83e82e..51431241f8 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -214,6 +214,7 @@ Variables that Change Behavior
    /variable/CMAKE_MESSAGE_INDENT
    /variable/CMAKE_MESSAGE_LOG_LEVEL
    /variable/CMAKE_MODULE_PATH
+   /variable/CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE
    /variable/CMAKE_POLICY_DEFAULT_CMPNNNN
    /variable/CMAKE_POLICY_WARNING_CMPNNNN
    /variable/CMAKE_PREFIX_PATH
diff --git a/Help/release/dev/multi-configuration-ninja.rst b/Help/release/dev/multi-configuration-ninja.rst
new file mode 100644
index 0000000000..d9f72cbbff
--- /dev/null
+++ b/Help/release/dev/multi-configuration-ninja.rst
@@ -0,0 +1,6 @@
+multi-configuration-ninja
+-------------------------
+
+* :manual:`cmake(1)` gained a :generator:`Ninja Multi-Config` generator,
+  which is similar to the :generator:`Ninja` generator but can be used to build
+  multiple configurations at once.
diff --git a/Help/variable/CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE.rst b/Help/variable/CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE.rst
new file mode 100644
index 0000000000..2b950e13f9
--- /dev/null
+++ b/Help/variable/CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE.rst
@@ -0,0 +1,7 @@
+CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE
+------------------------------------
+
+Specifies a configuration type to use as the default in ``build.ninja`` for the
+:generator:`Ninja Multi-Config` generator.
+
+If this variable is not specified, no ``build.ninja`` file is generated.