echo/CMake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Help: Clarify usage of CMAKE_NINJA_OUTPUT_PATH_PREFIX

Browse Source 
Issue: #24566
This commit is contained in:
Brad King 2023-03-03 11:47:54 -05:00
parent 0a9945cb8d
commit dbcae48e3a
1 changed files with 24 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
Help/variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX.rst
View File

@ -3,27 +3,38 @@ CMAKE_NINJA_OUTPUT_PATH_PREFIX
.. versionadded:: 3.6
Set output files path prefix for the :generator:`Ninja` generator.
Tell the :ref:`Ninja Generators` to add a prefix to every output path in
``build.ninja``. A trailing slash is appended to the prefix, if missing.
Every output files listed in the generated ``build.ninja`` will be
prefixed by the contents of this variable (a trailing slash is
appended if missing). This is useful when the generated ninja file is
meant to be embedded as a ``subninja`` file into a *super* ninja
project. For example, a ninja build file generated with a command
like::
This is useful when the generated ninja file is meant to be embedded as a
``subninja`` file into a *super* ninja project. For example, the command:
cd top-build-dir/sub &&
cmake -G Ninja -DCMAKE_NINJA_OUTPUT_PATH_PREFIX=sub/ path/to/source
.. code-block:: shell
can be embedded in ``top-build-dir/build.ninja`` with a directive like
this::
cd super-build-dir &&
cmake -G Ninja -S /path/to/src -B sub -DCMAKE_NINJA_OUTPUT_PATH_PREFIX=sub/
# ^^^---------- these match -----------^^^
generates a build directory with its top-level (:variable:`CMAKE_BINARY_DIR`)
in ``super-build-dir/sub``. The path to the build directory ends in the
output path prefix. This makes it suitable for use in a separately-written
``super-build-dir/build.ninja`` file with a directive like this::
subninja sub/build.ninja
The ``auto-regeneration`` rule in ``top-build-dir/build.ninja`` must have an
order-only dependency on ``sub/build.ninja``.
The ``auto-regeneration`` rule in ``super-build-dir/build.ninja`` must
have an order-only dependency on ``sub/build.ninja``.
.. versionadded:: 3.27
The :generator:`Ninja Multi-Config` generator supports this variable.
.. note::
When ``CMAKE_NINJA_OUTPUT_PATH_PREFIX`` is set, the project generated
by CMake cannot be used as a standalone project. No default targets
are specified.
The value of ``CMAKE_NINJA_OUTPUT_PATH_PREFIX`` must match one or more
path components at the *end* of :variable:`CMAKE_BINARY_DIR`, or the
behavior is undefined. However, this requirement is not checked
automatically.