From 8c062f9d9986560588bbc5b7cffbbf3de940cc02 Mon Sep 17 00:00:00 2001 From: Kyle Edwards Date: Wed, 27 Nov 2019 11:58:02 -0500 Subject: Help: Add documentation and release notes for multi-config Ninja --- Help/generator/Ninja Multi-Config.rst | 74 ++++++++++++++++++++++ Help/generator/Ninja.rst | 8 ++- Help/manual/cmake-generators.7.rst | 5 +- Help/manual/cmake-variables.7.rst | 1 + Help/release/dev/multi-configuration-ninja.rst | 6 ++ .../CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE.rst | 7 ++ 6 files changed, 98 insertions(+), 3 deletions(-) create mode 100644 Help/generator/Ninja Multi-Config.rst create mode 100644 Help/release/dev/multi-configuration-ninja.rst create mode 100644 Help/variable/CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE.rst diff --git a/Help/generator/Ninja Multi-Config.rst b/Help/generator/Ninja Multi-Config.rst new file mode 100644 index 0000000..71cc392 --- /dev/null +++ b/Help/generator/Ninja Multi-Config.rst @@ -0,0 +1,74 @@ +Ninja Multi-Config +------------------ + +Generates multiple ``build-.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-.ninja`` file will be generated for each of these +configurations (with ```` 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-.ninja`` file with ``ninja -f``. Running +``cmake --build . --config --target `` will run Ninja with +``build-.ninja`` as the ``-f`` file and ```` as the build +target. + +Executables and libraries of any configuration can be built regardless of which +``build-.ninja`` file is used, simply by specifying +``:`` as the Ninja target. You can also specify +``:all`` to build a target in all configurations. Each +``build-.ninja`` file will additionally have ```` targets which +are aliases for ``:``. However, custom commands and custom +targets will always use the configuration specified in +``build-.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. + +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 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. + +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-.ninja`` file. diff --git a/Help/generator/Ninja.rst b/Help/generator/Ninja.rst index c75d2c4..275055d 100644 --- a/Help/generator/Ninja.rst +++ b/Help/generator/Ninja.rst @@ -1,7 +1,7 @@ Ninja ----- -Generates build.ninja files. +Generates ``build.ninja`` files. A ``build.ninja`` file is generated into the build tree. Use the ninja program to build the project through the ``all`` target and install the @@ -38,3 +38,9 @@ features have not been integrated into upstream Ninja. Kitware maintains a branch of Ninja with the required features on `github.com/Kitware/ninja`_. .. _`github.com/Kitware/ninja`: https://github.com/Kitware/ninja/tree/features-for-fortran#readme + +See Also +^^^^^^^^ + +The :generator:`Ninja Multi-Config` generator is similar to the ``Ninja`` +generator, but generates multiple configurations at once. diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index 41f7652..6f88c0a 100644 --- a/Help/manual/cmake-generators.7.rst +++ b/Help/manual/cmake-generators.7.rst @@ -52,13 +52,14 @@ Makefile Generators /generator/Unix Makefiles /generator/Watcom WMake -Ninja Generator -^^^^^^^^^^^^^^^ +Ninja Generators +^^^^^^^^^^^^^^^^ .. toctree:: :maxdepth: 1 /generator/Ninja + /generator/Ninja Multi-Config .. _`IDE Build Tool Generators`: diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 7a5e83e..5143124 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -214,6 +214,7 @@ Variables that Change Behavior /variable/CMAKE_MESSAGE_INDENT /variable/CMAKE_MESSAGE_LOG_LEVEL /variable/CMAKE_MODULE_PATH + /variable/CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE /variable/CMAKE_POLICY_DEFAULT_CMPNNNN /variable/CMAKE_POLICY_WARNING_CMPNNNN /variable/CMAKE_PREFIX_PATH diff --git a/Help/release/dev/multi-configuration-ninja.rst b/Help/release/dev/multi-configuration-ninja.rst new file mode 100644 index 0000000..d9f72cb --- /dev/null +++ b/Help/release/dev/multi-configuration-ninja.rst @@ -0,0 +1,6 @@ +multi-configuration-ninja +------------------------- + +* :manual:`cmake(1)` gained a :generator:`Ninja Multi-Config` generator, + which is similar to the :generator:`Ninja` generator but can be used to build + multiple configurations at once. diff --git a/Help/variable/CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE.rst b/Help/variable/CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE.rst new file mode 100644 index 0000000..2b950e1 --- /dev/null +++ b/Help/variable/CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE.rst @@ -0,0 +1,7 @@ +CMAKE_NINJA_MULTI_DEFAULT_BUILD_TYPE +------------------------------------ + +Specifies a configuration type to use as the default in ``build.ninja`` for the +:generator:`Ninja Multi-Config` generator. + +If this variable is not specified, no ``build.ninja`` file is generated. -- cgit v0.12