meson/docs/markdown/Unity-builds.md

---
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 with the GUI.
No code changes are necessary apart from the potential clash issue
discussed above. Meson will automatically generate all the necessary
inclusion files for you.