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.

9 files changed, 85 insertions, 78 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.
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 63deda5..ef6fa01 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -426,10 +426,9 @@ Variables that Control the Build
    /variable/CMAKE_MODULE_LINKER_FLAGS_INIT
    /variable/CMAKE_MSVCIDE_RUN_PATH
    /variable/CMAKE_MSVC_RUNTIME_LIBRARY
-   /variable/CMAKE_NINJA_MULTI_CROSS_CONFIGS
-   /variable/CMAKE_NINJA_MULTI_CROSS_CONFIG_ENABLE
-   /variable/CMAKE_NINJA_MULTI_DEFAULT_BUILD_ALIAS
-   /variable/CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE
+   /variable/CMAKE_NMC_CROSS_CONFIGS
+   /variable/CMAKE_NMC_DEFAULT_BUILD_FILE_CONFIG
+   /variable/CMAKE_NMC_DEFAULT_CONFIGS
    /variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX
    /variable/CMAKE_NO_BUILTIN_CHRPATH
    /variable/CMAKE_NO_SYSTEM_FROM_IMPORTED
diff --git a/Help/variable/CMAKE_NINJA_MULTI_CROSS_CONFIGS.rst b/Help/variable/CMAKE_NINJA_MULTI_CROSS_CONFIGS.rst
deleted file mode 100644
index 48f6985..0000000
--- a/Help/variable/CMAKE_NINJA_MULTI_CROSS_CONFIGS.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-CMAKE_NINJA_MULTI_CROSS_CONFIGS
--------------------------------
-
-Set which configurations get cross-built if
-:variable:`CMAKE_NINJA_MULTI_CROSS_CONFIG_ENABLE` is set. See the
-documentation for the :generator:`Ninja Multi-Config` generator for more
-information.
diff --git a/Help/variable/CMAKE_NINJA_MULTI_CROSS_CONFIG_ENABLE.rst b/Help/variable/CMAKE_NINJA_MULTI_CROSS_CONFIG_ENABLE.rst
deleted file mode 100644
index 0571d52..0000000
--- a/Help/variable/CMAKE_NINJA_MULTI_CROSS_CONFIG_ENABLE.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-CMAKE_NINJA_MULTI_CROSS_CONFIG_ENABLE
--------------------------------------
-
-If this variable is enabled, cross-configuration building is enabled in the
-:generator:`Ninja Multi-Config` generator. See the generator's description for
-more details. This variable is ``OFF`` by default.
-
-This variable is meant to be set from the command line (via
-``-DCMAKE_NINJA_MULTI_CROSS_CONFIG_ENABLE:BOOL=ON``) and should not be set from
-project code.
diff --git a/Help/variable/CMAKE_NINJA_MULTI_DEFAULT_BUILD_ALIAS.rst b/Help/variable/CMAKE_NINJA_MULTI_DEFAULT_BUILD_ALIAS.rst
deleted file mode 100644
index a997e9b..0000000
--- a/Help/variable/CMAKE_NINJA_MULTI_DEFAULT_BUILD_ALIAS.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-CMAKE_NINJA_MULTI_DEFAULT_BUILD_ALIAS
--------------------------------------
-
-Controls the config of ``<target>`` aliases in ``build.ninja`` for the
-:generator:`Ninja Multi-Config` generator. See the generator's documentation
-for more details.
diff --git a/Help/variable/CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE.rst b/Help/variable/CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE.rst
deleted file mode 100644
index 2b950e1..0000000
--- a/Help/variable/CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-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.
diff --git a/Help/variable/CMAKE_NMC_CROSS_CONFIGS.rst b/Help/variable/CMAKE_NMC_CROSS_CONFIGS.rst
new file mode 100644
index 0000000..6eb6494
--- /dev/null
+++ b/Help/variable/CMAKE_NMC_CROSS_CONFIGS.rst
@@ -0,0 +1,7 @@
+CMAKE_NMC_CROSS_CONFIGS
+-------------------------------
+
+Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of
+configurations available from all ``build-<Config>.ninja`` files in the
+:generator:`Ninja Multi-Config` generator. See the generator's
+documentation for more details.
diff --git a/Help/variable/CMAKE_NMC_DEFAULT_BUILD_FILE_CONFIG.rst b/Help/variable/CMAKE_NMC_DEFAULT_BUILD_FILE_CONFIG.rst
new file mode 100644
index 0000000..c0eab56
--- /dev/null
+++ b/Help/variable/CMAKE_NMC_DEFAULT_BUILD_FILE_CONFIG.rst
@@ -0,0 +1,6 @@
+CMAKE_NMC_DEFAULT_BUILD_FILE_CONFIG
+-------------------------------------------
+
+Specifies the configuration to use by default in a ``build.ninja`` file in the
+:generator:`Ninja Multi-Config` generator. See the generator's documentation
+for more details.
diff --git a/Help/variable/CMAKE_NMC_DEFAULT_CONFIGS.rst b/Help/variable/CMAKE_NMC_DEFAULT_CONFIGS.rst
new file mode 100644
index 0000000..e2bb017
--- /dev/null
+++ b/Help/variable/CMAKE_NMC_DEFAULT_CONFIGS.rst
@@ -0,0 +1,7 @@
+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 in
+the :generator:`Ninja Multi-Config` generator.
+See the generator's documentation for more details.