From 3efe4777760b0ce45cfe93e666bf355381a944db Mon Sep 17 00:00:00 2001
From: Aqua-sama <aqua@iserlohn-fortress.net>
Date: Sun, 15 Jul 2018 12:33:53 +0200
Subject: Update Building.md

---
 BUILDING.md | 89 ++++++++++++++++++++++++++++++++++---------------------------
 1 file changed, 50 insertions(+), 39 deletions(-)

(limited to 'BUILDING.md')

diff --git a/BUILDING.md b/BUILDING.md
index 64bcd1e..50ca3ea 100644
--- a/BUILDING.md
+++ b/BUILDING.md
@@ -1,59 +1,52 @@
-## Before you start
+## Requirements
 
-### [Qt](https://www.qt.io/)
-Minimal required version is 5.10.
+### [Qt](https://www.qt.io/) 5.11
 
-An up-to-date version of QtWebEngine is highly recommended due to fixes to Blink
-that do _not_ get backported. QtWebEngine can be built with older versions of
-Qt, so consider building it if you use the LTS Qt release.
+Even though most of the browser might work with the last LTS Qt release, always
+use an up-to-date version of QtWebEngine. Security fixes to Blink do _not_ get
+backported. QtWebEngine can be built with older versions of Qt, if upgrading Qt
+is not a possibility.
 
-### [boost](http://www.boost.org/)
-Required component: program_options, string algorithms
+### [boost](http://www.boost.org/) program_options
 
-### cmake and a build tool
-Minimal version 3.1.0, only 3.10+ is tested; your build tool of choice (make,
-ninja, etc.)
+### cmake 3.10
 
-### A preferably working compiler with C++17 support
- - gcc 7 or later
- - clang 4 or later
- - only MSVC is supported on Windows due to QtWebEngine
+### Compiler with C++17 support
+ - gcc 7+;  clang 4+
+ - Windows: only MSVC is supported due to QtWebEngine
 
-## Compiling
-smolbote follows the generic cmake build template:
+## Basic Installation
+In short, the generic cmake build loop of 'cmake, make, make install' will
+generate a makefile, build the program and install it.
 
 ~~~ sh
-# 1. Clone the repository
+# clone the repository
 hg clone https://neueland.iserlohn-fortress.net/smolbote.hg
 
-# (optional) you can also get checksums for some commits
-# get node for the current commit
-hg log -r tip --template='{node}'
-# get sha512 checksums and signature
-curl -O https://neueland.iserlohn-fortress.net/smolbote/integrity/$node
-curl -O https://neueland.iserlohn-fortress.net/smolbote/integrity/$node.sig
-# verify signature and files
-gpg --verify $node.sig
-sha512sum --check --quiet $node
+# generate makefile
+mkdir build && cd build
+cmake -DCMAKE_CXX_FLAGS="-O2 [other cxx flags]" -DCMAKE_BUILD_TYPE=Release ../smolbote.hg
 
-# 2. Generate Makefile
-mkdir path/to/build && cd path/to/build
-cmake -DCMAKE_BUILD_TYPE=Release path/to/smolbote.hg
-
-# 3. Build
-make -j 4
-
-# 4. Install
+# make && make install
+make -j4
 make install
 ~~~
 
+### -DCMAKE_CXX_FLAGS
+cmake does not set any C++ flags by default, including no optimization flags.
+You need to set these yourself if your build system doesn't set any either.
+
+On gcc/clang, no optimize flags are set by default, resulting in rather bloated
+code being generated. Recommend setting at least -O2. MSVC has optimze flags
+set by default.
+
 ### -DCMAKE_BUILD_TYPE
-Controls what flags and optimizations are set. Possible values: Debug, Release,
-RelWithDebInfo, MinSizeRel
+Install paths are only set on Release builds.
 
 ### -DCMAKE_INSTALL_PREFIX
-Sets the install location. Binaries will be written to bin/, and plugins to
-lib/smolbote/.
+Sets the install location prefix.
+win32: Binary is written to bin/, and plugins to bin/plugins.
+others: Binary will be written to bin/, and plugins to lib/smolbote/.
 
 ### Using libc++
 You can use libc++ over stdlibc++ by setting UseLibCpp to On. Requires clang.
@@ -61,3 +54,21 @@ You can use libc++ over stdlibc++ by setting UseLibCpp to On. Requires clang.
 ~~~ sh
 -DCMAKE_CXX_COMPILER=/usr/bin/clang++ -DUseLibCpp=On
 ~~~
+
+### Verifying source code integrity
+Since mercurial doesn't have any method for signing commits, some commits have
+signed sha512 checksums available.
+
+~~~ sh
+# get node for the current commit
+node="$(hg log -r tip --template='{node}')"
+
+# get sha512 checksums and signature
+curl -O https://neueland.iserlohn-fortress.net/smolbote/integrity/$node
+curl -O https://neueland.iserlohn-fortress.net/smolbote/integrity/$node.sig
+
+# verify signature and files
+gpg --verify $node.sig
+sha512sum --check --quiet $node
+~~~
+
-- 
cgit v1.2.1