1 files changed, 39 insertions, 0 deletions
diff --git a/meson/docs/markdown/Unity-builds.md b/meson/docs/markdown/Unity-builds.md
new file mode 100644
index 000000000..833383d88
--- /dev/null
+++ b/meson/docs/markdown/Unity-builds.md
@@ -0,0 +1,39 @@
+---
+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.