diff options
| -rw-r--r-- | Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst | 10 | ||||
| -rw-r--r-- | Help/prop_tgt/UNITY_BUILD.rst | 100 | ||||
| -rw-r--r-- | Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst | 26 | ||||
| -rw-r--r-- | Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst | 17 | ||||
| -rw-r--r-- | Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst | 17 | ||||
| -rw-r--r-- | Help/variable/CMAKE_UNITY_BUILD.rst | 18 | ||||
| -rw-r--r-- | Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst | 7 |
7 files changed, 120 insertions, 75 deletions
diff --git a/Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst b/Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst index 53f3970..6d1e60d 100644 --- a/Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst +++ b/Help/prop_sf/SKIP_UNITY_BUILD_INCLUSION.rst @@ -1,7 +1,11 @@ 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 -that one would run into when using an :prop_tgt:`UNITY_BUILD`. +This property helps with "ODR (One definition rule)" problems where combining +a particular source file with others might lead to build errors or other +unintended side effects. diff --git a/Help/prop_tgt/UNITY_BUILD.rst b/Help/prop_tgt/UNITY_BUILD.rst index fab4f15..479802e 100644 --- a/Help/prop_tgt/UNITY_BUILD.rst +++ b/Help/prop_tgt/UNITY_BUILD.rst @@ -1,60 +1,60 @@ UNITY_BUILD ----------- -Should the target source files be processed into batches for -faster compilation. This feature is known as "Unity build", -or "Jumbo build". - -The ``C`` and ``CXX`` source files are grouped separately. - -This property is initialized by the value of the -:variable:`CMAKE_UNITY_BUILD` variable if it is set when -a target is created. - -.. note:: - - It's not recommended to directly set :prop_tgt:`UNITY_BUILD` - to ``ON``, but to instead set :variable:`CMAKE_UNITY_BUILD` from - the command line. However, it IS recommended to set - :prop_tgt:`UNITY_BUILD` to ``OFF`` if you need to ensure that a - target doesn't get a unity build. - -The batch size can be specified by setting -:prop_tgt:`UNITY_BUILD_BATCH_SIZE`. - -The batching of source files is done by adding new sources files -which will ``#include`` the source files, and exclude them from -building by setting :prop_sf:`HEADER_FILE_ONLY` to ``ON``. +When this property is set to true, the target source files will be combined +into batches for faster compilation. This is done by creating a (set of) +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. + +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 :variable:`CMAKE_UNITY_BUILD` +variable when a target is created. .. 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. + Projects should not directly set the ``UNITY_BUILD`` property or its + associated :variable:`CMAKE_UNITY_BUILD` variable to true. Depending + on the capabilities of the build machine and compiler used, it might or + might not be appropriate to enable unity builds. Therefore, this feature + should be under developer control, which would normally be through the + developer choosing whether or not to set the :variable:`CMAKE_UNITY_BUILD` + variable on the :manual:`cmake(1)` command line or some other equivalent + method. However, it IS recommended to set the ``UNITY_BUILD`` target + property to false if it is known that enabling unity builds for the + target can lead to problems. ODR (One definition rule) errors ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Since multiple source files are included into one source file, -it can lead to ODR errors. This section contains properties -which help fixing these errors. - -The source files marked by :prop_sf:`SKIP_UNITY_BUILD_INCLUSION` -will be skipped from unity build. - -The source files that have :prop_sf:`COMPILE_OPTIONS`, -:prop_sf:`COMPILE_DEFINITIONS`, :prop_sf:`COMPILE_FLAGS`, or -:prop_sf:`INCLUDE_DIRECTORIES` will also be skipped. - -With the :prop_tgt:`UNITY_BUILD_CODE_BEFORE_INCLUDE` and -:prop_tgt:`UNITY_BUILD_CODE_AFTER_INCLUDE` one can specify code -to be injected in the unity source file before and after every -``#include`` statement. - -.. note:: - - The order of source files defined in the ``CMakeLists.txt`` will - be preserved into the generated unity source files. This can - be used to manually enforce a specific grouping based on the - :prop_tgt:`UNITY_BUILD_BATCH_SIZE` target property. +When multiple source files are included into one source file, as is done +for unity builds, it can potentially lead to ODR errors. CMake provides +a number of measures to help address such problems: + +* Any source file that has a non-empty :prop_sf:`COMPILE_OPTIONS`, + :prop_sf:`COMPILE_DEFINITIONS`, :prop_sf:`COMPILE_FLAGS`, or + :prop_sf:`INCLUDE_DIRECTORIES` source property will not be combined + into a unity source. + +* Projects can prevent an individual source file from being combined into + a unity source by setting its :prop_sf:`SKIP_UNITY_BUILD_INCLUSION` + 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. + +* The :prop_tgt:`UNITY_BUILD_CODE_BEFORE_INCLUDE` and + :prop_tgt:`UNITY_BUILD_CODE_AFTER_INCLUDE` target properties can be used + to inject code into the unity source files before and after every + ``#include`` statement. + +* The order of source files added to the target via commands like + :command:`add_library`, :command:`add_executable` or + :command:`target_sources` will be preserved in the generated unity source + files. This can be used to manually enforce a specific grouping based on + the :prop_tgt:`UNITY_BUILD_BATCH_SIZE` target property. diff --git a/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst b/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst index 84047f2..44ffe27 100644 --- a/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst +++ b/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst @@ -1,13 +1,23 @@ UNITY_BUILD_BATCH_SIZE ---------------------- -Specifies how many source code files will be included into a -:prop_tgt:`UNITY_BUILD` source file. +Specifies the maximum number of source files that can be combined into any one +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 -by :variable:`CMAKE_UNITY_BUILD_BATCH_SIZE`. +The initial value for this property is taken from the +: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 -contain all the source files that would otherwise be split -into multiple batches. It is not recommended to do so, since it -would affect performance. +The batch size needs to be selected carefully. If set too high, the size of +the combined source files could result in the compiler using excessive memory +or hitting other similar limits. In extreme cases, this can even result in +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. diff --git a/Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst b/Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst index 7795289..7231b61 100644 --- a/Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst +++ b/Help/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE.rst @@ -2,7 +2,18 @@ UNITY_BUILD_CODE_AFTER_INCLUDE ------------------------------ Code snippet which is included verbatim by the :prop_tgt:`UNITY_BUILD` -feature just after the `#include` statement of the targeted source -files. +feature just after every ``#include`` statement in the generated unity +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`. diff --git a/Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst b/Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst index f335463..7ed6fa1 100644 --- a/Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst +++ b/Help/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE.rst @@ -2,7 +2,18 @@ UNITY_BUILD_CODE_BEFORE_INCLUDE ------------------------------- Code snippet which is included verbatim by the :prop_tgt:`UNITY_BUILD` -feature just before the `#include` statement of the targeted source -files. +feature just before every ``#include`` statement in the generated unity +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`. diff --git a/Help/variable/CMAKE_UNITY_BUILD.rst b/Help/variable/CMAKE_UNITY_BUILD.rst index bbcfd68..a86cd67 100644 --- a/Help/variable/CMAKE_UNITY_BUILD.rst +++ b/Help/variable/CMAKE_UNITY_BUILD.rst @@ -1,11 +1,19 @@ CMAKE_UNITY_BUILD ----------------- -Initializes the :prop_tgt:`UNITY_BUILD` target property on targets -as they are created. Set to ``ON`` to batch compilation of multiple -sources within each target. This feature is known as "Unity build", -or "Jumbo build". By default this variable is not set and so does -not enable unity builds on targets. +This variable is used to initialize the :prop_tgt:`UNITY_BUILD` +property of targets when they are created. Setting it to true +enables batch compilation of multiple sources within each target. +This feature is known as a *Unity* or *Jumbo* build. + +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:: This option currently does not work well in combination with diff --git a/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst b/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst index 3ab2344..7988d4b 100644 --- a/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst +++ b/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst @@ -1,6 +1,7 @@ CMAKE_UNITY_BUILD_BATCH_SIZE ---------------------------- -Default value for :prop_tgt:`UNITY_BUILD_BATCH_SIZE` of targets. - -By default ``CMAKE_UNITY_BUILD_BATCH_SIZE`` is set to ``8``. +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 +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. |