Ninja Multi-Config: Make cross-config building opt-in

Many users will want to use the Ninja Multi-Config generator like a
traditional Visual Studio-style multi-config generator, which doesn't
mix configurations - custom commands are built using target executables
of the same configuration the command is for. We do not want to force
these people to generate an N*N build matrix when they only need N*1,
especially if they have lots of targets. Add a new variable,
CMAKE_NINJA_CROSS_CONFIG_ENABLE, to opt-in to the cross-config build
matrix.

3 files changed, 17 insertions, 3 deletions

diff --git a/Help/generator/Ninja Multi-Config.rst b/Help/generator/Ninja Multi-Config.rst
index 71cc392..92ca760 100644
--- a/Help/generator/Ninja Multi-Config.rst
+++ b/Help/generator/Ninja Multi-Config.rst
@@ -19,9 +19,10 @@ the desired ``build-<Config>.ninja`` file with ``ninja -f``. Running
 ``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
+If :variable:`CMAKE_NINJA_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>:<Config>`` as the Ninja target. You can also specify
+``<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
@@ -30,6 +31,11 @@ targets will always use the configuration specified in
 Ninja for the same file to be output with different commands in the same build
 graph.
 
+If :variable:`CMAKE_NINJA_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``.
+
 Consider the following example:
 
 .. code-block:: cmake
@@ -54,7 +60,8 @@ 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:
+But if :variable:`CMAKE_NINJA_CROSS_CONFIG_ENABLE` is enabled, and you run the
+following instead:
 
 .. code-block:: shell
 
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 74dd1fb..26f1d80 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -423,6 +423,7 @@ Variables that Control the Build
    /variable/CMAKE_MODULE_LINKER_FLAGS_INIT
    /variable/CMAKE_MSVCIDE_RUN_PATH
    /variable/CMAKE_MSVC_RUNTIME_LIBRARY
+   /variable/CMAKE_NINJA_CROSS_CONFIG_ENABLE
    /variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX
    /variable/CMAKE_NO_BUILTIN_CHRPATH
    /variable/CMAKE_NO_SYSTEM_FROM_IMPORTED
diff --git a/Help/variable/CMAKE_NINJA_CROSS_CONFIG_ENABLE.rst b/Help/variable/CMAKE_NINJA_CROSS_CONFIG_ENABLE.rst
new file mode 100644
index 0000000..5c9c1aa
--- /dev/null
+++ b/Help/variable/CMAKE_NINJA_CROSS_CONFIG_ENABLE.rst
@@ -0,0 +1,6 @@
+CMAKE_NINJA_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.