From f07a845676ffb70015c2c1e61677ee0116e2b6a1 Mon Sep 17 00:00:00 2001 From: Jason Volk Date: Thu, 13 Sep 2018 23:43:54 -0700 Subject: [PATCH] README: Move the build addendum to a separate doc file. --- README.md | 77 ++-------------------------------------------------- doc/BUILD.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 75 insertions(+), 75 deletions(-) create mode 100644 doc/BUILD.md diff --git a/README.md b/README.md index 4d02ffa10..a11ab428a 100644 --- a/README.md +++ b/README.md @@ -112,6 +112,8 @@ make sudo make install ``` +Additional documentation for building can be found in [doc/BUILD.md](doc/BUILD.md) + ### BUILD (standalone) *Intended to allow building with dependencies that have not made their way @@ -195,81 +197,6 @@ to point at Riot's `webapp/` directory by entering the following: 6. Browse to `https://host.tld:8448/` and register a user. -## Addendum - -#### Additional build options - -Development builds should follow the same instructions as the standalone -section above while taking note of the following `./configure` 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. - - -##### Release modes (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. - -``` ---enable-generic -``` -Sets `-mtune=generic` as `native` is otherwise the default. - - -##### 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. - - -##### 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. - - ## Developers diff --git a/doc/BUILD.md b/doc/BUILD.md new file mode 100644 index 000000000..80b1b368a --- /dev/null +++ b/doc/BUILD.md @@ -0,0 +1,73 @@ +## Installation Addendum + +#### Additional build options + +Development builds should follow the same instructions as the standalone +section above while taking note of the following `./configure` 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. + + +##### Release modes (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. + +``` +--enable-generic +``` +Sets `-mtune=generic` as `native` is otherwise the default. + + +##### 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. + + +##### 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.