# Ninja Multi-Config

Generates multiple `build-<Config>.ninja` files.

This generator is very much like the `Ninja` generator, but with some key differences. Only these differences will be discussed in this document.

Unlike the `Ninja` generator, `Ninja Multi-Config` generates multiple configurations at once with `CMAKE_CONFIGURATION_TYPES` instead of only one configuration with `CMAKE_BUILD_TYPE`. One `build-<Config>.ninja` file will be generated for each of these configurations (with `<Config>` being the configuration name.) These files are intended to be run with `ninja -f build-<Config>.ninja`. A `build.ninja` file is also generated, using the configuration from either `CMAKE_DEFAULT_BUILD_TYPE` or the first item from `CMAKE_CONFIGURATION_TYPES`.

`cmake --build . --config <Config>` will always use `build-<Config>.ninja` to build. If no `--config` argument is specified, `cmake --build .` will default to `build-Debug.ninja`, unless a `build.ninja` is generated (see below), in which case that will be used instead.

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:

`CMAKE_CONFIGURATION_TYPES`

  Specifies the total set of configurations to build.

`CMAKE_CROSS_CONFIGS`

  Specifies a semicolon-separated list of configurations available from all `build-<Config>.ninja` files.

`CMAKE_DEFAULT_BUILD_TYPE`

  Specifies the configuration to use by default in a `build.ninja` file.

`CMAKE_DEFAULT_CONFIGS`

  Specifies a semicolon-separated list of configurations to build for a target in `build.ninja` if no `:<Config>` suffix is specified.

Consider the following example:

    cmake_minimum_required(VERSION 3.16)
    project(MultiConfigNinja C)

    add_executable(generator generator.c)
    add_custom_command(OUTPUT generated.c COMMAND generator generated.c)
    add_library(generated ${CMAKE_BINARY_DIR}/generated.c)

Now assume you configure the project with `Ninja Multi-Config` and run one of the following commands:

    ninja -f build-Debug.ninja generated
    # OR
    cmake --build . --config Debug --target generated

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 `CMAKE_CROSS_CONFIGS` is set to `all`, and you run the following instead:

    ninja -f build-Release.ninja generated:Debug
    # OR
    cmake --build . --config Release --target generated:Debug

This would build the `Release` configuration of `generator`, which would be 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.