Unity build

This article is about the compilation technique. For versions of the Unity game engine, see Unity (game engine) § History.

In software engineering, a unity build (also known as unified build or jumbo 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.

Implementation

If two different translation units file_a.cc

#include "header.h"

// content of source file A ...

and file_b.cc

#include "header.h"

// content of source file B ...

in the same project both include the header header.h, 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 jumbo_file.cc

#include "file_a.cc"
#include "file_b.cc"

then header.h will be processed only once (thanks to include guards) when compiling jumbo_file.cc.

Effects

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.

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.

Build system support

Some build systems provide built-in support for automated unity builds, including Visual Studio, Meson, CMake. and xmake.

References

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