Documentation updates (#882)

Restructured the docs folder in preparation for more docs. Improved the contents a bit.

1 files changed, 54 insertions, 0 deletions

diff --git a/docs/dev/xmake.md b/docs/dev/xmake.md
new file mode 100644
index 000000000..a529107b8
--- /dev/null
+++ b/docs/dev/xmake.md
@@ -0,0 +1,54 @@
+# xmake notes and tips and tricks
+
+We use xmake to build code in this tree. We also use xmake to handle some of our third-party dependencies which are
+not in the tree.
+
+This document is intended as a basic guide on how to accomplish some common things when working with the Zen codebase.
+
+The official documentation for xmake is located here: https://xmake.io/ it covers most features but isn't
+necessarily rich in examples on how to accomplish things on different platforms and environments.
+
+# Build basics
+
+xmake is what I'd call a "stateful" build system in that there is a 'configuration' step which you
+will generally want to run before actually building the code. This allows you to specify which
+mode you want to build (in our case, "debug" or "release"), and also allows you to perform additional
+configuration of options such as whether we should include support for Sentry crash reporting, use 
+of 'mimalloc' for memory allocations etc etc
+
+Configure xmake for building 'debug' (which includes building all third-party packages) and 
+triggering a build, issue these commands in the shell:
+
+```
+dev/zen> xmake config --mode=debug
+dev/zen> xmake
+```
+
+If all goes well, you will be able to run the compiled programs using:
+
+```
+dev/zen> xmake run zenserver
+dev/zen> xmake run zen
+```
+
+# Cleaning out *all* build state
+
+You may run into build issues at some point due to bad on-disk state. For instance your workstation
+could crash at an inopportune moment leaving things in an inconsistent state, or you may run into bugs
+in compilers or the build system itself.
+
+When faced with this it's good to be able to wipe out all state which influences the build. Since xmake
+uses a number of different locations to store state it's not entirely obvious at first how to accomplish 
+this.
+
+## Windows
+
+```
+dev\zen> rmdir /s /q .xmake build %LOCALAPPDATA%\.xmake %TEMP%\.xmake
+```
+
+## Linux / MacOS
+
+```
+dev/zen> rm -rf .xmake build ~/.xmake
+```