diff options
Diffstat (limited to 'Help/prop_tgt/UNITY_BUILD.rst')
| -rw-r--r-- | Help/prop_tgt/UNITY_BUILD.rst | 100 |
1 files changed, 50 insertions, 50 deletions
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. |