UNITY_BUILD

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 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 3.17.5 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 CMAKE_UNITY_BUILD variable when a target is created.

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 COMPILE_OPTIONS, COMPILE_DEFINITIONS, COMPILE_FLAGS, or 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 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 UNITY_BUILD_CODE_BEFORE_INCLUDE and 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 add_library(), add_executable() or target_sources() will be preserved in the generated unity source files. This can be used to manually enforce a specific grouping based on the UNITY_BUILD_BATCH_SIZE target property.