From e91416ad6fa4c59df1210f5c3a3afaf739c68433 Mon Sep 17 00:00:00 2001
From: Jason Volk <jasonzemos@gmail.com>
Date: Fri, 28 Aug 2020 00:09:28 -0700
Subject: [PATCH] Updated BUILD (markdown)

---
 BUILD.md | 27 ++++++++++++++++++++++-----
 1 file changed, 22 insertions(+), 5 deletions(-)

diff --git a/BUILD.md b/BUILD.md
index 06aa293..bc298a2 100644
--- a/BUILD.md
+++ b/BUILD.md
@@ -1,4 +1,4 @@
-## BUILD (standalone)
+# BUILD
 
 ##### Compatibility Primer
 
@@ -44,7 +44,7 @@ especially for development. Example `--prefix=~/.local/`.
 
 > ❗ Do not set your `--prefix` path to a directory inside your git repository or an invocation of `git clean` will erase your database in $prefix/var/db/.
 
-#### STANDALONE BUILD PROCEDURE
+### 🟢 STANDALONE BUILD PROCEDURE
 
 ```
 ./autogen.sh
@@ -57,8 +57,9 @@ as submodules. The result will not be installable on the system without this rep
 remaining intact. Please read the compatibility primer first to understand which options
 you need or don't need on your system.
 
-##### Re-building
-When you want to recompile and your system had changes (upgraded libs, compiler, switching between clang and gcc, etc.) you are advised to start from a clean state:
+##### REBUILDING FOR UPDATES
+
+Until [#84](https://github.com/matrix-construct/construct/issues/84) is resolved, updates to the repository (from e.g. `git pull`) or the system may cause complications with incremental builds using `make(1)`. For this reason we advise a "from scratch" build preceded by an invocation of `git clean`; example:
 
 ```
 git reset --hard  &&  git clean -f -x -d
@@ -66,7 +67,23 @@ git reset --hard  &&  git clean -f -x -d
 ./configure --prefix=...
 ```
 
-### Additional build options
+#### DEVELOPMENT BUILDS
+
+Those wishing to contribute new functionality or diagnose difficult bugs will benefit from several configuration options. This configuration generates a significant amount of additional code and instrumentation, in addition to full debug logging. The server may consume additional CPU and memory resources.
+
+> Until the resolution of [#84](https://github.com/matrix-construct/construct/issues/84) it is advised to sterilize the build environment before any re-`./configure`.
+
+> All `--with-included-` and other platform-specific build options remain the same and must be applied to these recipes.
+
+```
+./configure --prefix=... --enable-debug --enable-optimize --with-assert=trap --disable-lto
+```
+- Release optimization is always enabled; we only advise the removal of `--enable-optimize` when it is necessary to diagnose specific difficult issues.
+- It is much easier to debug, step, and fiddle with a live program rather than a dead one. `--with-assert=trap` gives the developer a choice to note the issue and continue the program at their discretion (If you aren't sure about an assert: terminate immediately!).
+- Disabling LTO is advised to reduce significant delays during the linking phase of every `make` during development.
+
+
+## Additional Build Options
 
 #### Debug mode