diff options
Diffstat (limited to 'Help/generator')
| -rw-r--r-- | Help/generator/Ninja Multi-Config.rst | 106 |
1 files changed, 62 insertions, 44 deletions
diff --git a/Help/generator/Ninja Multi-Config.rst b/Help/generator/Ninja Multi-Config.rst index e7f362e..31e8ea9 100644 --- a/Help/generator/Ninja Multi-Config.rst +++ b/Help/generator/Ninja Multi-Config.rst @@ -12,35 +12,67 @@ 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.) No -``build.ninja`` file is generated, unless -:variable:`CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE` is specified. You must specify -the desired ``build-<Config>.ninja`` file with ``ninja -f``. Running -``cmake --build . --config <Config> --target <target>`` will run Ninja with -``build-<Config>.ninja`` as the ``-f`` file and ``<target>`` as the build -target. - -If :variable:`CMAKE_NINJA_MULTI_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>:<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 -targets will always use the configuration specified in -``build-<Config>.ninja``. This is due to the fact that it is impossible in -Ninja for the same file to be output with different commands in the same build -graph. - -You can additionally use :variable:`CMAKE_NINJA_MULTI_CROSS_CONFIGS` to limit -the configurations that get cross-generated. If this variable is set, each -``build-<Config>.ninja`` file will only contain rules for the configurations -listed in the variable, plus their own configuration. This also affects which -configurations are built by the ``<target>:all`` target. - -If :variable:`CMAKE_NINJA_MULTI_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``. +``build.ninja`` file is generated by default (see below for how to generate +it.) + +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: @@ -66,7 +98,7 @@ 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_NINJA_MULTI_CROSS_CONFIG_ENABLE` is enabled, and you +But if :variable:`CMAKE_NMC_CROSS_CONFIGS` is set to ``all``, and you run the following instead: .. code-block:: shell @@ -80,17 +112,3 @@ 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. - -As a convenience, ``Ninja Multi-Config`` offers a -:variable:`CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE` setting. If this variable is -specified, a ``build.ninja`` file will be generated which points to the -specified ``build-<Config>.ninja`` file. In addition, if -:variable:`CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE` is used in conjunction with -:variable:`CMAKE_NINJA_MULTI_CROSS_CONFIG_ENABLE`, you can also specify -:variable:`CMAKE_NINJA_MULTI_DEFAULT_BUILD_ALIAS`, which changes the config -of the ``<target>`` targets in ``build.ninja``. For example, if you set -:variable:`CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE` to ``Release``, but set -:variable:`CMAKE_NINJA_MULTI_DEFAULT_BUILD_ALIAS` 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. |