Ninja Multi-Config: Shuffle variables around

Remove redundant variable CMAKE_NINJA_MULTI_CROSS_CONFIG_ENABLE.
Rename other variables. Document and improve handling of error
conditions.

1 files changed, 62 insertions, 44 deletions

diff --git a/Help/generator/Ninja Multi-Config.rst b/Help/generator/Ninja Multi-Config.rst
index e7f362e..31e8ea9 100644
--- a/Help/generator/Ninja Multi-Config.rst
+++ b/Help/generator/Ninja Multi-Config.rst
@@ -12,35 +12,67 @@ 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.
-
-If :variable:`CMAKE_NINJA_MULTI_CROSS_CONFIG_ENABLE` is turned on, executables
-and libraries of any configuration can be built regardless of which
-``build-<Config>.ninja`` file is used, simply by specifying
-``<target>:<OtherConfig>`` 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.
-
-You can additionally use :variable:`CMAKE_NINJA_MULTI_CROSS_CONFIGS` to limit
-the configurations that get cross-generated. If this variable is set, each
-``build-<Config>.ninja`` file will only contain rules for the configurations
-listed in the variable, plus their own configuration. This also affects which
-configurations are built by the ``<target>:all`` target.
-
-If :variable:`CMAKE_NINJA_MULTI_CROSS_CONFIG_ENABLE` is not enabled, you can
-still build any target in ``build-<Config>.ninja`` by specifying
-``<target>:<Config>`` or ``<target>``, but not ``<target>:<OtherConfig>`` or
-``<target>:all``.
+``build.ninja`` file is generated by default (see below for how to generate
+it.)
+
+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_NMC_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_NMC_DEFAULT_BUILD_FILE_CONFIG`
+  Specifies the configuration to use by default in a ``build.ninja`` file. If
+  this variable is specified, a ``build.ninja`` file is generated which uses
+  build rules from ``build-<Config>.ninja`` by default. All custom commands are
+  executed with this configuration. If the variable is not specified, no
+  ``build.ninja`` file is generated.
+
+  The value of this variable must be one of the items from
+  :variable:`CMAKE_CONFIGURATION_TYPES`.
+
+:variable:`CMAKE_NMC_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_NMC_CROSS_CONFIGS` are used. If
+  it is not specified, it defaults to
+  :variable:`CMAKE_NMC_DEFAULT_BUILD_FILE_CONFIG`.
+
+  For example, if you set
+  :variable:`CMAKE_NMC_DEFAULT_BUILD_FILE_CONFIG` to ``Release``, but
+  set :variable:`CMAKE_NMC_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_NMC_CROSS_CONFIGS` or be the same as
+  :variable:`CMAKE_NMC_DEFAULT_BUILD_FILE_CONFIG`. It must not be
+  specified if :variable:`CMAKE_NMC_DEFAULT_BUILD_FILE_CONFIG` or
+  :variable:`CMAKE_NMC_CROSS_CONFIGS` is not used.
 
 Consider the following example:
 
@@ -66,7 +98,7 @@ 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_NINJA_MULTI_CROSS_CONFIG_ENABLE` is enabled, and you
+But if :variable:`CMAKE_NMC_CROSS_CONFIGS` is set to ``all``, and you
 run the following instead:
 
 .. code-block:: shell
@@ -80,17 +112,3 @@ 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. In addition, if
-:variable:`CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE` is used in conjunction with
-:variable:`CMAKE_NINJA_MULTI_CROSS_CONFIG_ENABLE`, you can also specify
-:variable:`CMAKE_NINJA_MULTI_DEFAULT_BUILD_ALIAS`, which changes the config
-of the ``<target>`` targets in ``build.ninja``. For example, if you set
-:variable:`CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE` to ``Release``, but set
-:variable:`CMAKE_NINJA_MULTI_DEFAULT_BUILD_ALIAS` 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.