Help/generator/Ninja Multi-Config.rst

   1 Ninja Multi-Config
   2 ------------------
   3
   4 Generates multiple ``build-<Config>.ninja`` files.
   5
   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
   8 document.
   9
  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`.
  19
  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.
  24
  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.
  32
  33 The ``Ninja Multi-Config`` generator recognizes the following variables:
  34
  35 :variable:`CMAKE_CONFIGURATION_TYPES`
  36   Specifies the total set of configurations to build. See the variable's
  37   documentation for more information.
  38
  39 :variable:`CMAKE_CROSS_CONFIGS`
  40   Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of
  41   configurations available from all ``build-<Config>.ninja`` files.
  42   This variable activates cross-config mode.
  43   Targets from each config specified in this variable can be built from any
  44   ``build-<Config>.ninja`` file. Custom commands will use the configuration
  45   native to ``build-<Config>.ninja``. If it is set to ``all``, all
  46   configurations from :variable:`CMAKE_CONFIGURATION_TYPES` are cross-configs.
  47   If it is not specified, or empty, each ``build-<Config>.ninja`` file will
  48   only contain build rules for its own configuration.
  49
  50   The value of this variable must be a subset of
  51   :variable:`CMAKE_CONFIGURATION_TYPES`.
  52
  53 :variable:`CMAKE_DEFAULT_BUILD_TYPE`
  54   Specifies the configuration to use by default in a ``build.ninja`` file. If
  55   this variable is specified, ``build.ninja`` uses build rules from
  56   ``build-<Config>.ninja`` by default. All custom commands are executed with
  57   this configuration. If the variable is not specified, the first item from
  58   :variable:`CMAKE_CONFIGURATION_TYPES` is used instead.
  59
  60   The value of this variable must be one of the items from
  61   :variable:`CMAKE_CONFIGURATION_TYPES`.
  62
  63 :variable:`CMAKE_DEFAULT_CONFIGS`
  64   Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of
  65   configurations to build for a target in ``build.ninja``
  66   if no ``:<Config>`` suffix is specified. If it is set to ``all``, all
  67   configurations from :variable:`CMAKE_CROSS_CONFIGS` are used. If
  68   it is not specified, it defaults to
  69   :variable:`CMAKE_DEFAULT_BUILD_TYPE`.
  70
  71   For example, if you set
  72   :variable:`CMAKE_DEFAULT_BUILD_TYPE` to ``Release``, but
  73   set :variable:`CMAKE_DEFAULT_CONFIGS` to ``Debug`` or ``all``,
  74   all ``<target>`` aliases in ``build.ninja`` will resolve to
  75   ``<target>:Debug`` or ``<target>:all``, but custom commands will still use
  76   the ``Release`` configuration.
  77
  78   The value of this variable must be a subset of
  79   :variable:`CMAKE_CROSS_CONFIGS` or be the same as
  80   :variable:`CMAKE_DEFAULT_BUILD_TYPE`. It must not be
  81   specified if :variable:`CMAKE_DEFAULT_BUILD_TYPE` or
  82   :variable:`CMAKE_CROSS_CONFIGS` is not used.
  83
  84 Consider the following example:
  85
  86 .. code-block:: cmake
  87
  88   cmake_minimum_required(VERSION 3.16)
  89   project(MultiConfigNinja C)
  90
  91   add_executable(generator generator.c)
  92   add_custom_command(OUTPUT generated.c COMMAND generator generated.c)
  93   add_library(generated ${CMAKE_BINARY_DIR}/generated.c)
  94
  95 Now assume you configure the project with ``Ninja Multi-Config`` and run one of
  96 the following commands:
  97
  98 .. code-block:: shell
  99
 100   ninja -f build-Debug.ninja generated
 101   # OR
 102   cmake --build . --config Debug --target generated
 103
 104 This would build the ``Debug`` configuration of ``generator``, which would be
 105 used to generate ``generated.c``, which would be used to build the ``Debug``
 106 configuration of ``generated``.
 107
 108 But if :variable:`CMAKE_CROSS_CONFIGS` is set to ``all``, and you run the
 109 following instead:
 110
 111 .. code-block:: shell
 112
 113   ninja -f build-Release.ninja generated:Debug
 114   # OR
 115   cmake --build . --config Release --target generated:Debug
 116
 117 This would build the ``Release`` configuration of ``generator``, which would be
 118 used to generate ``generated.c``, which would be used to build the ``Debug``
 119 configuration of ``generated``. This is useful for running a release-optimized
 120 version of a generator utility while still building the debug version of the
 121 targets built with the generated code.