Add build failure notes to the build document (#1582)

Thanks to @eli-schwartz for the explanation and
suggestion as to how subpackages can get out of
date, and how to update them.

1 files changed, 23 insertions, 0 deletions

diff --git a/BUILD.md b/BUILD.md
index 1f044f047..be43e66d9 100644
--- a/BUILD.md
+++ b/BUILD.md
@@ -124,6 +124,29 @@ Options can be passed to the `meson setup` command using `-Doption=value`
 notation or using comma-separated notation (ie: `-Doption=value1,value2,value3`)
 when the option supports multiple values.
 
+### If your build fails
+
+1. Check if the `main` branch is also experiencing build failures
+   [on GitHub](https://github.com/dosbox-staging/dosbox-staging/actions?query=event%3Apush+is%3Acompleted+branch%3Amain).
+   If so, the maintenance team is aware of it and is working on it.
+
+2. Double-check that all your dependencies are installed. Read the
+   platform-specific documents above if needed.
+
+3. If the build fails with errors from the compiler (gcc/clang/msvc)
+   or linker, then please open a new issue.
+
+4. If Meson reports a problem with a subpackage, try resetting it
+   with `meson subprojects update --reset name-of-subpackage`. For example,
+   to reset FluidSynth: `meson subprojects update --reset fluidsynth`.
+
+5. If that doesn't help, try resetting your build area with:
+
+    ``` shell
+    git checkout -f main
+    git pull
+    git clean -fdx
+    ```
 
 ### Run unit tests