mirror of
https://github.com/Kitware/CMake.git
synced 2026-01-06 13:51:33 -06:00
121 lines
5.2 KiB
ReStructuredText
121 lines
5.2 KiB
ReStructuredText
Ninja Multi-Config
|
|
------------------
|
|
|
|
Generates multiple ``build-<Config>.ninja`` files.
|
|
|
|
This generator is very much like the :generator:`Ninja` generator, but with
|
|
some key differences. Only these differences will be discussed in this
|
|
document.
|
|
|
|
Unlike the :generator:`Ninja` generator, ``Ninja Multi-Config`` generates
|
|
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.) These files
|
|
are intended to be run with ``ninja -f build-<Config>.ninja``. No
|
|
``build.ninja`` file is generated by default (see below for how to generate
|
|
it.)
|
|
|
|
``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:
|
|
|
|
: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:
|
|
|
|
.. code-block:: cmake
|
|
|
|
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:
|
|
|
|
.. code-block:: shell
|
|
|
|
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 :variable:`CMAKE_NMC_CROSS_CONFIGS` is set to ``all``, and you
|
|
run the following instead:
|
|
|
|
.. code-block:: shell
|
|
|
|
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.
|