[vala/0.40] docs: Update build instructions and move them to README.md

[Rico Tzschichholz <ricotz src gnome org>]

commit c90d49e0e2962bdcc7ef1c3c6d81a76e574c8795
Author: Alistair Thomas <astavale yahoo co uk>
Date:   Mon Nov 19 23:01:53 2018 +0000

    docs: Update build instructions and move them to README.md
    
    Updates the links for building Vala and how to bootstrap the build

 README.md        | 113 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/building.txt |  47 -----------------------
 2 files changed, 113 insertions(+), 47 deletions(-)
---
diff --git a/README.md b/README.md
index bab55640f..1c3b206e3 100644
--- a/README.md
+++ b/README.md
@@ -38,3 +38,116 @@ written in e.g. C# as the Vala parser is written as a library, so that
 all compile-time information is available when generating a binding.
 
 More information about Vala is available at 
[https://wiki.gnome.org/Projects/Vala/](https://wiki.gnome.org/Projects/Vala/)
+
+
+## Building Vala
+Instructions on how to build the latest version of Vala.
+These can be modified to build a specific release.
+
+### Step One:
+Install the following packages:
+
+ * a C compiler, e.g. GCC
+ * a C library, e.g. glibc
+ * glib (>= 2.40)
+ * flex
+ * bison
+ * Graphviz (libgvc) (>= 2.16) to build valadoc
+ * make
+ * autoconf
+ * automake
+ * libtool
+
+
+### Step Two:
+Decide where the Vala compiler is to be found.
+
+Vala is self-hosting so it needs another Vala compiler to compile
+itself.  `valac` is the name of the executable and can be:
+
+ * installed from an existing package
+ * built from a source tarball
+ * built from the [Vala bootstrap module](https://gitlab.gnome.org/Archive/vala-bootstrap)
+
+If you have an existing `valac` installed then move on to step three.
+
+If you don't have an existing version of Vala installed (i.e. because you're
+bootstrapping or cross-compiling) then a source tarball or the vala-bootstrap
+module contain pre-compiled C files from the Vala sources. These can be used
+to bootstrap `valac`.
+
+Source tarballs can be downloaded via:
+
+https://wiki.gnome.org/Projects/Vala/Release
+
+or the vala-bootstrap module is available at:
+
+https://gitlab.gnome.org/Archive/vala-bootstrap
+
+
+Here is an example on how to download and compile from a Vala release tarball.
+In this example it is release version 0.42.3:
+
+```sh
+curl --silent --show-error --location https://download.gnome.org/sources/vala/0.40/vala-0.40.11.tar.xz 
--output vala-bootstrap.tar.xz
+tar --extract --file vala-bootstrap.tar.xz
+cd vala-bootstrap
+./configure --prefix=/opt/vala-bootstrap
+make && sudo make install
+```
+
+The configure script will check if `valac` can be found in PATH. If not then
+`valac` is bootstrapped from the C source files in the tarball.
+If you do not wish to install the bootstrapped version of `valac` it can be
+found in `vala-bootstrap/compiler/valac` This is a libtool wrapper script
+that makes the libraries in the build directory work together.
+
+
+An example of downloading and compiling from the bootstrap module:
+
+```sh
+git clone https://gitlab.gnome.org/Archive/vala-bootstrap
+cd vala-bootstrap
+touch */*.stamp
+VALAC=/no-valac ./configure --prefix=/opt/vala-bootstrap
+make && sudo make install
+```
+
+### Step Three:
+Compiling the newest Vala from the repository using a pre-installed `valac`:
+
+```sh
+git clone https://gitlab.gnome.org/GNOME/vala
+cd vala
+./autogen.sh
+make && sudo make install
+```
+
+To use `valac` from a bootstrapped build detailed in step two use:
+
+```sh
+git clone https://gitlab.gnome.org/GNOME/vala
+cd vala
+VALAC=/opt/vala-bootstrap/bin/vala ./autogen.sh
+make && sudo make install
+```
+
+### Compiling Different Vala Versions
+Maybe you now want to compile Vala with the new version you have just installed.
+Then you simply clean the version files and start the build. Be warned that
+`git clean -dfx` **will remove all untracked files** from the source tree:
+
+```sh
+git clean -dfx
+./autogen.sh
+make && sudo make install
+```
+
+If you wish to build a specific release, for example 0.40.11:
+
+```sh
+git checkout 0.40.11
+git clean -dfx
+./autogen.sh
+make && sudo make install
+```