From 9972d58b29528cef858bd21f370d8c74f10ce171 Mon Sep 17 00:00:00 2001
From: Jason Volk <jason@zemos.net>
Date: Sat, 20 Jul 2019 13:47:10 -0700
Subject: [PATCH] doc: Improve build addendum.

---
 doc/BUILD.md | 88 +++++++++++++++++++++++++++++-----------------------
 1 file changed, 49 insertions(+), 39 deletions(-)

diff --git a/doc/BUILD.md b/doc/BUILD.md
index 1b87feef0..d5ff1a9ec 100644
--- a/doc/BUILD.md
+++ b/doc/BUILD.md
@@ -1,15 +1,6 @@
-## BUILD
+## BUILD (standalone)
 
-*Most users will need to follow the standalone build instructions in the next section.*
-
-```
-./autogen.sh
-./configure
-make
-sudo make install
-```
-
-### BUILD (standalone)
+##### Compatibility Primer
 
 This section is intended to allow building with dependencies that have not
 made their way to mainstream systems. Important notes that may affect you:
@@ -29,50 +20,55 @@ with `--with-included-rocksdb` as instructed below.~~
 configure with `--with-included-rocksdb` until regressions in your RocksDB
 package have been fixed.
 
+##### Installation Primer
+
+A general overview of what construct will build and install is given here. At
+this time it is suggested to supply `./configure` with a `--prefix` path,
+especially for development. Example `--prefix=~/.local/`.
+
+- Binary executable `$prefix/bin/construct`
+- Shared library `$prefix/lib/libircd.so`
+- Shared library modules `$prefix/lib/modules/construct/*.so`
+- Header files `$prefix/include/ircd/*`
+- Read-only shared assets `$prefix/share/construct/*`
+- Database directory may be established at `$prefix/var/db/construct/`
+
+```
+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
 
 ```
 ./autogen.sh
-mkdir build
-```
-
-> The install directory may be this or another place of your choosing. If you decide
-elsewhere, make sure to change the `--prefix` in the `./configure` statement below.
-
-```
 ./configure --prefix=$PWD/build --with-included-boost --with-included-rocksdb
-```
-
-> The `--with-included-*` will fetch, configure **and build** the dependencies included
-as submodules.
-
-```
 make install
 ```
 
-## Installation Addendum
+> The `--with-included-*` will fetch, configure **and build** the dependencies included
+as submodules. Please read the compatibility primer first to understand which options
+you need or don't need on your system.
 
-#### Additional build options
 
-Development builds should follow the same instructions as the standalone
-section above while taking note of the following `./configure` options:
+### Additional build options
 
-##### Debug mode
+#### Debug mode
 
 ```
 --enable-debug
 ```
 Full debug mode. Includes additional code within `#ifdef RB_DEBUG` sections.
 Optimization level is `-Og`, which is still valgrind-worthy. Debugger support
-is `-ggdb`. Log level is `DEBUG` (maximum). Assertions are enabled.
+is `-ggdb`. Log level is `DEBUG` (maximum). Assertions are enabled. No
+sanitizer instrumentation is generated by default in this mode.
 
 
-##### Release modes (for distribution packages)
+#### Generic mode binary (for distribution packages)
 
-Options in this section may help distribution maintainers create packages.
-Users building for themselves (whether standalone or fully installed) probably
-don't need anything here.
+Construct developers have set the default compilation to generate native
+hardware operations which may only be supported on very specific targets. For
+a generic mode binary, package maintainers may require this option.
 
 ```
 --enable-generic
@@ -80,7 +76,7 @@ don't need anything here.
 Sets `-mtune=generic` as `native` is otherwise the default.
 
 
-##### Compact mode
+#### Compact mode (experimental)
 
 ```
 --enable-compact
@@ -93,7 +89,7 @@ _This feature is experimental. It may not build or execute on all platforms
 reliably. Please report bugs._
 
 
-##### Manually enable assertions
+#### Manually enable assertions
 
 ```
 --enable-assert
@@ -102,7 +98,7 @@ Implied by `--enable-debug`. This is useful to specifically enable `assert()`
 statements when `--enable-debug` is not used.
 
 
-##### Manually enable optimization
+#### Manually enable optimization
 
 ```
 --enable-optimize
@@ -111,7 +107,7 @@ This manually applies full release-mode optimizations even when using
 `--enable-debug`. Implied when not in debug mode.
 
 
-##### Disable third-party dynamic allocator libraries
+#### Disable third-party dynamic allocator libraries
 
 ```
 --disable-malloc-libs
@@ -122,7 +118,21 @@ may enable these to be configured by default, if detected. To always prevent
 any alternative to the default standard library allocator specify this option.
 
 
-##### Logging level
+#### Enable third-party dynamic allocator libraries
+
+Currently:
+
+```
+--enable-jemalloc
+```
+
+`./configure` will detect alternative `malloc()` implementations found in
+libraries installed on the system (jemalloc/tcmalloc/etc). Construct developers
+may not enable these to be configured by default, falling back on the default
+allocator. To always use one of the alternative allocators use one option here.
+
+
+#### Logging level
 
 ```
 --with-log-level=