4 Generates multiple ``build-<Config>.ninja`` files.
6 This generator is very much like the :generator:`Ninja` generator, but with
7 some key differences. Only these differences will be discussed in this
10 Unlike the :generator:`Ninja` generator, ``Ninja Multi-Config`` generates
11 multiple configurations at once with :variable:`CMAKE_CONFIGURATION_TYPES`
12 instead of only one configuration with :variable:`CMAKE_BUILD_TYPE`. One
13 ``build-<Config>.ninja`` file will be generated for each of these
14 configurations (with ``<Config>`` being the configuration name.) These files
15 are intended to be run with ``ninja -f build-<Config>.ninja``. A
16 ``build.ninja`` file is also generated, using the configuration from either
17 :variable:`CMAKE_DEFAULT_BUILD_TYPE` or the first item from
18 :variable:`CMAKE_CONFIGURATION_TYPES`.
20 ``cmake --build . --config <Config>`` will always use ``build-<Config>.ninja``
21 to build. If no ``--config`` argument is specified, ``cmake --build .`` will
22 default to ``build-Debug.ninja``, unless a ``build.ninja`` is generated (see
23 below), in which case that will be used instead.
25 Each ``build-<Config>.ninja`` file contains ``<target>`` targets as well as
26 ``<target>:<Config>`` targets, where ``<Config>`` is the same as the
27 configuration specified in ``build-<Config>.ninja`` Additionally, if
28 cross-config mode is enabled, ``build-<Config>.ninja`` may contain
29 ``<target>:<OtherConfig>`` targets, where ``<OtherConfig>`` is a cross-config,
30 as well as ``<target>:all``, which builds the target in all cross-configs. See
31 below for how to enable cross-config mode.
33 The ``Ninja Multi-Config`` generator recognizes the following variables:
35 :variable:`CMAKE_CONFIGURATION_TYPES`
36 Specifies the total set of configurations to build.
38 :variable:`CMAKE_CROSS_CONFIGS`
39 Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of
40 configurations available from all ``build-<Config>.ninja`` files.
42 :variable:`CMAKE_DEFAULT_BUILD_TYPE`
43 Specifies the configuration to use by default in a ``build.ninja`` file.
45 :variable:`CMAKE_DEFAULT_CONFIGS`
46 Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of
47 configurations to build for a target in ``build.ninja``
48 if no ``:<Config>`` suffix is specified.
50 Consider the following example:
54 cmake_minimum_required(VERSION 3.16)
55 project(MultiConfigNinja C)
57 add_executable(generator generator.c)
58 add_custom_command(OUTPUT generated.c COMMAND generator generated.c)
59 add_library(generated ${CMAKE_BINARY_DIR}/generated.c)
61 Now assume you configure the project with ``Ninja Multi-Config`` and run one of
62 the following commands:
66 ninja -f build-Debug.ninja generated
68 cmake --build . --config Debug --target generated
70 This would build the ``Debug`` configuration of ``generator``, which would be
71 used to generate ``generated.c``, which would be used to build the ``Debug``
72 configuration of ``generated``.
74 But if :variable:`CMAKE_CROSS_CONFIGS` is set to ``all``, and you run the
79 ninja -f build-Release.ninja generated:Debug
81 cmake --build . --config Release --target generated:Debug
83 This would build the ``Release`` configuration of ``generator``, which would be
84 used to generate ``generated.c``, which would be used to build the ``Debug``
85 configuration of ``generated``. This is useful for running a release-optimized
86 version of a generator utility while still building the debug version of the
87 targets built with the generated code.