Documentation: Update build system documentation

doc/build_system.md

@@ -24,11 +24,15 @@ Provided aliases:
 
 ## setup_project
 
-Cleans the project and its dependencies first, ensuring the project is in
+Cleans the project and its dependencies first (see below), ensuring
-a known state, then downloads and extracts dependencies.
+the project is in a known state, then sets up dependencies.
 
-This will probably do more in the future (for example compile dependencies
+This includes downloading (and caching) of files that are not yet
-that need to be compiled).
+locally cached and compiling dependencies that need to be compiled.
+
+This script’s intended purpose is setting up a development environment but
+it can also be used to update the locally set-up dependencies to the ones
+that the project is using.
 
 
 # build
@@ -55,14 +59,20 @@ Accepted environment variables:
 - `CXX`: override the default compiler
 - `CXXFLAGS`: override the default compiler flags, must at least specify
    the C++ version
+- `SINGLE`: if set to `yes`, causes the test script to compile the tests in
+   single-threaded mode¹
+
+¹Unit tests are always run one after the other.
 
 
 # clean
 
-Removes and re-creates `bin/`. Also removes the endianness header and
+Removes and re-creates `bin/` and `include/`, then re-creates symlinks to
-the endianness check binary.
+shared object and header files as needed for the build process.
+Also removes the endianness header and the endianness check binary.
 
 
 # clean_dependencies
 
-Removes and re-creates `dependencies/`.
+Removes and re-creates `dependencies/` and prunes the download cache of files
+that either have been corrupted or are no longer used.