improve documentation on building

1 files changed, 29 insertions, 4 deletions

diff --git a/Documentation/building.md b/Documentation/building.md
index 3e6c819..50ce328 100644
--- a/Documentation/building.md
+++ b/Documentation/building.md
@@ -3,7 +3,7 @@ A complete build of flow involves two parts
 
 1. Building Scala sources (the front-end), resulting in a platform independent artifact (i.e. a jar file).
 
-2. Building C sources (the back-end), yielding a native library that may only be used on systems resembling the platform for which it was compiled
+2. Building C sources (the back-end), yielding a native library that may only be used on systems resembling the platform for which it was compiled.
 
 Both steps are independent, their only interaction being a header file generated by the JDK utility `javah` (see `sbt javah` for details), and may therefore be built in any order.
 
@@ -13,13 +13,38 @@ Run `sbt flow-main/packageBin` in the base directory. This simply compiles Scala
 ## Building Native Sources
 The back-end is managed by GNU Autotools and all relevant files are contained in `flow-native`.
 
+---
+
+### Aside: Autotools Introduction
+Autotools is a suite of programs constituting a sort of "meta-build system". It is used to generate a platform-independent build script known as `./configure`, which, when run, will analyze the current system (search for a C compiler, required libraries etc) and produce a `Makefile`. The makefile in turn is system-specific and can be used to create the final binary. In summary the build process is as follows:
+
+1. Autotools (specifically the program `autoreconf`) generates `./configure`, this happens on the developer's machine
+2. `./configure` is run on the host computer
+3. `make` is run to produce a binary, also on the host computer
+
+In a typical, source-controlled repository, only a bootstrapping script that calls Autotools is checked into version control. However, source *releases* include the generated `./configure` script. An end-user then downloads a source release and only has to run `./configure && make`.
+
+However, since flow does currently not provide source releases (not to be confused with source repository or Git tags), the developer's machine is the same as the host machine and so the bootstrapping process always needs to be performed.
+
+---
+
+### Build Process
+
 Several steps are involved in producing the native library:
 
-1. When compiling for the first time, initialize Autotools by running the script `./bootstrap`.
+1. Bootstrap the build (run this once, if `./configure` does not exist).
+
+    1. Check availability of dependencies: autotools and libtool (on Debian-based systems run `apt-get install build-essential autoconf automake libtool`)
+    2. Run `./bootstrap`
+
+2. Compile
+   
+   1. Check availability of dependencies: C compiler and JDK
+   2. Run `./configure && make`
 
-2. Once initialized, `./configure && make` will build the back-end.
+3. Install
 
-3. The native library is now ready and can be:
+    The native library is now ready and can be:
 
 	- copied to a local directory: `DESTDIR=$(pwd)/<directory> make install`