construct/doc/BUILD.md

## 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:

- Boost: The required version is available through `apt` as `libboost-all-dev` on
Ubuntu Cosmic (18.10). All earlier releases (including 18.04 LTS) can configure
with `--with-included-boost` as instructed below.

- RocksDB: The required version is available through `apt` as `librocksdb-dev` on
Ubuntu Disco (19.04). All earlier releases (including 18.04 LTS) can configure
with `--with-included-rocksdb` and skip the next bullet.

- RocksDB: THE COMPLETE SOURCE-CODE OF ROCKSDB MUST BE AVAILABLE TO BUILD CONSTRUCT.
This is different from the `include/` and `lib/` files installed by `librocksdb-dev`
with 19.04 or later (which is also required). If you are on 19.04, 19.10, or 20.04
or later, provide the source-code with the following:
```
git submodule update --init deps/rocksdb
cd deps/rocksdb
git fetch --tags --force
git checkout v5.17.2
```

##### 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
./configure --prefix=$PWD/build
make install
```

> The `--with-included-*` will fetch, configure **and build** the dependencies included
as submodules. The result will not be installable on the system without this repository
remaining intact. Please read the compatibility primer first to understand which options
you need or don't need on your system.


### Additional build options

#### 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. No
sanitizer instrumentation is generated by default in this mode.


#### Generic mode binary (for distribution packages)

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
```
Sets `-mtune=generic` as `native` is otherwise the default.


#### Compact mode (experimental)

```
--enable-compact
```
Create the smallest possible resulting output. This will optimize for size
(if optimization is enabled), remove all debugging, strip symbols, and apply
any toolchain-feature or #ifdef in code that optimizes the output size.

_This feature is experimental. It may not build or execute on all platforms
reliably. Please report bugs._


#### Manually enable assertions

```
--enable-assert
```
Implied by `--enable-debug`. This is useful to specifically enable `assert()`
statements when `--enable-debug` is not used.

```
--with-assert=trap
```
Recommended when using `--enable-assert` for debugging. This replaces the
default mechanism of assertion with traps rather than aborts; allowing
developers to explore an unterminated program.

#### Manually enable optimization

```
--enable-optimize
```
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-malloc-libs
```
`./configure` will detect alternative `malloc()` implementations found in
libraries installed on the system (jemalloc/tcmalloc/etc). Construct developers
may enable these to be configured by default, if detected. To always prevent
any alternative to the default standard library allocator specify this option.


#### 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=
```
This manually sets the level of logging. All log levels at or below this level
will be available. When a log level is not available, all code used to generate
its messages will be entirely eliminated via *dead-code-elimination* at compile
time.

The log levels are (from logger.h):
```
7  DEBUG      Maximum verbosity for developers.
6  DWARNING   A warning but only for developers (more frequent than WARNING).
5  DERROR     An error but only worthy of developers (more frequent than ERROR).
4  INFO       A more frequent message with good news.
3  NOTICE     An infrequent important message with neutral or positive news.
2  WARNING    Non-impacting undesirable behavior user should know about.
1  ERROR      Things that shouldn't happen; user impacted and should know.
0  CRITICAL   Catastrophic/unrecoverable; program is in a compromised state.
```

When `--enable-debug` is used `--with-log-level=DEBUG` is implied. Otherwise
for release mode `--with-log-level=INFO` is implied. Large deployments with
many users may consider lower than `INFO` to maximize optimization and reduce
noise.