Unity build

In software engineering, a unity build (also known as unified build, jumbo build or blob build) is a method used in C and C++ software development to speed up the compilation of projects by combining multiple translation units into a single one, usually achieved by using include directives to bundle multiple source files into one larger file.

If two different translation units FileA.cpp:

#include "Header.hpp"

// content of source file A ...

and FileB.cpp:

#include "Header.hpp"

// content of source file B ...

in the same project both include the header Header.hpp, that header will be processed twice by the compiler chain, once for each build task. If the two translation units are merged into a single source file JumboFile.cpp:

#include "FileA.cpp"
#include "FileB.cpp"

then Header.hpp will be processed only once (thanks to include guards) when compiling JumboFile.cpp.^[1]

The main benefit of unity builds is a reduction of duplicated effort in parsing and compiling the content of headers that are included in more than one source file. The content of headers usually accounts for the majority of code in a source file after preprocessing. Unity builds also mitigate the overhead caused by having a large number of small source files by reducing the number of object files created and processed by the compilation chain, and allows interprocedural analysis and optimisation across the files that form the unity build task (similar to the effects of link-time optimisation). They make it also easier to detect violations of the One Definition Rule, because if a symbol is defined twice in different source files in the same unity build, the compiler will be able to identify the redefinition and emit a warning or error.

One of the drawbacks of unity builds is a larger memory footprint due to larger translation units. Larger translation units can also negatively affect parallel builds, since a small number of large compile jobs is generally harder or impossible to schedule to saturate all available parallel computing resources effectively. Unity builds can also deny part of the benefits of incremental builds, that rely on rebuilding as little code as possible, i.e. only the translation units affected by changes since the last build. These disadvantages can be offset by a great increase in the speed of the application linker stage, which no longer has to load and eliminate duplicate template codegen blocks in each translation unit. The linker stage memory use will also decrease.

Unity builds have also potentially dangerous effects on the semantics of programs. Some valid C++ constructs that rely on internal linkage may fail under a unity build, for instance clashes of static symbols and symbols defined in anonymous namespaces with the same identifier in different files. If different C++ files define different functions with the same name, the compiler may unexpectedly resolve the overloading by selecting the wrong function, in a way that was not possible when designing the software with the files as different translation units. Another adverse effect is the possible leakage of macro definitions across different source files.^[2]

Some build systems provide built-in support for automated unity builds, including Visual Studio,^[3] Meson,^[4] CMake.^[5] and xmake.

• Kubota, Takafumi; Yusuke, Suzuki; and, Kenji Kono (2019). To unify or not to unify: a case study on unified builds (in WebKit). Proceedings of the 28th International Conference on Compiler Construction. doi:10.1145/3302516.3307347.