docs: Add build-errors.md

Since ImGui/cimgui keep breaking their APIs and introducing errors, add
a document explaining it as the most common cause.

Signed-off-by: Alexander Shishkin <[email protected]>

Author: virtuoso

CONTRIBUTING.md

@@ -7,6 +7,7 @@ You contributions are welcome and appreciated! This document is here to help wit
   - [But C?](#but-c)
   - [Code layout](#code-layout)
   - [More specifically](#more-specifically)
+- [I get build errors](#i-get-build-errors)
 - [Coding style](#coding-style)
 - [Pull requests](#pull-requests)
 
@@ -67,6 +68,10 @@ A short tour of core/:
 
 Another useful tool is git grep. Also, build configurations generate compile_commands.json that can be plugged into your favorite IDE. Having done that, you'll be able to inspect the code much more efficiently.
 
+## I get build errors
+
+If you're suddenly getting build errors, [check here](https://github.com/virtuoso/clap/tree/main/docs/build-errors.md). Otherwise, [report an issue](https://github.com/virtuoso/clap/issues/new) and/or send a pull request.
+
 ## Coding style
 
 There's a .clang-format file at the top, unfortunately, as of this writing clang-format still isn't quite able to align pointers on the right the way that it's done in the code, so either fix up after it or just format the code by hand.

README.md

@@ -20,6 +20,7 @@
   - [Run local web server](#run-local-web-server)
 - [Windows build](#windows-build)
 - [Build using cmake presets](#build-using-cmake-presets)
+- [Build errors](https://github.com/virtuoso/clap/tree/main/docs/build-errors.md)
 - [What to do with all this](#what-to-do-with-all-this)
 
 ## Live demos

docs/build-errors.md

@@ -0,0 +1,28 @@
+# Build Errors
+
+If after updating from the `main` branch you suddenly start getting build errors
+and Github runners built the same code successfully (which should always be the
+case), they are probably coming from ImGui API mismatch between your local copy
+and ImGui and/or cimgui upstream. They usually look something like this:
+```
+core/pipeline-debug.c:222:49: error: too few arguments to function call, expected 6, have 4
+  221 |             igImage((ImTextureID)texture_id(pass_tex), (ImVec2){512, 512 * aspect},
+      |             ~~~~~~~
+  222 |                     (ImVec2){1,1}, (ImVec2){0,0});
+      |                                                 ^
+```
+or
+```
+core/ui-imgui.c:23:26: error: use of undeclared identifier 'igGetIO_ContextPtr'
+   23 |     struct ImGuiIO *io = igGetIO_ContextPtr(ctx);
+      |                          ^
+```
+
+You may think that removing the local build directory is the solution, but actually
+you need to remove `deps/.bootstrap.json`:
+```sh
+rm deps/.bootstrap.json
+```
+
+and configure again with `./configure.sh` or `cmake --preset=emtest` or suchlike. The
+build directory can stay.