CMake/Help/prop_tgt/UNITY_BUILD.rst

UNITY_BUILD
-----------

.. versionadded:: 3.16

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.

CMake provides different algorithms for selecting which sources are grouped
together into a *bucket*. Algorithm selection is decided by the
:prop_tgt:`UNITY_BUILD_MODE` target property, which has the following acceptable
values:

* ``BATCH``
  When in this mode CMake determines which files are grouped together.
  The :prop_tgt:`UNITY_BUILD_BATCH_SIZE` property controls the upper limit on
  how many sources can be combined per unity source file.

* ``GROUP``
  When in this mode each target explicitly specifies how to group
  source files. Each source file that has the same
  :prop_sf:`UNITY_GROUP` value will be grouped together. Any sources
  that don't have this property will be compiled individually. The
  :prop_tgt:`UNITY_BUILD_BATCH_SIZE` property is ignored when using
  this mode.

If no explicit :prop_tgt:`UNITY_BUILD_MODE` has been specified, CMake will
default to ``BATCH``.

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::

  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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.

* Projects can set :prop_tgt:`UNITY_BUILD_UNIQUE_ID` to cause a valid
  C-identifier to be generated which is unique per file in a unity
  build.  This can be used to avoid problems with anonymous namespaces
  in unity builds.

* 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.