1 files changed, 121 insertions, 0 deletions
diff --git a/share/cmake-3.17/Help/generator/Ninja Multi-Config.rst b/share/cmake-3.17/Help/generator/Ninja Multi-Config.rst
new file mode 100644
index 0000000..1f68535
--- /dev/null
+++ b/share/cmake-3.17/Help/generator/Ninja Multi-Config.rst
@@ -0,0 +1,121 @@
+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.) These files
+are intended to be run with ``ninja -f build-<Config>.ninja``. A
+``build.ninja`` file is also generated, using the configuration from either
+:variable:`CMAKE_DEFAULT_BUILD_TYPE` or the first item from
+:variable:`CMAKE_CONFIGURATION_TYPES`.
+
+``cmake --build . --config <Config>`` will always use ``build-<Config>.ninja``
+to build. If no ``--config`` argument is specified, ``cmake --build .`` will
+default to ``build-Debug.ninja``, unless a ``build.ninja`` is generated (see
+below), in which case that will be used instead.
+
+Each ``build-<Config>.ninja`` file contains ``<target>`` targets as well as
+``<target>:<Config>`` targets, where ``<Config>`` is the same as the
+configuration specified in ``build-<Config>.ninja`` Additionally, if
+cross-config mode is enabled, ``build-<Config>.ninja`` may contain
+``<target>:<OtherConfig>`` targets, where ``<OtherConfig>`` is a cross-config,
+as well as ``<target>:all``, which builds the target in all cross-configs. See
+below for how to enable cross-config mode.
+
+The ``Ninja Multi-Config`` generator recognizes the following variables:
+
+:variable:`CMAKE_CONFIGURATION_TYPES`
+  Specifies the total set of configurations to build. See the variable's
+  documentation for more information.
+
+:variable:`CMAKE_CROSS_CONFIGS`
+  Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of
+  configurations available from all ``build-<Config>.ninja`` files.
+  This variable activates cross-config mode.
+  Targets from each config specified in this variable can be built from any
+  ``build-<Config>.ninja`` file. Custom commands will use the configuration
+  native to ``build-<Config>.ninja``. If it is set to ``all``, all
+  configurations from :variable:`CMAKE_CONFIGURATION_TYPES` are cross-configs.
+  If it is not specified, or empty, each ``build-<Config>.ninja`` file will
+  only contain build rules for its own configuration.
+
+  The value of this variable must be a subset of
+  :variable:`CMAKE_CONFIGURATION_TYPES`.
+
+:variable:`CMAKE_DEFAULT_BUILD_TYPE`
+  Specifies the configuration to use by default in a ``build.ninja`` file. If
+  this variable is specified, ``build.ninja`` uses build rules from
+  ``build-<Config>.ninja`` by default. All custom commands are executed with
+  this configuration. If the variable is not specified, the first item from
+  :variable:`CMAKE_CONFIGURATION_TYPES` is used instead.
+
+  The value of this variable must be one of the items from
+  :variable:`CMAKE_CONFIGURATION_TYPES`.
+
+:variable:`CMAKE_DEFAULT_CONFIGS`
+  Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of
+  configurations to build for a target in ``build.ninja``
+  if no ``:<Config>`` suffix is specified. If it is set to ``all``, all
+  configurations from :variable:`CMAKE_CROSS_CONFIGS` are used. If
+  it is not specified, it defaults to
+  :variable:`CMAKE_DEFAULT_BUILD_TYPE`.
+
+  For example, if you set
+  :variable:`CMAKE_DEFAULT_BUILD_TYPE` to ``Release``, but
+  set :variable:`CMAKE_DEFAULT_CONFIGS` to ``Debug`` or ``all``,
+  all ``<target>`` aliases in ``build.ninja`` will resolve to
+  ``<target>:Debug`` or ``<target>:all``, but custom commands will still use
+  the ``Release`` configuration.
+
+  The value of this variable must be a subset of
+  :variable:`CMAKE_CROSS_CONFIGS` or be the same as
+  :variable:`CMAKE_DEFAULT_BUILD_TYPE`. It must not be
+  specified if :variable:`CMAKE_DEFAULT_BUILD_TYPE` or
+  :variable:`CMAKE_CROSS_CONFIGS` is not used.
+
+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 :variable:`CMAKE_CROSS_CONFIGS` is set to ``all``, and 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.