|
|
|
|
---
|
|
|
|
|
short-description: Unity builds are a technique for reducing build times
|
|
|
|
|
...
|
|
|
|
|
|
|
|
|
|
# Unity builds
|
|
|
|
|
|
|
|
|
|
Unity builds are a technique for cutting down build times. The way it
|
|
|
|
|
works is relatively straightforward. Suppose we have source files
|
|
|
|
|
`src1.c`, `src2.c` and `src3.c`. Normally we would run the compiler
|
|
|
|
|
three times, once for each file. In a unity build we instead compile
|
|
|
|
|
all these sources in a single unit. The simplest approach is to create
|
|
|
|
|
a new source file that looks like this.
|
|
|
|
|
|
|
|
|
|
```c
|
|
|
|
|
#include<src1.c>
|
|
|
|
|
#include<src2.c>
|
|
|
|
|
#include<src3.c>
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This is then compiled rather than the individual files. The exact
|
|
|
|
|
speedup depends on the code base, of course, but it is not uncommon to
|
|
|
|
|
obtain more than 50% speedup in compile times. This happens even
|
|
|
|
|
though the Unity build uses only one CPU whereas individual compiles
|
|
|
|
|
can be run in parallel. Unity builds can also lead to faster code,
|
|
|
|
|
because the compiler can do more aggressive optimizations (e.g.
|
|
|
|
|
inlining).
|
|
|
|
|
|
|
|
|
|
The downside is that incremental builds are as slow as full rebuilds
|
|
|
|
|
(because that is what they are). Unity compiles also use more memory,
|
|
|
|
|
which may become an issue in certain scenarios. There may also be some
|
|
|
|
|
bugs in the source that need to be fixed before Unity compiles work.
|
|
|
|
|
As an example, if both `src1.c` and `src2.c` contain a static function
|
|
|
|
|
or variable of the same name, there will be a clash.
|
|
|
|
|
|
|
|
|
|
Meson has built-in support for unity builds. To enable them, just pass
|
|
|
|
|
`--unity on` on the command line or enable unity builds in you project
|
|
|
|
|
default_options.
|
|
|
|
|
No code changes are necessary apart from the potential clash issue
|
|
|
|
|
discussed above. Meson will automatically generate all the necessary
|
|
|
|
|
inclusion files for you.
|
|
|
|
|
|
|
|
|
|
You may modify unity settings for a given build target using
|
|
|
|
|
the `override_options` parameter. This may be useful when a build
|
|
|
|
|
target is not compatible with unity build.
|
|
|
|
|
|
|
|
|
|
The `unity` option can also have the value `subprojects`, to build
|
|
|
|
|
subprojects with unity, while building the main project incrementally.
|
|
|
|
|
|
|
|
|
|
The `unity_size` option allows to specify the number of source files
|
|
|
|
|
included per unity file. The default is 4. Having more source files
|
|
|
|
|
per unity file will speed up full builds, but slow down incremental
|
|
|
|
|
builds. To get only one unity file per build target, you can use
|
|
|
|
|
a very big number for `unity_size`.
|
