doc: reorganise and update

8 files changed, 435 insertions, 1 deletions

diff --git a/doc/development/CodingStyle.rst b/doc/development/CodingStyle.rst
index a2fc554fd..02870c88c 100644
--- a/doc/development/CodingStyle.rst
+++ b/doc/development/CodingStyle.rst
@@ -199,7 +199,7 @@ Guidelines to edit the documentation
             ToC entry <file1>
             file2
 
-   7) Documentation should not use “you”, “we”, …, because it’s not an interactive conversation or informal letter. It’s like a thesis, everything is structured and formal. However, to make it more friendly to newcomers, we agree to allow informal language in the section :ref:`USING:QuickStart`.
+   7) Documentation should not use “you”, “we”, …, because it’s not an interactive conversation or informal letter. It’s like a thesis, everything is structured and formal. However, to make it more friendly to newcomers, we agree to allow informal language in the Quick Start Guide.
 
    8) Please keep errors to a minimum.
 
diff --git a/doc/development/Directories.rst b/doc/development/Directories.rst
new file mode 100644
index 000000000..fbe85f8ef
--- /dev/null
+++ b/doc/development/Directories.rst
@@ -0,0 +1,31 @@
+.. _BUILD:dir_structure:
+
+Directory structure
+###################
+
+* ``doc``: `reStructuredText` sources and auxiliary files to build the documentation with `Sphinx <http://www.sphinx-doc.org>`_.
+  A continuous integration (CI) workflow is used to automatically build and deploy this site and/or PDF you are reading.
+
+* ``libraries``: mostly third party libraries such as `ieee`, `std`, `synopsys` and `vital`. Except for a few shell and
+  `Python` scripts, all the content is written in VHDL.
+
+* ``logo``: Python and Gimp sources of the logo and the banners.
+
+* ``pyGHDL``: sources of the :mod:`Python Interfaces <pyGHDL>`.
+
+* ``scripts``: scripts and auxiliary files:
+
+  * ``scripts/vendors``: 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. See :ref:`GETTING:PrecompVendor` for
+    information on how to use them.
+
+  * ``scripts/gcc``: header and configuration files to build GHDL with GCC (all platforms).
+
+  * ``scripts/msys2-*``: PKGBUILD recipes for building nightly GHDL packages on MSYS2.
+
+  * ``scripts/pnodes*``: Python scripts for automatically generating some of the sources of :mod:`Python Interfaces <pyGHDL>`.
+
+* ``src``: sources of GHDL. Most of them are written in Ada, some in C.
+
+* ``testsuite``: files used for testing.
diff --git a/doc/development/Scripts.rst b/doc/development/Scripts.rst
new file mode 100644
index 000000000..85695358e
--- /dev/null
+++ b/doc/development/Scripts.rst
@@ -0,0 +1,23 @@
+.. _DEV:Scripts:
+
+Scripts
+#######
+
+.. #
+   This files requires a Python module called 'Frontend-AutoProgram' to be
+   located in the 'doc' root folder. It expects a variable 'parser' of type
+   ArgumentParser.
+
+.. _CMDREF-pnodes:
+
+.. autoprogram:: AutoProgram:pnodes_parser
+   :prog: pnodes
+   :groups:
+   :label: CmdRef:pnodes:
+
+.. _CMDREF-pnodespy:
+
+.. autoprogram:: AutoProgram:pnodespy_parser
+   :prog: pnodespy
+   :groups:
+   :label: CmdRef:pnodespy:
diff --git a/doc/development/building/GCC.rst b/doc/development/building/GCC.rst
new file mode 100644
index 000000000..7a8cd9b56
--- /dev/null
+++ b/doc/development/building/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, 7.x, 8.x, 9.x or 10.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/ppc64le 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`` (``gcc/config/rs6000/rs6000-logue.c`` since gcc 10), function ``rs6000_output_function_epilogue``:
+
+	  .. 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/development/building/LLVM.rst b/doc/development/building/LLVM.rst
new file mode 100644
index 000000000..b8dde9735
--- /dev/null
+++ b/doc/development/building/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, 8.0, 9.0, 10.0 or 11.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 supported with LLVM 3.5 or ``>=6``.
+
+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/development/building/Sources.rst b/doc/development/building/Sources.rst
new file mode 100644
index 000000000..523028961
--- /dev/null
+++ b/doc/development/building/Sources.rst
@@ -0,0 +1,82 @@
+.. _SOURCES:
+
+Sources
+#######
+
+.. HINT::
+
+   All the following procedures will retrieve the latest development version of GHDL, i.e., the `master` branch at
+   `github.com/ghdl/ghdl <https://github.com/ghdl/ghdl>`_. We do our best to keep it stable, but bugs can seldom be
+   published. See `HINT` boxes below for instructions to get older releases.
+
+.. _RELEASE:Sources:Zip:
+
+.. rubric :: Tarball/zip-file
+
+GHDL can be downloaded as a zip-file or tarball from GitHub. See the following table to choose your desired format/version:
+
+.. only:: html
+
+   .. |zip-master| image:: https://img.shields.io/badge/ZIP-archive/master-323131.svg?longCache=true&style=flat-square&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAMAAABEpIrGAAACE1BMVEUAAAAAAABcXFwAAACpqakAAABXV1cAAAAAAADAwMBYWFgAAACcnJxzc3MiIiKPj4%2FExMRaWlohISHo6OgbGxs5OTnMzMw9PT3AwMBWVlZkZGSGhoanp6eLi4vMzMyAgIC3t7eUlJSysrKNjY2Wlparq6uysrKlpaW1tbV6enqzs7PR0dGrq6uEhISwsLDFxcW9vb3Kysrg4OC8vLy3t7fPz8%2FDw8Ojo6OsrKzS0tLQ0NC9vb3ExMTm5ua9vb3Q0NChoaGsrKyurq7e3t7U1NSWlpaJiYmNjY3R0dG0tLSVlZXCwsK8vLzDw8Ph4eHk5OTW1tbW1tbm5ube3t7g4ODKysq3t7fOzs7f39%2FW1tbR0dHOzs7CwsLe3t7c3Nzn5%2BfW1tbq6urIyMjb29vW1tbe3t7X19fa2trb29vt7e3q6urHx8ft7e3k5OTh4eHPz8%2FV1dXT09Pm5ubh4eHg4ODm5ub9%2Ff3%2F%2F%2F%2F%2F%2F%2F%2Fk5OTp6enY2Njo6OjZ2dnn5%2Bfp6enc3Nzu7u76%2Bvr09PTk5OTw8PDn5%2Bf5%2Bfnf39%2Fq6urg4ODo6Ojk5OT4%2BPjm5ubm5ubs7Ozu7u76%2Bvrk5OTu7u739%2Ffq6urr6%2Bvx8fH6%2Bvrt7e34%2BPj6%2Bvr%2B%2Fv7s7Oz5%2Bfn%2B%2Fv7%2F%2F%2F%2Fp6enr6%2Bvt7e3v7%2B%2Fx8fHy8vLz8%2FP09PT29vb39%2Ff5%2Bfn8%2FPz9%2Ff3%2B%2Fv7%2F%2F%2F9qYR%2FuAAAAonRSTlMAAQECAgMDBAYGBwgKCwwMDQ4SEhQUGhwdHiIjIyQkJygpMDIzMzQ1NTY3OTo8PDw%2FP0ZITk9RUlNTVldXV1hYWlpaWltdYGBiY2ZpbHB1dXZ3d3t8fX5%2Ff4aHiIqKj5WXn6KjpKmssrK0t7u8vb7BwsPEyszNzc3O0dLT09fY2tvf4OXm5ufn6ers7O3w8fLy8vL09fX29%2Ff4%2Bvv7%2FP39%2Ff5qibsTAAABrElEQVR4AX2LhfcSURCFBxHBbkWxuwW7Q7AbQ7AbuwMMRQxRVAwMxRBWBRSX%2BRN%2F97y3y9ldlv3OmfPu3PkemfBsVbaQAwsrzPxnLrVh4huc65h3I8iGno9walyj6wzu9CIrVxk86YvU%2BxVS6SKZOP4D5ccxJJnxHtvnvdRk10sUlUVEJy4NFIV33d8S89P1JJj3GOfaDqQlG4%2BcX7tdlL6DKtr7UwgwuOwRdY85h08vuD1A5MFnGEgB7OlGkg0XZj5bPFXEcW91oQHj37Iu0uh%2BYNqXlZtFvKkLN%2FZ9g%2FJ7Qiep9JutjD25AiGpC0nqehZG4%2BEQaXQe%2BX3oUbNA1P8uFPWWTyqzPo2yCGDSAyj%2FT4ncZ%2F%2FzFgEs%2FwClQmDptvk2AtjJsht275C9QJqwevIxZ2ETf3UWrjBPdxR%2B7V6zykkYfY5ek0HIWIXx%2FGIQnowucC1mFmg4JlbTlngRoRw2CiBcRizGSZCoY8mHDEIoj1BPUJOUiiLr1wR%2FFo%2BaIiPeHIO0ENIMcl6yECig%2FqlNIUCtuIMKS5Sgm2xxRao4VyMuaos7qkQtvzsAWpTtdh6JoYQAAAAASUVORK5CYII%3D
+      :target: https://github.com/ghdl/ghdl/archive/master.zip
+      :alt: Source Code from GitHub - 'master' branch.
+
+   .. |tgz-master| image:: https://img.shields.io/badge/TGZ-archive/master-323131.svg?longCache=true&style=flat-square&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAMAAABEpIrGAAACE1BMVEUAAAAAAABcXFwAAACpqakAAABXV1cAAAAAAADAwMBYWFgAAACcnJxzc3MiIiKPj4%2FExMRaWlohISHo6OgbGxs5OTnMzMw9PT3AwMBWVlZkZGSGhoanp6eLi4vMzMyAgIC3t7eUlJSysrKNjY2Wlparq6uysrKlpaW1tbV6enqzs7PR0dGrq6uEhISwsLDFxcW9vb3Kysrg4OC8vLy3t7fPz8%2FDw8Ojo6OsrKzS0tLQ0NC9vb3ExMTm5ua9vb3Q0NChoaGsrKyurq7e3t7U1NSWlpaJiYmNjY3R0dG0tLSVlZXCwsK8vLzDw8Ph4eHk5OTW1tbW1tbm5ube3t7g4ODKysq3t7fOzs7f39%2FW1tbR0dHOzs7CwsLe3t7c3Nzn5%2BfW1tbq6urIyMjb29vW1tbe3t7X19fa2trb29vt7e3q6urHx8ft7e3k5OTh4eHPz8%2FV1dXT09Pm5ubh4eHg4ODm5ub9%2Ff3%2F%2F%2F%2F%2F%2F%2F%2Fk5OTp6enY2Njo6OjZ2dnn5%2Bfp6enc3Nzu7u76%2Bvr09PTk5OTw8PDn5%2Bf5%2Bfnf39%2Fq6urg4ODo6Ojk5OT4%2BPjm5ubm5ubs7Ozu7u76%2Bvrk5OTu7u739%2Ffq6urr6%2Bvx8fH6%2Bvrt7e34%2BPj6%2Bvr%2B%2Fv7s7Oz5%2Bfn%2B%2Fv7%2F%2F%2F%2Fp6enr6%2Bvt7e3v7%2B%2Fx8fHy8vLz8%2FP09PT29vb39%2Ff5%2Bfn8%2FPz9%2Ff3%2B%2Fv7%2F%2F%2F9qYR%2FuAAAAonRSTlMAAQECAgMDBAYGBwgKCwwMDQ4SEhQUGhwdHiIjIyQkJygpMDIzMzQ1NTY3OTo8PDw%2FP0ZITk9RUlNTVldXV1hYWlpaWltdYGBiY2ZpbHB1dXZ3d3t8fX5%2Ff4aHiIqKj5WXn6KjpKmssrK0t7u8vb7BwsPEyszNzc3O0dLT09fY2tvf4OXm5ufn6ers7O3w8fLy8vL09fX29%2Ff4%2Bvv7%2FP39%2Ff5qibsTAAABrElEQVR4AX2LhfcSURCFBxHBbkWxuwW7Q7AbQ7AbuwMMRQxRVAwMxRBWBRSX%2BRN%2F97y3y9ldlv3OmfPu3PkemfBsVbaQAwsrzPxnLrVh4huc65h3I8iGno9walyj6wzu9CIrVxk86YvU%2BxVS6SKZOP4D5ccxJJnxHtvnvdRk10sUlUVEJy4NFIV33d8S89P1JJj3GOfaDqQlG4%2BcX7tdlL6DKtr7UwgwuOwRdY85h08vuD1A5MFnGEgB7OlGkg0XZj5bPFXEcW91oQHj37Iu0uh%2BYNqXlZtFvKkLN%2FZ9g%2FJ7Qiep9JutjD25AiGpC0nqehZG4%2BEQaXQe%2BX3oUbNA1P8uFPWWTyqzPo2yCGDSAyj%2FT4ncZ%2F%2FzFgEs%2FwClQmDptvk2AtjJsht275C9QJqwevIxZ2ETf3UWrjBPdxR%2B7V6zykkYfY5ek0HIWIXx%2FGIQnowucC1mFmg4JlbTlngRoRw2CiBcRizGSZCoY8mHDEIoj1BPUJOUiiLr1wR%2FFo%2BaIiPeHIO0ENIMcl6yECig%2FqlNIUCtuIMKS5Sgm2xxRao4VyMuaos7qkQtvzsAWpTtdh6JoYQAAAAASUVORK5CYII%3D
+      :target: https://github.com/ghdl/ghdl/archive/master.tar.gz
+      :alt: Source Code from GitHub - 'master' branch.
+
+   +----------+------------------------+
+   | Branch   | Download Link          |
+   +==========+========================+
+   | master   | |zip-master|           |
+   +----------+------------------------+
+   | master   | |tgz-master|           |
+   +----------+------------------------+
+
+.. HINT::
+
+   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:
+
+.. 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.
+
++----------+----------------------------------------+
+| Protocol | GitHub Repository URL                  |
++==========+========================================+
+| HTTPS    | https://github.com/ghdl/ghdl.git       |
++----------+----------------------------------------+
+| SSH      | ssh://git@github.com:ghdl/ghdl.git     |
++----------+----------------------------------------+
+
+.. HINT::
+
+   Execute ``git checkout -b stable <tag>`` after ``git clone``, to checkout a specific version of GHDL.
+
+Command line instructions to clone GHDL with HTTPS protocol:
+
+.. code-block:: Bash
+
+   cd GitRoot
+   git clone "https://github.com/ghdl/ghdl.git" ghdl
+   cd ghdl
+   git remote rename origin github
+
+Command line instructions to clone GHDL with SSH protocol:
+
+.. code-block:: Bash
+
+   cd GitRoot
+   git clone "ssh://git@github.com:ghdl/ghdl.git" ghdl
+   cd ghdl
+   git remote rename origin github
+
+.. NOTE::
+
+   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.
diff --git a/doc/development/building/index.rst b/doc/development/building/index.rst
new file mode 100644
index 000000000..2c9f09d8d
--- /dev/null
+++ b/doc/development/building/index.rst
@@ -0,0 +1,106 @@
+.. _BUILD:
+
+Building GHDL from Sources
+##########################
+
+.. toctree::
+   :hidden:
+
+   Sources
+   mcode
+   LLVM
+   GCC
+
+GHDL can be downloaded as a `tarball <https://github.com/ghdl/ghdl/archive/master.tar.gz>`__/`zipfile <https://github.com/ghdl/ghdl/archive/master.zip>`__
+or cloned with ``git clone`` from GitHub. GitHub offers HTTPS and SSH as transfer protocols. See the :ref:`SOURCES` page for
+further details.
+
+.. IMPORTANT::
+   Since GHDL is written in `Ada`, independently of the code generator you use, 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.
+
+.. ATTENTION::
+   Since ``v0.37``, GHDL's synthesis features require GCC >=8.1, due to some new GNAT features which are not available in
+   previous releases. Users with older versions (who don't need synthesis) can configure GHDL with option ``--disable-synth``.
+
+GHDL currently supports three different back-ends (code generators):
+
+* mcode - built-in in-memory 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                                            |                                                         |
+|                            | * Base simulation time can be modified for speeding up execution           |                                                         |
++----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+
+| :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  |
++----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+
+
+.. 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:Simulation`.
+
+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 straightaway. MINGW/MSYS2 builds depend on the environment/runtime. See :ghdlsharp:`1560`.
+
+.. HINT ::
+  For MacOS 10.15 (Catalina), see :ghdlsharp:`1368` for workarounds to link failures.
+
+TL;DR
+=====
+
+In order to follow the traditional way to ``configure`` and ``make``, you need an Ada compiler.
+
+.. HINT::
+  Depending on the OS and distribution you are using, you will also need to install some toolchain dependencies, such as
+  ``zlib``.
+
+To use mcode backend (easiest to build), in the GHDL base directory, configure and build:
+
+.. code-block::
+
+  $ ./configure --prefix=/usr/local
+  $ make
+
+At that place, you can already use the `ghdl_mcode` built in the directory. You can also install GHDL:
+
+.. code-block::
+
+  $ make install
+
+That's all!
+
+.. HINT::
+  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``.
diff --git a/doc/development/building/mcode.rst b/doc/development/building/mcode.rst
new file mode 100644
index 000000000..9e46a29b6
--- /dev/null
+++ b/doc/development/building/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::
+
+   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