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