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:

• GCC: Ubuntu Xenial (16.04) users must use a PPA to obtain GCC-7 or greater; don't forget to export CXX=g++-7 before running ./configure on that system.

• 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 as instructed below.

• RocksDB: At this time we advise all users including those on 19.04 to 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
./configure --prefix=$PWD/build --with-included-boost --with-included-rocksdb
make install

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

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.

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.