New in version 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
CMake provides different algorithms for selecting which sources are grouped
together into a bucket. Algorithm selection is decided by the
UNITY_BUILD_MODE target property, which has the following acceptable
BATCHWhen in this mode CMake determines which files are grouped together. The
UNITY_BUILD_BATCH_SIZEproperty controls the upper limit on how many sources can be combined per unity source file.
GROUPWhen in this mode each target explicitly specifies how to group source files. Each source file that has the same
UNITY_GROUPvalue will be grouped together. Any sources that don't have this property will be compiled individually. The
UNITY_BUILD_BATCH_SIZEproperty is ignored when using this mode.
If no explicit
UNITY_BUILD_MODE has been specified, CMake will
Unity builds are not currently supported for all languages. CMake version
3.20.2 supports combining
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
This property is initialized by the value of the
variable when a target is created.
Projects should not directly set the
UNITY_BUILD property or its
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 on the
cmake(1) command line or some other equivalent
method. However, it IS recommended to set the
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:
Projects can prevent an individual source file from being combined into a unity source by setting its
SKIP_UNITY_BUILD_INCLUSIONsource 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
UNITY_BUILD_UNIQUE_IDto 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 order of source files added to the target via commands like
target_sources()will be preserved in the generated unity source files. This can be used to manually enforce a specific grouping based on the