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

* doc: fix version extraction from 'configure'

* doc: update section 'Getting GHDL'

* readme: update

21 files changed, 268 insertions, 425 deletions

diff --git a/README.md b/README.md
index 5204e9131..5ab462a19 100644
--- a/README.md
+++ b/README.md
@@ -50,11 +50,28 @@ Periodically (not regularly), several binary distributions are made available th
 
 ## Building GHDL
 
-In order to follow the traditional way to `configure` and `make`, you need the GNU Ada compiler, GNAT GPL (2014, or later; for x86, 32 or 64 bits). GNAT GPL can be downloaded anonymously from [libre.adacore.com](http://libre.adacore.com/tools/gnat-gpl-edition/). Then, untar and run the *doinstall* script.
+GHDL currently supports three different back-ends (code generators). Each has its pros and cons. Here is a short comparison:
+
+| | pros | cons | observations |
+|---|---|---|---|
+|mcode | very easy to build | x86_64/i386 only | no executable created from your design |
+| | very quick analysis time and can analyze very big designs | simulation is slower | |
+| GCC | generated code is faster | analyze can take time (particularly for big units) | the output is an executable |
+| | generated code can be debugged | build is more complex |
+| | many platforms (x86, x86_64, powerpc, sparc) | |
+
+LLVM has the same pros/cons as GCC, but it is easier to build. However, coverage (`gcov`) is unique to GCC.
+
+You can find specific instructions for each of the options in '[Building](http://ghdl.readthedocs.io/en/latest/building/Building.html)'.
+
+### TL;DR
+
+In order to follow the traditional way to `configure` and `make`, you need the an Ada compiler. Most GNU/Linux package managers provide a package named `gcc-ada` or `gcc-gnat`. Alternatively, 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.
 
 > Depending on the OS and distribution you are using, you will also need to install some toolchain dependencies, such as `zlib`. See '[Building](http://ghdl.readthedocs.io/en/latest/building/Building.html)' for specific package names.
 
-In the GHDL base directory, configure and build:
+To use mcode backend (easiest to build), in the GHDL base directory, configure and build:
+
 ```sh
 $ ./configure --prefix=/usr/local
 $ make
@@ -70,22 +87,6 @@ That's all!
 
 > The executable is installed as 'ghdl' in `/usr/local`. To install it to a different path, change the `--prefix` in the call to `configure`. For example, on Windows, you may want to set it to `--prefix=/c/Program Files (x86)/GHDL`.
 
----
-
-Furthermore, each supported compiler has its pros and cons. Here is a short comparison:
-
-| | pros | cons | observations |
-|---|---|---|---|
-|mcode | very easy to build | x86_64/i386 only | no executable created from your design |
-| | very quick analysis time and can analyze very big designs | simulation is slower | |
-| GCC | generated code is faster | analyze can take time (particularly for big units) | the output is an executable |
-| | generated code can be debugged | build is more complex |
-| | many platforms (x86, x86_64, powerpc, sparc) | |
-
-LLVM has the same pros/cons as GCC, but it is easier to build. However, coverage (`gcov`) is unique to GCC.
-
-You can find specific instructions for each of the options in '[Building](http://ghdl.readthedocs.io/en/latest/building/Building.html)'.
-
 # Project structure
 
 ## Regular users
@@ -99,14 +100,12 @@ You can find specific instructions for each of the options in '[Building](http:/
 
 ## Advanced users
 
-- `libghdl` is a shared library that includes a subset of the regular features plus some features to be used by extension tools (i.e. `libghdl-py`). This is built along with the regular GHDL and it supports both non-synthesisable and synthesisable code. Nonetheless, this is not for users, but for tools built on top of the core.
+- `libghdl` is a shared library that includes a subset of the regular features plus some features to be used by extension tools (i.e. `libghdl-py`). This is built along with the regular GHDL and it supports both non-synthesisable and synthesisable code. Nonetheless, this is not for users, but for tools built on top of the core. When configured along with `--enable-synth`, this shared library includes **[experimental]** synthesis features too.
 
 - [libghdl-py](python/libghdl) is a Python interface to `libghdl`. Currently, it is only used by `ghdl-ls`; however, it can be useful for advanced users which are willing to build Python utilities based on GHDL.
 
-## Experimental
-
-- `libghdlsynth` is a shared library that includes the analysis and synthesis features of the core GHDL, but not the pieces for compilation/simulation.
+- **[experimental]** [ghdlsynth-beta](https://github.com/tgingold/ghdlsynth-beta) is the integration of GHDL as a frontend plugin module for [Yosys Open SYnthesis Suite](http://www.clifford.at/yosys/), which uses the `libghdlsynth` library.
 
-- [ghdlsynth-beta](https://github.com/tgingold/ghdlsynth-beta) is the integration of GHDL as a frontend plugin module for [Yosys Open SYnthesis Suite](http://www.clifford.at/yosys/), which uses the `libghdlsynth` library.
+- **[deprecated]** `libghdlsynth` is a shared library that includes the analysis and synthesis features of the core GHDL, but not the pieces for compilation/simulation.
 
-- `ghdl_simul`, which supports interpreted simulation, is available for historical reasons and for development/debugging only. It is very slow compared to the 'regular' compiled simulation and not all the features are supported.
+- **[deprecated]** `ghdl_simul`, which supports interpreted simulation, is available for historical reasons and for development/debugging only. It is very slow compared to the 'regular' compiled simulation and not all the features are supported.
diff --git a/doc/_extensions/.gitempty b/doc/_extensions/.gitempty
deleted file mode 100644
index e69de29bb..000000000
--- a/doc/_extensions/.gitempty
+++ /dev/null
diff --git a/doc/building/gcc/GNULinux-GNAT.rst b/doc/building/gcc/GNULinux-GNAT.rst
deleted file mode 100644
index e6c7f61b4..000000000
--- a/doc/building/gcc/GNULinux-GNAT.rst
+++ /dev/null
@@ -1,36 +0,0 @@
-.. _BUILD:gcc:GNULinux-GNAT:
-
-GCC Backend on GNU/Linux with GCC/GNAT
-######################################
-
-.. 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.
diff --git a/doc/building/gcc/Windows-MinGW-GNAT.rst b/doc/building/gcc/Windows-MinGW-GNAT.rst
deleted file mode 100644
index 09274a534..000000000
--- a/doc/building/gcc/Windows-MinGW-GNAT.rst
+++ /dev/null
@@ -1,30 +0,0 @@
-.. _BUILD:gcc:Windows-MinGW-GNAT:
-
-GCC Backend on Windows with GCC/GNAT (MinGW)
-############################################
-
-.. TODO::
-   Under investigation on how to build that beast.
-
-.. #
-   On Windows with MinGW, GHDL is configured by ``configure`` and build 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`` select `mcode` as backend.
-
-   * 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 --prefix=PREFIX
-      $ make
-      $ make install
diff --git a/doc/building/gcc/index.rst b/doc/building/gcc/index.rst
deleted file mode 100644
index 23b6ebfa2..000000000
--- a/doc/building/gcc/index.rst
+++ /dev/null
@@ -1,54 +0,0 @@
-.. _BUILD:gcc:
-
-GCC Backend
-###########
-
-.. 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
-
-.. rubric:: Supported platforms
-
-* :doc:`GNULinux-GNAT`
-* :doc:`Windows-MinGW-GNAT`
-
-
-.. 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:: C
-
-		  else if (! strcmp (language_string, "GNU Objective-C"))
-			  i = 14;
-		  else
-		  -  gcc_unreachable ();
-		  +  i = 0;
-		  fprintf (file, "%d,", i);
-
-		  /* 8 single bit fields: global linkage (not set for C extern linkage),
-
-.. toctree::
-   :hidden:
-
-   GNU/Linux with GCC/GNAT <GNULinux-GNAT>
-   Windows with GCC/GNAT (MinGW) <Windows-MinGW-GNAT>
diff --git a/doc/building/llvm/GNULinux-GNAT.rst b/doc/building/llvm/GNULinux-GNAT.rst
deleted file mode 100644
index 5bb1fcad7..000000000
--- a/doc/building/llvm/GNULinux-GNAT.rst
+++ /dev/null
@@ -1,23 +0,0 @@
-.. _BUILD:llvm:GNULinux-GNAT:
-
-LLVM Backend on GNU/Linux with GCC/GNAT
-#######################################
-
-.. HINT:: You need to install LLVM (usually depends on ``libedit``, see :ghdlsharp:`29`). Debugging is only supported with LLVM 3.5.
-
-* First configure GHDL with the proper arg ``./configure --with-llvm-config``. If ``llvm-config`` is not in your path, you can specify it: ``./configure --with-llvm-config=LLVM_INSTALL/bin/llvm-config``.
-
-* Then, build with ``make`` and install with ``make install``.
-
-.. 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/building/llvm/Windows-MinGW-GNAT.rst b/doc/building/llvm/Windows-MinGW-GNAT.rst
deleted file mode 100644
index 59d70023f..000000000
--- a/doc/building/llvm/Windows-MinGW-GNAT.rst
+++ /dev/null
@@ -1,26 +0,0 @@
-.. _BUILD:llvm:Windows-MinGW-GNAT:
-
-LLVM Backend on Windows with GCC/GNAT (MinGW)
-#############################################
-
-On Windows with MinGW, 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``.
-
-.. rubric:: Example:
-
-.. code-block:: Bash
-
-   $ cd <ghdl>
-   $ mkdir build
-   $ cd build
-   $ ../configure --prefix=PREFIX
-   $ make
-   $ make install
diff --git a/doc/building/llvm/index.rst b/doc/building/llvm/index.rst
deleted file mode 100644
index 72c2c50c1..000000000
--- a/doc/building/llvm/index.rst
+++ /dev/null
@@ -1,22 +0,0 @@
-.. _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
-
-.. rubric:: Supported platforms
-
-* :doc:`GNULinux-GNAT`
-* :doc:`Windows-MinGW-GNAT`
-* Mac OS
-
-.. toctree::
-   :hidden:
-
-   GNU/Linux with GCC/GNAT <GNULinux-GNAT>
-   Windows with GCC/GNAT (MinGW) <Windows-MinGW-GNAT>
diff --git a/doc/building/mcode/GNULinux-GNAT.rst b/doc/building/mcode/GNULinux-GNAT.rst
deleted file mode 100644
index 2d7598599..000000000
--- a/doc/building/mcode/GNULinux-GNAT.rst
+++ /dev/null
@@ -1,27 +0,0 @@
-.. _BUILD:mcode:GNULinux-GNAT:
-
-mcode Backend on GNU/Linux with GCC/GNAT
-########################################
-
-On Linux, 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``. You may need super user privileges (``sudo ...``).
-
-
-.. rubric:: Example:
-
-.. code-block:: Bash
-
-   $ cd <ghdl>
-   $ mkdir build
-   $ cd build
-   $ ../configure --prefix=PREFIX
-   $ make
-   $ make install
diff --git a/doc/building/mcode/Windows-GNATGPL.rst b/doc/building/mcode/Windows-GNATGPL.rst
deleted file mode 100644
index c767343be..000000000
--- a/doc/building/mcode/Windows-GNATGPL.rst
+++ /dev/null
@@ -1,36 +0,0 @@
-.. _BUILD:mcode:Windows-GNATGPL:
-
-mcode Backend on Windows with GNAT GPL
-######################################
-
-Requirements
-============
-
-* GNAT GPL from http://libre.adacore.com
-* PowerShell 4
-* PowerShell Community Extensions (PSCX)
-
-
-Scripts and Parameters
-======================
-
-`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
diff --git a/doc/building/mcode/Windows-MinGW-GNAT.rst b/doc/building/mcode/Windows-MinGW-GNAT.rst
deleted file mode 100644
index f1482ccb8..000000000
--- a/doc/building/mcode/Windows-MinGW-GNAT.rst
+++ /dev/null
@@ -1,26 +0,0 @@
-.. _BUILD:mcode:Windows-MinGW-GNAT:
-
-mcode Backend on Windows with GCC/GNAT (MinGW)
-##############################################
-
-On Windows with MinGW, 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``.
-
-.. rubric:: Example:
-
-.. code-block:: Bash
-
-   $ cd <ghdl>
-   $ mkdir build
-   $ cd build
-   $ ../configure --prefix=PREFIX
-   $ make
-   $ make install
diff --git a/doc/building/mcode/index.rst b/doc/building/mcode/index.rst
deleted file mode 100644
index 92eeaabd4..000000000
--- a/doc/building/mcode/index.rst
+++ /dev/null
@@ -1,28 +0,0 @@
-.. _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.
-
-
-.. rubric:: Requirements
-
-* GCC (Gnu Compiler Collection)
-* GNAT (Ada compiler for GCC)
-
-
-.. rubric:: Supported platforms
-
-* :doc:`GNULinux-GNAT`
-* :doc:`Windows-GNATGPL`
-* :doc:`Windows-MinGW-GNAT`
-
-.. toctree::
-   :hidden:
-
-   GNU/Linux with GCC/GNAT <GNULinux-GNAT>
-   Windows with GNAT GPL <Windows-GNATGPL>
-   Windows with GCC/GNAT (MinGW) <Windows-MinGW-GNAT>
diff --git a/doc/conf.py b/doc/conf.py
index efa30f23e..014cbd13b 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -14,17 +14,10 @@
 
 import sys, os, shlex, re, subprocess
 
-# http://docs.readthedocs.io/en/latest/getting_started.html#in-markdown
-from recommonmark.parser import CommonMarkParser
-source_parsers = { '.md': CommonMarkParser, }
-
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('.'))
-# sys.path.insert(0, os.path.abspath('../py'))
-sys.path.insert(0, os.path.abspath('_extensions'))
-# sys.path.insert(0, os.path.abspath('_themes/sphinx_rtd_theme'))
 
 # -- General configuration ------------------------------------------------
 
@@ -36,6 +29,7 @@ needs_sphinx = '1.5'
 # ones.
 extensions = [
 # Standard Sphinx extensions
+	'recommonmark',
 	'sphinx.ext.extlinks',
 	'sphinx.ext.intersphinx',
 	'sphinx.ext.todo',
@@ -55,9 +49,11 @@ extensions = [
 templates_path = ['_templates', '_themes']
 
 # The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-# source_suffix = ['.rst', '.md']
-source_suffix = ['.rst', '.md']
+source_suffix = {
+    '.rst': 'restructuredtext',
+    #'.txt': 'markdown',
+    '.md': 'markdown',
+}
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
@@ -67,21 +63,22 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'GHDL'
-copyright = u'2015-2017, Tristan Gingold and contributors'
+copyright = u'2002-2019, Tristan Gingold and contributors'
 author = u'Tristan Gingold and contributors'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
-#
+
 try:
 	with open('../configure') as verin:
 		for line in verin:
-			line = re.findall(r'ghdl_version=\"(.+)\"', line)
+			line = re.findall(r'ghdl_version=\"([0-9].+)\"', line)
 			if line:
 				version=line[0]
-except Exception, e:
-	print "cannot extract version: %s" % e
+				break
+except Exception as e:
+	print('cannot extract version: %s' % e)
 	version = "latest"
 	pass
 
@@ -89,7 +86,6 @@ release = version  # The full version, including alpha/beta/rc tags.
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
-#
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
 language = None
@@ -334,7 +330,7 @@ texinfo_documents = [
 # ==============================================================================
 intersphinx_mapping = {
    'python': ('https://docs.python.org/3.6/', None),
-   'poc': ('http://poc-library.readthedocs.io/en/release', None),
+   'poc': ('https://poc-library.readthedocs.io/en/release', None),
 #   'ghdl':   ('http://ghdl.readthedocs.io/en/latest', None)
 }
 
diff --git a/doc/building/Directories.rst b/doc/getting/Directories.rst
index 6b3c105f0..2d5b575d8 100644
--- a/doc/building/Directories.rst
+++ b/doc/getting/Directories.rst
@@ -1,6 +1,6 @@
 .. _BUILD:dir_structure:
 
-Directory Structure
+Directory structure
 ###################
 
 * ``src``: sources of GHDL, all of them in Ada.
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/building/PrecompileVendorPrimitives.rst b/doc/getting/PrecompileVendorPrimitives.rst
index 714dc053d..714dc053d 100644
--- a/doc/building/PrecompileVendorPrimitives.rst
+++ b/doc/getting/PrecompileVendorPrimitives.rst
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/building/Building.rst b/doc/getting/index.rst
index 9bdecd147..f64e44caf 100644
--- a/doc/building/Building.rst
+++ b/doc/getting/index.rst
@@ -3,20 +3,27 @@
 Building GHDL from Sources
 ##########################
 
-.. rubric:: Download
+.. 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. The installation directory is referred to as ``GHDLRoot``.
+page for further details.
 
-.. rubric:: Available back-ends
+.. 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 <http://gcc.gnu.org/>`_, and
-* `LLVM - Low-Level Virtual Machine <http://llvm.org/>`_ .
+* 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:
 
@@ -27,9 +34,10 @@ Here is a short comparison, so that you can choose the one you want to use:
 |                            | * Very quick analysis                                                      | * x86_64/i386 only                                      |
 |                            | * Can handle very large designs                                            |                                                         |
 +----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+
-| :ref:`LLVM <BUILD:llvm>`   | * Generated code is faster                                                 | * Build is more complex                                 |
+| :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) |
@@ -40,11 +48,11 @@ Here is a short comparison, so that you can choose the one you want to use:
    :hidden:
 
    Directories
-   With mcode Backend <mcode/index>
-   With LLVM Backend <llvm/index>
-   With GCC Backend <gcc/index>
+   mcode
+   LLVM
+   GCC
 
-.. HINT::
+.. 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`.
@@ -54,14 +62,7 @@ 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::
-   Since GHDL is written in `Ada`, independently of the code generator you use,
-   the `GNU Ada compiler`, `GNAT GPL`, is required, 2014 (or later) for ``x86``
-   (32 or 64 bit). `GNAT GPL` can be downloaded anonymously from `libre.adacore.com <http://libre.adacore.com/tools/gnat-gpl-edition/>`_.
-   Then, untar and run the doinstall script. Alternatively, most GNU/Linux
-   provide a package named ``gcc-ada`` or ``gcc-gnat``.
-
-.. HINT::
+.. HINT ::
   In these instructions, the configure script is executed in the source directory; but you can execute in a different
   directory too, like this:
 
@@ -70,3 +71,9 @@ created.
 		$ 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
diff --git a/doc/index.rst b/doc/index.rst
index 2df9c2c9f..b1bd73c23 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -103,8 +103,8 @@ LRM) is a plus.
    :hidden:
 
    getting/Releases
-   Building GHDL <building/Building>
-   building/PrecompileVendorPrimitives
+   Building GHDL <getting/index>
+   getting/PrecompileVendorPrimitives
 
 .. raw:: latex