mirror of
https://github.com/Kitware/CMake.git
synced 2026-11-06 05:16:58 +00:00
Matthew Woehlke
4bbdabae74
Enable test preparation targets by default. Add (better named) `CMAKE_SKIP_TEST_PREP_TARGETS` variable to control generation of the same, mirroring `CMAKE_SKIP_INSTALL_PREP_TARGETS`. Remove support for old `CMAKE_TEST_BUILD_DEPENDS` variable. Update and improve documentation. This improves consistency between test and install preparation targets. It also modifies the descriptions of preparation targets in the documentation of generators which support them to be consistent. (Previously, each generator described preparation targets in a manner unique to each generator.) Fixes: #28050
164 lines
5.3 KiB
ReStructuredText
164 lines
5.3 KiB
ReStructuredText
FASTBuild
|
|
=========
|
|
|
|
.. versionadded:: 4.2
|
|
|
|
Generates a ``fbuild.bff`` file, which can be used to build the project with
|
|
`FASTBuild <https://www.fastbuild.org/docs/home.html>`_.
|
|
|
|
Usage
|
|
-----
|
|
|
|
Specify the generator when invoking :manual:`cmake(1)`:
|
|
|
|
.. code-block:: shell
|
|
|
|
cmake [<options>] -G FASTBuild -B <path-to-build> [-S <path-to-source>]
|
|
|
|
This writes a FASTBuild configuration file named ``fbuild.bff`` into
|
|
``<path-to-build>``.
|
|
|
|
.. note::
|
|
|
|
This generator also produces IDE project files for Visual Studio and Xcode,
|
|
which are placed under:
|
|
|
|
* ``<path-to-build>/VisualStudio`` - Visual Studio solution and projects
|
|
* ``<path-to-build>/XCode`` - Xcode workspace and projects
|
|
|
|
These IDE files can be generated by building ``xcode`` or ``solution``
|
|
targets and will build using FASTBuild as the backend.
|
|
|
|
Built-in Targets
|
|
----------------
|
|
|
|
``install_prep/<component>``
|
|
|
|
.. versionadded:: 4.5
|
|
|
|
Created if the project has install rules, unless the
|
|
:variable:`CMAKE_SKIP_INSTALL_PREP_TARGETS` or
|
|
:variable:`CMAKE_SKIP_INSTALL_RULES` variable is enabled. Builds all known
|
|
build dependencies for the named install component. Components whose
|
|
names cannot be represented safely are excluded. See
|
|
:ref:`Install Preparation Targets` and :ref:`Target Names`.
|
|
|
|
``install_prep/all``
|
|
|
|
.. versionadded:: 4.5
|
|
|
|
Created if the project has install rules, unless the
|
|
:variable:`CMAKE_SKIP_INSTALL_PREP_TARGETS` or
|
|
:variable:`CMAKE_SKIP_INSTALL_RULES` variable is enabled. Builds all known
|
|
build dependencies for an installation that does not select a component.
|
|
See :ref:`Install Preparation Targets`.
|
|
|
|
``test_prep/<test-name>``
|
|
|
|
.. versionchanged:: 4.5
|
|
|
|
Created unless the :variable:`CMAKE_SKIP_TEST_PREP_TARGETS` variable is
|
|
enabled. Builds all known build dependencies for the named test, including
|
|
the executable target invoked by the test, targets referenced by generator
|
|
expressions in the test command, and explicit ``BUILD_DEPENDS`` entries.
|
|
|
|
Tests with names that are not valid target names are excluded. If multiple
|
|
tests in different directories share the same name, their dependencies are
|
|
merged into one ``test_prep/<test-name>`` target. See the
|
|
:manual:`cmake-buildsystem(7)` manual for more details on
|
|
:ref:`Target Names`.
|
|
|
|
Individual ``test_prep/<test-name>`` targets are not created for tests
|
|
discovered at test time, because their names are not known during
|
|
generation.
|
|
|
|
``test_prep/all``
|
|
|
|
.. versionchanged:: 4.5
|
|
|
|
Created unless the :variable:`CMAKE_SKIP_TEST_PREP_TARGETS` variable is
|
|
enabled. Depends on every generated ``test_prep/<test-name>`` target. Also
|
|
builds dependencies recorded by the :prop_dir:`CMAKE_TEST_BUILD_DEPENDS`
|
|
directory property.
|
|
|
|
Caching
|
|
-------
|
|
|
|
To enable FASTBuild caching, set the cache path using the
|
|
:variable:`CMAKE_FASTBUILD_CACHE_PATH` variable or the
|
|
``FASTBUILD_CACHE_PATH`` environment variable.
|
|
|
|
Then build with the ``-cache`` flag:
|
|
|
|
.. code-block:: console
|
|
|
|
cmake --build <path-to-build> -- -cache
|
|
|
|
Compiler Behavior Variables
|
|
---------------------------
|
|
|
|
The following variables control how compiler nodes are emitted in the generated
|
|
``fbuild.bff``. These settings may affect build determinism, debug info paths,
|
|
include handling, and compiler argument formatting:
|
|
|
|
* :variable:`CMAKE_FASTBUILD_ALLOW_RESPONSE_FILE`
|
|
* :variable:`CMAKE_FASTBUILD_CLANG_GCC_UPDATE_XLANG_ARG`
|
|
* :variable:`CMAKE_FASTBUILD_CLANG_REWRITE_INCLUDES`
|
|
* :variable:`CMAKE_FASTBUILD_COMPILER_EXTRA_FILES`
|
|
* :variable:`CMAKE_FASTBUILD_FORCE_RESPONSE_FILE`
|
|
* :variable:`CMAKE_FASTBUILD_SOURCE_MAPPING`
|
|
* :variable:`CMAKE_FASTBUILD_USE_DETERMINISTIC_PATHS`
|
|
* :variable:`CMAKE_FASTBUILD_USE_LIGHTCACHE`
|
|
* :variable:`CMAKE_FASTBUILD_USE_RELATIVE_PATHS`
|
|
|
|
Configuration Variables
|
|
-----------------------
|
|
|
|
The following variables can be used to configure this generator:
|
|
|
|
* :variable:`CMAKE_FASTBUILD_CACHE_PATH`
|
|
* :variable:`CMAKE_FASTBUILD_CAPTURE_SYSTEM_ENV`
|
|
* :variable:`CMAKE_FASTBUILD_ENV_OVERRIDES`
|
|
* :variable:`CMAKE_FASTBUILD_IDE_ARGS`
|
|
* :variable:`CMAKE_FASTBUILD_TRACK_BYPRODUCTS_AS_OUTPUT`
|
|
* :variable:`CMAKE_FASTBUILD_VERBOSE_GENERATOR`
|
|
|
|
Target Properties
|
|
-----------------
|
|
|
|
The following target properties can be used to fine-tune behavior on a
|
|
per-target basis:
|
|
|
|
* :prop_tgt:`FASTBUILD_CACHING` -
|
|
disables caching for a specific target.
|
|
* :prop_tgt:`FASTBUILD_DISTRIBUTION` -
|
|
disables distributed compilation for a specific target.
|
|
|
|
Notes
|
|
-----
|
|
|
|
* This generator does not support directories as outputs of custom commands.
|
|
If you do specify a directory as an output, it should be marked with the
|
|
``SYMBOLIC`` property to avoid incorrect behavior.
|
|
* It is highly advised to use custom commands with only one output.
|
|
If multiple outputs are specified, the generator will emit an additional
|
|
rule to check the outputs at build time. This adds overhead and is necessary
|
|
because FASTBuild natively supports only a single output per custom step.
|
|
|
|
Example
|
|
-------
|
|
|
|
.. code-block:: shell
|
|
|
|
cmake [<options>] -G FASTBuild -B <path-to-build> -DCMAKE_BUILD_TYPE=Release
|
|
cmake --build <path-to-build> --target my_app
|
|
|
|
This generates ``fbuild.bff`` in ``<path-to-build>`` and uses FASTBuild
|
|
to build the ``my_app`` target.
|
|
|
|
See Also
|
|
--------
|
|
|
|
* :manual:`cmake-generators(7)`
|
|
* `FASTBuild Documentation <https://www.fastbuild.org/docs/documentation.html>`_
|