mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-04 04:40:56 -06:00
Code Issues Packages Projects Releases Wiki Activity

Help: Improve readability and fix inaccuracies in unity build docs

Browse Source
This commit is contained in:
Craig Scott
2019-11-09 19:48:34 +11:00
parent 929d7a454c
commit fcacd8ce8d
7 changed files with 114 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst
View File

@@ -1,7 +1,11 @@
SKIP_UNITY_BUILD_INCLUSION SKIP_UNITY_BUILD_INCLUSION
-------------------------- --------------------------
Is this source file skipped by :prop_tgt:`UNITY_BUILD` feature. Setting this property to true ensures the source file will be skipped by
unity builds when its associated target has its :prop_tgt:`UNITY_BUILD`
property set to true. The source file will instead be compiled on its own
in the same way as it would with unity builds disabled.
This property helps with "ODR (One definition rule)" problems This property helps with "ODR (One definition rule)" problems where combining
that one would run into when using an :prop_tgt:`UNITY_BUILD`. a particular source file with others might lead to build errors or other
unintended side effects.

88
Help/prop_tgt/UNITY_BUILD.rst
View File

@@ -1,60 +1,60 @@
UNITY_BUILD UNITY_BUILD
----------- -----------
Should the target source files be processed into batches for When this property is set to true, the target source files will be combined
faster compilation. This feature is known as "Unity build", into batches for faster compilation. This is done by creating a (set of)
or "Jumbo build". unity sources which ``#include`` the original sources, then compiling these
unity sources instead of the originals. This is known as a *Unity* or *Jumbo*
build. The :prop_tgt:`UNITY_BUILD_BATCH_SIZE` property controls the upper
limit on how many sources can be combined per unity source file.
The ``C`` and ``CXX`` source files are grouped separately. Unity builds are not currently supported for all languages. CMake version
|release| supports combining ``C`` and ``CXX`` source files. For targets that
mix source files from more than one language, CMake will separate the languages
such that each generated unity source file only contains sources for a single
language.
This property is initialized by the value of the This property is initialized by the value of the :variable:`CMAKE_UNITY_BUILD`
:variable:`CMAKE_UNITY_BUILD` variable if it is set when variable when a target is created.
a target is created.
.. note:: .. note::
It's not recommended to directly set :prop_tgt:`UNITY_BUILD` Projects should not directly set the ``UNITY_BUILD`` property or its
to ``ON``, but to instead set :variable:`CMAKE_UNITY_BUILD` from associated :variable:`CMAKE_UNITY_BUILD` variable to true. Depending
the command line. However, it IS recommended to set on the capabilities of the build machine and compiler used, it might or
:prop_tgt:`UNITY_BUILD` to ``OFF`` if you need to ensure that a might not be appropriate to enable unity builds. Therefore, this feature
target doesn't get a unity build. should be under developer control, which would normally be through the
developer choosing whether or not to set the :variable:`CMAKE_UNITY_BUILD`
The batch size can be specified by setting variable on the :manual:`cmake(1)` command line or some other equivalent
:prop_tgt:`UNITY_BUILD_BATCH_SIZE`. method. However, it IS recommended to set the ``UNITY_BUILD`` target
property to false if it is known that enabling unity builds for the
The batching of source files is done by adding new sources files target can lead to problems.
which will ``#include`` the source files, and exclude them from
building by setting :prop_sf:`HEADER_FILE_ONLY` to ``ON``.
.. note::
Marking the original sources with :prop_sf:`HEADER_FILE_ONLY`
is considered an implementation detail that may change in the
future because it does not work well in combination with
the :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable.
ODR (One definition rule) errors ODR (One definition rule) errors
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Since multiple source files are included into one source file, When multiple source files are included into one source file, as is done
it can lead to ODR errors. This section contains properties for unity builds, it can potentially lead to ODR errors. CMake provides
which help fixing these errors. a number of measures to help address such problems:
The source files marked by :prop_sf:`SKIP_UNITY_BUILD_INCLUSION` * Any source file that has a non-empty :prop_sf:`COMPILE_OPTIONS`,
will be skipped from unity build. :prop_sf:`COMPILE_DEFINITIONS`, :prop_sf:`COMPILE_FLAGS`, or
:prop_sf:`INCLUDE_DIRECTORIES` source property will not be combined
into a unity source.
The source files that have :prop_sf:`COMPILE_OPTIONS`, * Projects can prevent an individual source file from being combined into
:prop_sf:`COMPILE_DEFINITIONS`, :prop_sf:`COMPILE_FLAGS`, or a unity source by setting its :prop_sf:`SKIP_UNITY_BUILD_INCLUSION`
:prop_sf:`INCLUDE_DIRECTORIES` will also be skipped. source property to true. This can be a more effective way to prevent
problems with specific files than disabling unity builds for an entire
target.
With the :prop_tgt:`UNITY_BUILD_CODE_BEFORE_INCLUDE` and * The :prop_tgt:`UNITY_BUILD_CODE_BEFORE_INCLUDE` and
:prop_tgt:`UNITY_BUILD_CODE_AFTER_INCLUDE` one can specify code :prop_tgt:`UNITY_BUILD_CODE_AFTER_INCLUDE` target properties can be used
to be injected in the unity source file before and after every to inject code into the unity source files before and after every
``#include`` statement. ``#include`` statement.
.. note:: * The order of source files added to the target via commands like
:command:`add_library`, :command:`add_executable` or
The order of source files defined in the ``CMakeLists.txt`` will :command:`target_sources` will be preserved in the generated unity source
be preserved into the generated unity source files. This can files. This can be used to manually enforce a specific grouping based on
be used to manually enforce a specific grouping based on the the :prop_tgt:`UNITY_BUILD_BATCH_SIZE` target property.
:prop_tgt:`UNITY_BUILD_BATCH_SIZE` target property.

26
Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst
View File

@@ -1,13 +1,23 @@
UNITY_BUILD_BATCH_SIZE UNITY_BUILD_BATCH_SIZE
---------------------- ----------------------
Specifies how many source code files will be included into a Specifies the maximum number of source files that can be combined into any one
:prop_tgt:`UNITY_BUILD` source file. unity source file when unity builds are enabled by the :prop_tgt:`UNITY_BUILD`
target property. The original source files will be distributed across as many
unity source files as necessary to honor this limit.
If the property is not set, CMake will use the value provided The initial value for this property is taken from the
by :variable:`CMAKE_UNITY_BUILD_BATCH_SIZE`. :variable:`CMAKE_UNITY_BUILD_BATCH_SIZE` variable when the target is created.
If that variable has not been set, the initial value will be 8.
By setting it to value `0` the generated unity source file will The batch size needs to be selected carefully. If set too high, the size of
contain all the source files that would otherwise be split the combined source files could result in the compiler using excessive memory
into multiple batches. It is not recommended to do so, since it or hitting other similar limits. In extreme cases, this can even result in
would affect performance. build failure. On the other hand, if the batch size is too low, there will be
little gain in build performance.
Although strongly discouraged, the batch size may be set to a value of 0 to
combine all the sources for the target into a single unity file, regardless of
how many sources are involved. This runs the risk of creating an excessively
large unity source file and negatively impacting the build performance, so
a value of 0 is not generally recommended.

17
Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst
View File

@@ -2,7 +2,18 @@ UNITY_BUILD_CODE_AFTER_INCLUDE
------------------------------ ------------------------------
Code snippet which is included verbatim by the :prop_tgt:`UNITY_BUILD` Code snippet which is included verbatim by the :prop_tgt:`UNITY_BUILD`
feature just after the `#include` statement of the targeted source feature just after every ``#include`` statement in the generated unity
files. source files. For example:
This could be something like `#undef NOMINMAX`. .. code-block:: cmake
set(after [[
#if defined(NOMINMAX)
#undef NOMINMAX
#endif
]])
set_target_properties(myTarget PROPERTIES
UNITY_BUILD_CODE_AFTER_INCLUDE "${after}"
)
See also :prop_tgt:`UNITY_BUILD_CODE_BEFORE_INCLUDE`.

17
Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst
View File

@@ -2,7 +2,18 @@ UNITY_BUILD_CODE_BEFORE_INCLUDE
------------------------------- -------------------------------
Code snippet which is included verbatim by the :prop_tgt:`UNITY_BUILD` Code snippet which is included verbatim by the :prop_tgt:`UNITY_BUILD`
feature just before the `#include` statement of the targeted source feature just before every ``#include`` statement in the generated unity
files. source files. For example:
This could be something like `#define NOMINMAX`. .. code-block:: cmake
set(before [[
#if !defined(NOMINMAX)
#define NOMINMAX
#endif
]])
set_target_properties(myTarget PROPERTIES
UNITY_BUILD_CODE_BEFORE_INCLUDE "${before}"
)
See also :prop_tgt:`UNITY_BUILD_CODE_AFTER_INCLUDE`.

18
Help/variable/CMAKE_UNITY_BUILD.rst
View File

@@ -1,11 +1,19 @@
CMAKE_UNITY_BUILD CMAKE_UNITY_BUILD
----------------- -----------------
Initializes the :prop_tgt:`UNITY_BUILD` target property on targets This variable is used to initialize the :prop_tgt:`UNITY_BUILD`
as they are created. Set to ``ON`` to batch compilation of multiple property of targets when they are created. Setting it to true
sources within each target. This feature is known as "Unity build", enables batch compilation of multiple sources within each target.
or "Jumbo build". By default this variable is not set and so does This feature is known as a *Unity* or *Jumbo* build.
not enable unity builds on targets.
Projects should not set this variable, it is intended as a developer
control to be set on the :manual:`cmake(1)` command line or other
equivalent methods. The developer must have the ability to enable or
disable unity builds according to the capabilities of their own machine
and compiler.
By default, this variable is not set, which will result in unity builds
being disabled.
.. note:: .. note::
This option currently does not work well in combination with This option currently does not work well in combination with

7
Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst
View File

@@ -1,6 +1,7 @@
CMAKE_UNITY_BUILD_BATCH_SIZE CMAKE_UNITY_BUILD_BATCH_SIZE
---------------------------- ----------------------------
Default value for :prop_tgt:`UNITY_BUILD_BATCH_SIZE` of targets. This variable is used to initialize the :prop_tgt:`UNITY_BUILD_BATCH_SIZE`
property of targets when they are created. It specifies the default upper
By default ``CMAKE_UNITY_BUILD_BATCH_SIZE`` is set to ``8``. limit on the number of source files that may be combined in any one unity
source file when unity builds are enabled for a target.