docs: Howto exclude file from unity build

Adds a howto section describing how to put files in a separate build
target and override the unity build setting, and why you might want to
do this.

Closes: #13031

1 files changed, 21 insertions, 0 deletions

diff --git a/docs/markdown/howtox.md b/docs/markdown/howtox.md
index 8b56c807e..4a57e8569 100644
--- a/docs/markdown/howtox.md
+++ b/docs/markdown/howtox.md
@@ -323,3 +323,24 @@ executable(
   deps : [my_dep]
 )
 ```
+
+## Exclude a file from unity builds
+
+If your project supports unity builds, you should fix any bugs that crop up when
+source files are concatenated together.
+Sometimes this isn't possible, though, for example if the source files are
+generated.
+
+In this case, you can put them in a separate static library build target and
+override the unity setting.
+
+```meson
+generated_files = ...
+unityproof_lib = static_library('unityproof', generated_files,
+  override_options : ['unity=off'])
+
+main_exe = executable('main', main_sources, link_with : unityproof_lib)
+```
+
+To link the static library into another library target, you may need to use
+`link_whole` instead of `link_with`.