Debian Codegraph @

subprojects/meson-docs/docs/markdown/Unity-builds.md

raw
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`.