Unity Build Merger Transformation
Unity build (also known as single compilation unit) is a technique used in C and C++ projects to combine multiple translation units so that they are compiled as a single unit. Instead of compiling each source file separately and then linking them, the compiler processes a single merged file that includes all source files. This reduces compile time because shared header files, definitions, and templates are parsed only once. It can also enable interprocedural optimizations, such as inlining functions across original file boundaries. However, unity builds increase incremental build times — any change requires recompiling the entire merged file — and they prevent parallel compilation.
Unity Build Merger Transformation in emmtrix Studio
The Unity Build Merger transformation in emmtrix Studio merges all C source files of a project into a single source file. It can be invoked via #pragma EMX_TRANSFORMATION UnityBuildMerger or through the graphical user interface. The transformation concatenates the contents of all C files in a deterministic order to form one translation unit. It automatically checks for duplicate or conflicting declarations (e.g., functions, variables, structs, enums) and performs renaming where necessary to resolve conflicts. After merging, the tool produces a new file that can be compiled directly, enabling the compiler to see the entire program at once.
Typical Usage and Benefits
- Compile time reduction: Unity builds are particularly useful when a project has many source files that all include the same expensive header files or templates. By merging these files, the compiler parses the common headers only once, significantly reducing total compile time.
- Whole‑program optimizations: The unified translation unit allows the compiler to perform whole‑program optimizations, such as inlining functions across file boundaries, without requiring link‑time optimization.
- Further optimization: A single translation unit enables additional optimization and transformation steps on the source code. For example, automated test case reduction becomes simpler when working on a single merged source file.
emmtrix Studio automates the generation of unity builds by applying the Unity Build Merger transformation to source projects. It ensures that a valid C program is generated, so developers do not need to manually create a unity file.
Example
Consider a project with two source files, foo.c and bar.c. In a normal build, these files are compiled separately.
/* foo.c */
void bar(void);
void foo(void) {
...
bar();
}
/* bar.c */
void bar(void) {
...
}
|
/* unity_build.c – generated by UnityBuildMerger */
void bar(void) {
...
}
void foo(void) {
...
bar();
}
|
The build system then compiles unity_build.c instead of compiling foo.c and bar.c separately, allowing the compiler to inline foo() and bar() wherever they are used, without relying on link‑time optimization.
Limitations
The transformation currently resolves all include directives and embeds the corresponding code directly into the generated source file. A parameter may be added in the future to keep the original #include directives instead of embedding their contents.
Parameters
| Parameter | Possible Values | Default Value | Description |
|---|---|---|---|
| Currently, no parameters | |||
External Links
- Single compilation unit – Wikipedia article about the unity build technique used in C/C++ projects.