[doc] Update section 'Getting GHDL' (#906)

* doc: fix version extraction from 'configure'

* doc: update section 'Getting GHDL'

* readme: update

7 files changed, 754 insertions, 54 deletions

diff --git a/doc/getting/Directories.rst b/doc/getting/Directories.rst
new file mode 100644
index 000000000..2d5b575d8
--- /dev/null
+++ b/doc/getting/Directories.rst
@@ -0,0 +1,50 @@
+.. _BUILD:dir_structure:
+
+Directory structure
+###################
+
+* ``src``: sources of GHDL, all of them in Ada.
+
+* ``libraries``: mostly third party libraries such as, `ieee`, `mentor`,
+  `std`, `synopsys` and `vital`. Except for a few shell and `Python` scripts, all
+  the content is written in VHDL.
+
+  * Vendors like Altera, Lattice and Xilinx have their own simulation libraries,
+    especially for FPGA primitives, soft and hard macros. These libraries cannot
+    be shipped with GHDL, but we offer prepared compile scripts to
+    pre-compile the vendor libraries, if the vendor tool is present on the
+    computer. These are located in ``libraries/vendor``.
+    See :ref:`GETTING:PrecompVendor` for information on how to
+    use them.
+
+* ``dist``: scripts and auxiliary files to build GHDL in different
+  environments:
+
+  * ``gcc``: header and configuration files to build GHDL with GCC (all
+    platforms).
+  * ``linux``: build and test script written in shell, and other auxiliary
+    files used to i) launch docker containers and ii) automate multiple builds
+    in `Travis CI <https://travis-ci.org/>`_.
+
+  * ``windows``:
+
+    * ``mcode``:
+    * ``appveyor``:
+
+* ``doc``: `Markdown` and `reStructuredText` sources and auxiliary files to
+  build the documentation with `Sphinx <http://www.sphinx-doc.org>`_. In fact,
+  `Read the Docs <http://readthedocs.org>`_ (RTD) is used to automatically build
+  and deploy this site and/or PDF you are reading.
+
+* ``testsuite``: files used for testing.
+
+* `.yml` configuration files for CI environments (``readthedocs``,
+  ``travis``, and ``appveyor``) and `ignore` files for source control
+  management tools (``git`` and ``.hg``).
+
+* Files for building GHDL: ``configure`` and ``Makefile.in``.
+
+* Auxiliary files for development: ``.gdbinit`` and ``ghdl.gpr.in``
+  (GNAT project file).
+
+* Text files: ``COPYING.md``, ``NEWS.md``, and ``README.md``.
diff --git a/doc/getting/GCC.rst b/doc/getting/GCC.rst
new file mode 100644
index 000000000..b8c46f63f
--- /dev/null
+++ b/doc/getting/GCC.rst
@@ -0,0 +1,75 @@
+.. _BUILD:gcc:
+
+GCC backend
+###########
+
+.. TODO :: Instructions to build GHDL with GCC backend on Windows are not available yet.
+
+.. rubric:: Requirements
+
+* GCC (Gnu Compiler Collection)
+* GNAT (Ada compiler for GCC)
+* GCC source files. Download and untar the sources of version 4.9.x, 5.x, 6.x or 7.x.
+
+.. HINT :: There are some dependencies for building GCC (``gmp``, ``mpfr`` and ``mpc``). If you have not installed them on your system, you can either build them manually or use the ``download_prerequisites`` script provided in the GCC source tree (recommended): ``cd /path/to/gcc/source/dir && ./contrib/download_prerequisites``.
+
+* First configure GHDL, specify GCC source directory and installation prefix (like  ``/usr/local`` or ``/opt/ghdl``).
+* Next, invoke ``make copy-sources`` to copy GHDL sources in the source directory.
+* Then, configure GCC. The list of ``--disable`` configure options can be adjusted to your needs. GHDL does not require all these optional libraries and disabling them will speed up the build.
+* Now, build and install GCC with ``make``.
+* Last, build and install GHDL libraries.
+
+.. rubric:: Example:
+
+.. code-block:: Bash
+
+ $ cd <ghdl>
+ $ mkdir build
+ $ cd build
+ $ ../configure --with-gcc=/path/to/gcc/source/dir --prefix=/usr/local
+ $ make copy-sources
+ $ mkdir gcc-objs; cd gcc-objs
+ $ /path/to/gcc/source/dir/configure --prefix=/usr/local --enable-languages=c,vhdl \
+ --disable-bootstrap --disable-lto --disable-multilib --disable-libssp \
+ --disable-libgomp --disable-libquadmath
+ $ make -j2 && make install
+ $ cd /path/to/ghdl/source/dir/build
+ $ make ghdllib
+ $ make install
+
+.. HINT :: Note that the prefix directory to configure ``gcc`` must be the same as the one used to configure GHDL. If you have manually built ``gmp``/``mpfr``/``mpc`` (without using the script in ``contrib``), and, if you have installed them in a non-standard directory, you may need to add ``--with-gmp=GMP_INSTALL_DIR``.
+
+.. HINT :: If your system gcc was configured with ``--enable-default-pie`` (check if that option appears in the output of ``gcc -v``), you should also add it.
+
+.. HINT :: If you don't want to install ``makeinfo``, do ``make install MAKEINFO=true`` instead.
+
+.. HINT :: Once GCC (with GHDL) has been built once, it is possible to work on the GHDL source tree without copying it in the GCC tree. Commands are::
+
+  $ make ghdl1-gcc           # Build the compiler
+  $ make ghdl_gcc            # Build the driver
+  $ make libs.vhdl.local_gcc # Compile the vhdl libraries
+  $ make grt-all             # Build the GHDL runtime
+  $ make install.vpi.local   # Locally install vpi files
+
+  In ``src/ortho/gcc``, create a ``Makefile.conf`` file that sets the following
+  variables:
+
+  .. CODE:: Bash
+
+    AGCC_GCCSRC_DIR=/path/to/gcc/sources
+    AGCC_GCCOBJ_DIR=/path/to/gcc/build
+
+  If your system gcc was built with ``--enable-default-pie``, add
+  ``-no-pie`` option for linking.
+
+.. HINT :: For ppc64 (and AIX ?) platform, the object file format contains an identifier for the source language. Because gcc doesn't know about VHDL, gcc crashes very early. This could be fixed with a very simple change in ``gcc/config/rs6000/rs6000.c``, ``function rs6000_output_function_epilogue`` (as of gcc 4.8):
+
+	  .. CODE:: diff
+
+ 	 	 	  || ! strcmp (language_string, "GNU GIMPLE")
+ 	 	 	  || ! strcmp (language_string, "GNU Go")
+ 	 	 	  || ! strcmp (language_string, "GNU D")
+ 	 	-	  || ! strcmp (language_string, "libgccjit"))
+ 	 	+	  || ! strcmp (language_string, "libgccjit")
+ 	 	+	  || ! strcmp (language_string, "vhdl"))
+ 	 	 	i = 0;
diff --git a/doc/getting/LLVM.rst b/doc/getting/LLVM.rst
new file mode 100644
index 000000000..9190549d2
--- /dev/null
+++ b/doc/getting/LLVM.rst
@@ -0,0 +1,43 @@
+.. _BUILD:llvm:
+
+LLVM backend
+############
+
+.. rubric:: Requirements
+
+* GCC (Gnu Compiler Collection)
+* GNAT (Ada compiler for GCC)
+* LLVM (Low-Level-Virtual Machine) and CLANG (Compiler front-end for LLVM): 3.5, 3.8, 3.9, 4.0, 5.0, 6.0, 7.0 or 8.0
+
+.. _BUILD:llvm:GNAT:
+
+GCC/GNAT: GNU/Linux or Windows (MinGW/MSYS2)
+============================================
+
+.. HINT:: You need to install LLVM (usually depends on ``libedit``, see :ghdlsharp:`29`). Debugging is only supported with LLVM 3.5.
+
+GHDL is configured by ``configure`` and built by ``make``.
+
+* First, GHDL needs to be configured. It is common to specify a ``PREFIX``
+  (installation directory like ``/usr/local`` or ``/opt/ghdl``). Set the proper
+  arg, ``./configure --with-llvm-config``, to select LLVM backend. If
+  ``llvm-config`` is not in your path, you can specify it:
+  ``./configure --with-llvm-config=LLVM_INSTALL/bin/llvm-config``.
+
+* Next, ``make`` starts the compilation process.
+
+* Finally, ``make install`` installs GHDL into the installation directory
+  specified by ``PREFIX``.
+
+.. rubric:: Example:
+
+.. code-block:: Bash
+
+   $ cd <ghdl>
+   $ mkdir build
+   $ cd build
+   $ ../configure --with-llvm-config --prefix=PREFIX
+   $ make
+   $ make install
+
+.. HINT:: If you want to have stack backtraces on errors (like assert failure or index of out bounds), you need to configure and build ``libbacktrace`` from GCC (you don't need to configure GCC). Then add the following arg to configure: ``--with-backtrace-lib=/path-to-gcc-build/libbacktrace/.libs/libbacktrace.a``
diff --git a/doc/getting/PrecompileVendorPrimitives.rst b/doc/getting/PrecompileVendorPrimitives.rst
new file mode 100644
index 000000000..714dc053d
--- /dev/null
+++ b/doc/getting/PrecompileVendorPrimitives.rst
@@ -0,0 +1,422 @@
+.. _GETTING:PrecompVendor:
+
+Precompile Vendor Primitives
+############################
+
+Vendors like Altera, Lattice and Xilinx have their own simulation libraries,
+especially for FPGA primitives, soft and hard macros. These libraries cannot
+be shipped with *GHDL*, but we offer prepared compile scripts to pre-compile
+the vendor libraries, if the vendor tool is present on the computer. There are
+also popular simulation and verification libraries like OSVVM [#f1]_ or
+UVVM [#f3]_, which can be pre-compiled, too.
+
+The compilation scripts are writen in the shell languages: *PowerShell* for
+*Windows* |trade| and *Bash* for *GNU/Linux*. The compile scripts can colorize
+the GHDL warning and error lines with the help of `grc/grcat` [#f4]_.
+
+Supported Vendors Libraries
+===========================
+
+* Altera/Intel Quartus (13.0 or later):
+
+  * `lpm`, `sgate`
+  * `altera`, `altera_mf`, `altera_lnsim`
+  * `arriaii`, `arriaii_pcie_hip`, `arriaiigz`
+  * `arriav`, `arriavgz`, `arriavgz_pcie_hip`
+  * `cycloneiv`, `cycloneiv_pcie_hip`, `cycloneive`
+  * `cyclonev`
+  * `max`, `maxii`, `maxv`
+  * `stratixiv`, `stratixiv_pcie_hip`
+  * `stratixv`, `stratixv_pcie_hip`
+  * `fiftyfivenm`, `twentynm`
+
+* Lattice (3.6 or later):
+
+  * `ec`
+  * `ecp`, `ecp2`, `ecp3`, `ecp5u`
+  * `lptm`, `lptm2`
+  * `machxo`, `machxo2`, `machxo3l`
+  * `sc`, `scm`
+  * `xp`, `xp2`
+
+* Xilinx ISE (14.0 or later):
+
+  * `unisim` (incl. `secureip`)
+  * `unimacro`
+  * `simprim` (incl. `secureip`)
+  * `xilinxcorelib`
+
+* Xilinx Vivado (2014.1 or later):
+
+  * `unisim` (incl. `secureip`)
+  * `unimacro`
+
+Supported Simulation and Verification Libraries
+===============================================
+
+* OSVVM (for VHDL-2008)
+
+  * osvvm
+  
+* UVVM (for VHDL-2008)
+
+  * uvvm-utilities
+  * uvvm-vvc-framework
+  * uvvm-vip-avalon_mm
+  * uvvm-vip-axi_lite
+  * uvvm-vip-axi_stream
+  * uvvm-vip-gpio
+  * uvvm-vip-i2c
+  * uvvm-vip-sbi
+  * uvvm-vip-spi
+  * uvvm-vip-uart
+
+---------------------------------------------------------------------
+
+Script Configuration
+====================
+
+The vendor library compile scripts need to know where the used / latest vendor
+tool chain is installed. Therefore, the scripts implement a default installation
+directory search as well as environment variable checks. If a vendor tool cannot
+be detected or the script chooses the wrong vendor library source directory,
+then it's possible to provide the path via `--source` or `-Source`.
+
+The generated output is stored relative to the current working directory. The
+scripts create a sub-directory for each vendor. The default output directory can
+be overwritten by the parameter `--output` or `-Output`.
+
+To compile all source files with GHDL, the simulator executable is searched in
+`PATH`. The found default GHDL executable can be overwritten by setting the
+environment variable `GHDL` or by passing the parameter `--ghdl` or `-GHDL` to
+the scripts.
+
+If the vendor library compilation is used very often, we recommend configuring
+these parameters in `config.sh` or `config.psm1`, so the command line can be
+shortened to the essential parts.
+
+---------------------------------------------------------------------
+
+Compiling on Linux
+==================
+
+* **Step 0 - Configure the scripts (optional)**
+    See the next section for how to configure `config.sh`.
+
+* **Step 1 - Browse to your simulation working directory**
+    
+  .. code-block:: Bash
+
+    $ cd <MySimulationFolder>
+    ```
+
+* **Step 2 - Start the compilation script(s)**
+    
+  .. code-block:: Bash
+
+    $ /usr/local/lib/ghdl/vendors/compile-altera.sh --all
+    $ /usr/local/lib/ghdl/vendors/compile-lattice.sh --all
+    $ /usr/local/lib/ghdl/vendors/compile-xilinx-ise.sh --all
+    $ /usr/local/lib/ghdl/vendors/compile-xilinx-vivado.sh --all
+    $ /usr/local/lib/ghdl/vendors/compile-osvvm.sh --all
+    $ /usr/local/lib/ghdl/vendors/compile-uvvm.sh --all
+    ```
+    
+    In most cases GHDL is installed into `/usr/local/`. The scripts are
+    installed into the `lib` directory.
+
+* **Step 3 - Viewing the result**
+    This creates vendor directories in your current working directory and
+    compiles the vendor files into them.
+
+    
+  .. code-block:: Bash
+
+    $ ls -ahl
+    ...
+    drwxr-xr-x  2 <user> <group>  56K Mar 09 17:41 altera
+    drwxr-xr-x  2 <user> <group>  56K Mar 09 17:42 lattice
+    drwxr-xr-x  2 <user> <group>  56K Mar 09 17:48 osvvm
+    drwxr-xr-x  2 <user> <group>  56K Mar 09 17:58 uvvm
+    drwxr-xr-x  2 <user> <group>  56K Mar 09 17:58 xilinx-ise
+    drwxr-xr-x  2 <user> <group>  56K Mar 09 17:48 xilinx-vivado
+    ```
+
+
+---------------------------------------------------------------------
+
+Compiling on Windows
+====================
+
+* **Step 0 - Configure the scripts (optional)**
+    See the next section for how to configure `config.psm1`.
+
+* **Step 1 - Browse to your simulation working directory**
+    
+  .. code-block:: PowerShell
+
+     PS> cd <MySimulationFolder>
+
+* **Step 2 - Start the compilation script(s)**
+    
+  .. code-block:: PowerShell
+
+     PS> <GHDL>\libraries\vendors\compile-altera.ps1 -All
+     PS> <GHDL>\libraries\vendors\compile-lattice.ps1 -All
+     PS> <GHDL>\libraries\vendors\compile-xilinx-ise.ps1 -All
+     PS> <GHDL>\libraries\vendors\compile-xilinx-vivado.ps1 -All
+     PS> <GHDL>\libraries\vendors\compile-osvvm.ps1 -All
+     PS> <GHDL>\libraries\vendors\compile-uvvm.ps1 -All
+
+* **Step 3 - Viewing the result**
+    This creates vendor directories in your current working directory and
+    compiles the vendor files into them.
+
+  .. code-block:: PowerShell
+
+     PS> dir
+         Directory: D:\temp\ghdl
+
+     Mode           LastWriteTime       Length Name
+     ----           -------------       ------ ----
+     d----    09.03.2018    19:33        <DIR> altera
+     d----    09.03.2018    19:38        <DIR> lattice
+     d----    09.03.2018    19:38        <DIR> osvvm
+     d----    09.03.2018    19:45        <DIR> uvvm
+     d----    09.03.2018    19:06        <DIR> xilinx-ise
+     d----    09.03.2018    19:40        <DIR> xilinx-vivado
+
+
+---------------------------------------------------------------------
+
+Configuration Files
+======================
+
+For Linux: `config.sh`
+----------------------
+
+Please open the `config.sh` file and set the dictionary entries for the
+installed vendor tools to your tool's installation
+directories. Use an empty string `""` for not installed tools.
+
+`config.sh`:
+
+.. code-block:: Bash
+   
+   declare -A InstallationDirectory
+   InstallationDirectory[AlteraQuartus]="/opt/Altera/17.1"
+   InstallationDirectory[LatticeDiamond]="/opt/Diamond/3.9_x64"
+   InstallationDirectory[OSVVM]="/home/<user>/git/GitHub/osvvm"
+   InstallationDirectory[UVVM]="/home/<user>/git/GitHub/uvvm_all"
+   InstallationDirectory[XilinxISE]="/opt/Xilinx/14.7"
+   InstallationDirectory[XilinxVivado]="/opt/Xilinx/Vivado/2017.4"
+
+
+For Windows: `config.psm1`
+--------------------------
+
+Please open the `config.psm1` file and set the dictionary entries for the
+installed vendor tools to your tool's installation
+folder. Use an empty string `""` for not installed tools.
+
+`config.psm1`:
+
+.. code-block:: PowerShell
+
+   $InstallationDirectory = @{
+     "AlteraQuartus" =   "C:\Altera\17.1";
+     "LatticeDiamond" =  "C:\Lattice\Diamond\3.9_x64";
+     "XilinxISE" =       "C:\Xilinx\14.7\ISE_DS";
+     "XilinxVivado" =    "C:\Xilinx\Vivado\2017.4";
+     "OSVVM" =           "D:\git\GitHub\osvvm";
+     "UVVM" =            "D:\git\GitHub\uvvm_all"
+   }
+
+
+Selectable Options for the Bash Scripts:
+----------------------------------------
+
+* Common parameters to most scripts:
+  
+  .. code-block:: none
+
+     --help, -h            Print the embedded help page(s).
+     --clean, -c           Cleanup directory before analyzing.
+     --no-warnings, -n     Don't show warnings. Report errors only.
+     --skip-existing, -s   Skip already compiled files (an *.o file exists).
+     --skip-largefiles, -S Don't compile large entities like DSP and PCIe primitives.
+     --halt-on-error, -H   Stop compiling if an error occurred.
+
+* `compile-altera.sh`
+
+  Selectable libraries:
+  
+  .. code-block:: none
+
+     --all, -a             Compile all libraries, including common libraries, packages and device libraries.
+     --altera              Compile base libraries like 'altera' and 'altera_mf'
+     --max                 Compile device libraries for Max CPLDs
+     --arria               Compile device libraries for Arria FPGAs
+     --cyclone             Compile device libraries for Cyclone FPGAs
+     --stratix             Compile device libraries for Stratix FPGAs
+
+  Compile options:
+  
+  .. code-block:: none
+	
+     --vhdl93              Compile selected libraries with VHDL-93 (default).
+     --vhdl2008            Compile selected libraries with VHDL-2008.
+
+* `compile-xilinx-ise.sh`
+
+  Selectable libraries:
+  
+  .. code-block:: none
+	
+     --all, -a             Compile all libraries, including common libraries, packages and device libraries.
+     --unisim              Compile the unisim primitives
+     --unimacro            Compile the unimacro macros
+     --simprim             Compile the simprim primitives
+     --corelib             Compile the xilinxcorelib macros
+     --secureip            Compile the secureip primitives
+
+  Compile options:
+  
+  .. code-block:: none
+	
+     --vhdl93              Compile selected libraries with VHDL-93 (default).
+     --vhdl2008            Compile selected libraries with VHDL-2008.
+
+* `compile-xilinx-vivado.sh`
+
+  Selectable libraries:
+  
+  .. code-block:: none
+	
+     --all, -a             Compile all libraries, including common libraries, packages and device libraries.
+     --unisim              Compile the unisim primitives
+     --unimacro            Compile the unimacro macros
+     --secureip            Compile the secureip primitives
+
+  Compile options:
+  
+  .. code-block:: none
+	
+     --vhdl93              Compile selected libraries with VHDL-93 (default).
+     --vhdl2008            Compile selected libraries with VHDL-2008.
+
+* `compile-osvvm.sh`
+
+  Selectable libraries:
+  
+  .. code-block:: none
+	
+     --all, -a             Compile all.
+     --osvvm               Compile the OSVVM library.
+
+* `compile-uvvm.sh`
+
+  Selectable libraries:
+  
+  .. code-block:: none
+	
+     --all, -a             Compile all.
+     --uvvm                Compile the UVVM libraries.
+
+
+Selectable Options for the PowerShell Scripts:
+----------------------------------------------
+
+* Common parameters to all scripts:
+  
+  .. code-block:: none
+	
+     -Help                 Print the embedded help page(s).
+     -Clean                Cleanup directory before analyzing.
+     -SuppressWarnings     Don't show warnings. Report errors only.
+
+* `compile-altera.ps1`
+
+  Selectable libraries:
+  
+  .. code-block:: none
+	
+     -All                  Compile all libraries, including common libraries, packages and device libraries.
+     -Altera               Compile base libraries like 'altera' and 'altera_mf'
+     -Max                  Compile device libraries for Max CPLDs
+     -Arria                Compile device libraries for Arria FPGAs
+     -Cyclone              Compile device libraries for Cyclone FPGAs
+     -Stratix              Compile device libraries for Stratix FPGAs
+
+  Compile options:
+		
+  .. code-block:: none
+
+     -VHDL93               Compile selected libraries with VHDL-93 (default).
+     -VHDL2008             Compile selected libraries with VHDL-2008.
+
+* `compile-xilinx-ise.ps1`
+
+  Selectable libraries:
+  
+  .. code-block:: none
+
+     -All                  Compile all libraries, including common libraries, packages and device libraries.
+     -Unisim               Compile the unisim primitives
+     -Unimacro             Compile the unimacro macros
+     -Simprim              Compile the simprim primitives
+     -CoreLib              Compile the xilinxcorelib macros
+     -Secureip             Compile the secureip primitives
+
+  Compile options:
+  
+  .. code-block:: none
+
+     -VHDL93               Compile selected libraries with VHDL-93 (default).
+     -VHDL2008             Compile selected libraries with VHDL-2008.
+
+* `compile-xilinx-vivado.ps1`
+
+  Selectable libraries:
+  
+  .. code-block:: none
+
+     -All                  Compile all libraries, including common libraries, packages and device libraries.
+     -Unisim               Compile the unisim primitives
+     -Unimacro             Compile the unimacro macros
+     -Secureip             Compile the secureip primitives
+
+  Compile options:
+  
+  .. code-block:: none
+
+     -VHDL93               Compile selected libraries with VHDL-93 (default).
+     -VHDL2008             Compile selected libraries with VHDL-2008.
+
+* `compile-osvvm.ps1`
+
+  Selectable libraries:
+  
+  .. code-block:: none
+
+     -All                  Compile all.
+     -OSVVM                Compile the OSVVM library.
+
+* `compile-uvvm.ps1`
+
+  Selectable libraries:
+  
+  .. code-block:: none
+
+     -All                  Compile all.
+     -UVVM                 Compile the UVVM libraries.
+
+--------------------------------------------------------------------------------
+
+.. container:: footnotes
+
+	 .. rubric:: Footnotes
+
+   .. [#f1] OSVVM http://github.com/OSVVM/OSVVM
+   .. [#f3] UVVM https://github.com/UVVM/UVVM_All
+   .. [#f4] Generic Colourizer http://kassiopeia.juls.savba.sk/~garabik/software/grc.html
diff --git a/doc/getting/Releases.rst b/doc/getting/Releases.rst
index 81286a14a..676ffd421 100644
--- a/doc/getting/Releases.rst
+++ b/doc/getting/Releases.rst
@@ -31,8 +31,7 @@ Downloading pre-built packages
       from helpers import printReleaseTab
       printReleaseTab('data', latex=True)
 
-Pre-built packages of older releases
-====================================
+.. rubric :: Pre-built packages of older releases
 
 .. only:: html
 
@@ -58,10 +57,9 @@ Downloading Source Files
 
 .. _RELEASE:Sources:Zip:
 
-Downloading from GitHub
-=======================
+.. rubric :: Tarball/zip-file
 
-GHDL can be downloaded as a zip-file from GitHub. See the following table, to
+GHDL can be downloaded as a zip-file or tarball from GitHub. See the following table, to
 choose your desired format/version:
 
 .. only:: html
@@ -84,21 +82,17 @@ choose your desired format/version:
 
 .. HINT::
 
-   To download a specific version of GHDL, use these alternative URL, where ``<format>`` is ``tar`` or ``zip``: ``https://api.github.com/repos/ghdl/ghdl/<format>ball/<tag>``.
+   To download a specific version of GHDL, use this alternative URL, where ``<format>`` is ``tar.gz`` or ``zip``: ``https://codeload.github.com/ghdl/ghdl/<format>/<tag>``.
 
 .. _RELEASE:Sources:GitClone:
 
-Downloading via ``git clone``
-=============================
+.. rubric :: git clone
 
 GHDL can be downloaded (cloned) with ``git clone`` from GitHub. GitHub offers
 the transfer protocols HTTPS and SSH. You should use SSH if you have a GitHub
 account and have already uploaded an OpenSSH public key to GitHub, otherwise
 use HTTPS if you have no account or you want to use login credentials.
 
-The created folder :file:`<GitRoot>\\ghdl` is used as :file:`<GHDLRoot>` in
-later instructions or on other pages in this documentation.
-
 +----------+----------------------------------------+
 | Protocol | GitHub Repository URL                  |
 +==========+========================================+
@@ -111,12 +105,7 @@ later instructions or on other pages in this documentation.
 
    Execute ``git checkout -b stable <tag>`` after ``git clone``, to checkout a specific version of GHDL.
 
-
-On Linux
---------
-
-Command line instructions to clone GHDL onto a Linux machine with HTTPS
-protocol:
+Command line instructions to clone GHDL with HTTPS protocol:
 
 .. code-block:: Bash
 
@@ -125,8 +114,7 @@ protocol:
    cd ghdl
    git remote rename origin github
 
-Command line instructions to clone GHDL onto a Linux machine machine with SSH
-protocol:
+Command line instructions to clone GHDL with SSH protocol:
 
 .. code-block:: Bash
 
@@ -135,40 +123,9 @@ protocol:
    cd ghdl
    git remote rename origin github
 
-
-On OS X
--------
-
-Please see the Linux instructions.
-
-
-On Windows
-----------
-
 .. NOTE::
 
-   All Windows command line instructions are intended for :program:`Windows PowerShell`,
-   if not marked otherwise. So executing the following instructions in Windows
-   Command Prompt (:program:`cmd.exe`) won't function or will result in errors!
-   :program:`Windows PowerShell` can be installed or upgraded to v5.1 by installing the
-   `Windows Management Framework <https://docs.microsoft.com/en-us/powershell/wmf/5.1/install-configure>`_.
-
-Command line instructions to clone GHDL onto a Windows machine with HTTPS
-protocol:
-
-.. code-block:: PowerShell
-
-   cd GitRoot
-   git clone "https://github.com/ghdl/ghdl.git" ghdl
-   cd ghdl
-   git remote rename origin github
-
-Command line instructions to clone GHDL onto a Windows machine with SSH
-protocol:
-
-.. code-block:: PowerShell
-
-   cd GitRoot
-   git clone "ssh://git@github.com:ghdl/ghdl.git" ghdl
-   cd ghdl
-   git remote rename origin github
+   Executing the following instructions in Windows Command Prompt (:program:`cmd.exe`)
+   won't function or will result in errors! All Windows command line instructions are
+   intended for :program:`Windows PowerShell`, if not marked otherwise. :program:`Windows PowerShell`
+   can be installed or upgraded to v5.1 by installing the `Windows Management Framework <https://docs.microsoft.com/en-us/powershell/wmf/5.1/install-configure>`_.
diff --git a/doc/getting/index.rst b/doc/getting/index.rst
new file mode 100644
index 000000000..f64e44caf
--- /dev/null
+++ b/doc/getting/index.rst
@@ -0,0 +1,79 @@
+.. _BUILD:
+
+Building GHDL from Sources
+##########################
+
+.. rubric :: Download
+
+GHDL can be downloaded as a `zip-file <https://github.com/ghdl/ghdl/archive/master.zip>`_/`tar-file <https://github.com/ghdl/ghdl/archive/master.tar.gz>`_
+(latest 'master' branch) or cloned with ``git clone`` from GitHub. GitHub
+offers HTTPS and SSH as transfer protocols. See the :ref:`RELEASE:Sources`
+page for further details.
+
+.. IMPORTANT ::
+   Since GHDL is written in `Ada`, independently of the code generator you use,
+   the a compiler is required. Most GNU/Linux package managers provide a package
+   named ``gcc-ada`` or ``gcc-gnat``. Alternatively, `GNU Ada compiler`, `GNAT GPL`,
+   can be downloaded anonymously from `libre.adacore.com <http://libre.adacore.com/tools/gnat-gpl-edition/>`_ (2014, or later; for x86, 32 or 64 bits).
+   Then, untar and run the doinstall script.
+
+.. rubric :: Available back-ends
+
+GHDL currently supports three different back-ends (code generators):
+
+* mcode - built-in x86 (or x86_64) code generator
+* GCC - Gnu Compiler Collection (`gcc.gnu.org <http://gcc.gnu.org/>`_)
+* LLVM - Low-Level Virtual Machine (`llvm.org <http://llvm.org/>`_)
+
+Here is a short comparison, so that you can choose the one you want to use:
+
++----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+
+| Back-end                   | Pros                                                                       | Cons                                                    |
++============================+============================================================================+=========================================================+
+| :ref:`mcode <BUILD:mcode>` | * Very easy to build                                                       | * Simulation is slower                                  |
+|                            | * Very quick analysis                                                      | * x86_64/i386 only                                      |
+|                            | * Can handle very large designs                                            |                                                         |
++----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+
+| :ref:`LLVM <BUILD:llvm>`   | * Generated code is faster                                                 | * Build is more complex than mcode                      |
+|                            | * Generated code can be debugged (with ``-g``)                             |                                                         |
+|                            | * Easier to build than GCC                                                 |                                                         |
+|                            | * Ported to many platforms (x86, x86_64, armv7/aarch64)                    |                                                         |
++----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+
+| :ref:`GCC <BUILD:gcc>`     | * Generated code is faster (particularly with ``-O`` or ``-O2``)           | * Build is even more complex                            |
+|                            | * Generated code can be debugged (with ``-g``)                             | * Analysis can take time (particularly for large units) |
+|                            | * Ported to many platforms (x86, x86_64, PowerPC, SPARC)                   | * Code coverage collection (``gcov``) is unique to GCC  |
++----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+
+
+.. toctree::
+   :hidden:
+
+   Directories
+   mcode
+   LLVM
+   GCC
+
+.. HINT ::
+   The output of both GCC and LLVM is an executable file, but `mcode` does not
+   generate any. Therefore, if using GCC/LLVM, the call with argument ``-r`` can
+   be replaced with direct execution of the binary. See section :ref:`USING:QuickStart`.
+
+After making your choice, you can jump to the corresponding section.
+However, we suggest you to read :ref:`BUILD:dir_structure` first, so that you
+know where the content will be placed and which files are expected to be
+created.
+
+.. HINT ::
+  In these instructions, the configure script is executed in the source directory; but you can execute in a different
+  directory too, like this:
+
+	.. CODE:: Bash
+
+		$ mkdir ghdl-objs
+		$ cd ghdl-objs
+		$ ../path/to/ghdl/configure ...
+
+.. HINT :: On Windows, building GHDL with mcode backend and GNAT GPL 32 bit seems to be the only way to get a standalone native executable.
+
+  * MINGW/MSYS2 builds depend on the environment/runtime.
+  * For 64 bit, no native compiler exists from AdaCore.
+  * That Ada to .NET compiler, which might work for 32 or 64 bit. is not up-to-date.
diff --git a/doc/getting/mcode.rst b/doc/getting/mcode.rst
new file mode 100644
index 000000000..5e6fbbf68
--- /dev/null
+++ b/doc/getting/mcode.rst
@@ -0,0 +1,74 @@
+.. _BUILD:mcode:
+
+mcode backend
+#############
+
+The mcode backend is available for all supported platforms and is also the
+simplest procedure, because it requires the fewest dependencies and configuration
+options.
+
+.. _BUILD:mcode:GNAT:
+
+GCC/GNAT: GNU/Linux or Windows (MinGW/MSYS2)
+============================================
+
+.. rubric:: Requirements
+
+* GCC (Gnu Compiler Collection)
+* GNAT (Ada compiler for GCC)
+
+GHDL is configured by ``configure`` and built by ``make``.
+
+* First, GHDL needs to be configured. It is common to specify a ``PREFIX``
+  (installation directory like ``/usr/local`` or ``/opt/ghdl``). Without any
+  other option, ``configure`` selects `mcode` as the backend.
+
+* Next, ``make`` starts the compilation process.
+
+* Finally, ``make install`` installs GHDL into the installation directory
+  specified by ``PREFIX``.
+
+.. HINT :: ON GNU/Linux, you may need super user privileges (``sudo ...``).
+
+
+.. rubric:: Example:
+
+.. code-block:: Bash
+
+   $ cd <ghdl>
+   $ mkdir build
+   $ cd build
+   $ ../configure --prefix=PREFIX
+   $ make
+   $ make install
+
+.. _BUILD:mcode:GNATGPL-Windows:
+
+GNAT GPL: Windows
+=================
+
+.. rubric:: Requirements
+
+* GNAT GPL from http://libre.adacore.com
+* PowerShell 4
+* PowerShell Community Extensions (PSCX)
+
+.. rubric:: `compile.ps1`
+
+.. code-block:: plain
+
+   Commands          Description
+   --------------------------------------------------------------------
+   -Help             Display the integrated help pages
+   -Clean            Clean up all files and directories
+   -Compile          Compile GHDL
+   -Install          Install all files into a directory (xcopy deployment)
+   -Uninstall        Uninstall all files from a directory
+   -Update           Update files in the installation directory
+   -CreatePackage    create an installer package
+
+   Install options:
+   -InstallPath      Installation directory
+
+   CreatePackage options:
+   -Zip              Create a zip-file for xcopy deployment