Restructured build section. Created smaller files. Created (hidden) sub-ToCs. Added out-dated build instructions for Windows GNAT GPL flow from private README.md.

12 files changed, 815 insertions, 0 deletions

diff --git a/doc/building/Building.rst b/doc/building/Building.rst
new file mode 100644
index 000000000..92e2de96f
--- /dev/null
+++ b/doc/building/Building.rst
@@ -0,0 +1,54 @@
+.. _BUILD:
+
+Building GHDL
+#############
+
+GHDL currently supports three supported different backends (code generators): `mcode` (built-in), `GCC <http://gcc.gnu.org/>`_ and `LLVM <http://llvm.org/>`_ . Here is a short comparison, so that you can choose the one you want to use:
+
++------------------------+------------------------------------------------------------------------------------------+---------------------------------------------------------+
+|                        | pros                                                                                     | cons                                                    |
++========================+==========================================================================================+=========================================================+
+| `mcode`                | - very easy to build                                                                     | - :samp:`x86_64`/:samp:`i386` only                      |
+|                        | - very quick analysis                                                                    | - simulation is slower                                  |
+|                        | - can handle very large designs                                                          |                                                         |
++------------------------+------------------------------------------------------------------------------------------+---------------------------------------------------------+
+| GCC                  | - generated code is faster (particularly with :samp:`-O` or :samp:`-O2`)                 | - analysis can take time (particularly for large units) |
+|                        | - generated code can be debugged (with :samp:`-g`)                                       | - build is more complex                                 |
+|                        | - ported to many platforms (:samp:`x86`, :samp:`x86_64`, :samp:`powerpc`, :samp:`sparc`) |                                                         |
++------------------------+------------------------------------------------------------------------------------------+---------------------------------------------------------+
+| LLVM                 | - Same as GCC                                                                          | Coverage, :samp:`gcov`, is unique to GCC              |
+|                        | - Easier to build than 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 :samp:`-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 below. However, we suggest you to read :ref:`BUILD:dir_structure` before, so that you know where the content is placed and which temporal 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 :samp:`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. Alternatively, most GNU/Linux provide a package named :samp:`gcc-ada` or :samp:`gcc-gnat`.
+
+.. TODO::
+
+   * @1138 Backtraces optional -patchable-
+   * Very briefly, why is mcode faster for analysis and GCC/LLVM for simulation?
+   * The only other dependency is zlib (On ubuntu/debian, install zlib1g-dev).
+   * From :ghdlsharp:`279`:
+   * GCC: GHDL generates an intermediate representation for GCC, which creates an executable. So GHDL acts a a new language frontend like C for the GCC and uses the existing backend to generated e.g. x86(-64) binary code.
+   * LLVM: GHDL generates instructions for the LLVM abstract register machine, which then generates x86(-64) instructions for the host system.
+   * mcode: GHDL generates the x86(-64) instructions in memory and executes the model.
+     * gcc is currently only supported on Linux, because you need to compile a complete GCC from zero and add GHDL as a frontend into the GCC. Compiling the complete GCC suite plus GHDL takes a lot of time. I think it's not possible to finish the compile task in the bounds of a Travis-CI run.
+  
+
+GHDL can be build with three different back-ends: mcode, LLVM or GCC.
+
+* :ref:`mcode <BUILD:mcode>`
+* :ref:`LLVM <BUILD:llvm>`
+* :ref:`GCC <BUILD:gcc>`
+
+.. toctree::
+   :hidden:
+   
+   Directories
+   With mcode Backend <mcode/index>
+   With LLVM Backend <llvm/index>
+   With GCC Backend <gcc/index>
+   TestSuites
diff --git a/doc/building/Directories.rst b/doc/building/Directories.rst
new file mode 100644
index 000000000..e7b054a7d
--- /dev/null
+++ b/doc/building/Directories.rst
@@ -0,0 +1,59 @@
+.. _BUILD:dir_structure:
+
+Directory Structure
+###################
+
+* :samp:`src`: sources of GHDL, all of them in Ada.
+
+* :samp:`libraries`: mostly third party libraries such as, `ieee`, `mentor`,
+  `std`, `synopsys` and `vital`. Except 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 can
+    not 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 :samp:`libraries/vendor`.
+    See Vendor Primitives <VendorPrimitives.html> for information on how to
+    use them.
+	
+* :samp:`dist`: scripts and auxiliar files to build GHDL in different
+  environments:
+  
+  * :samp:`gcc`: header and configuration files to build GHDL with GCC (all the
+    platforms).
+  * :samp:`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/>`_.
+  
+  * :samp:`windows`:
+    
+    * :samp:`mcode`:
+    * :samp:`appveyor`: 
+  	
+* :samp:`doc`: `Markdown` and `reStructuredText` sources and auxiliary files to
+  build the documentation with `Sphinx <http://www.sphinx-doc.org>`_. Indeed,
+  `Read the docs <http://readthedocs.org>`_ (RTD) is used to automatically build
+  and deploy this site and/or PDF you are reading.
+
+* :samp:`testsuite`: see section :ref:`test_suites`.
+
+* `.yml` configuration files for CI environments (:samp:`readthedocs`,
+  :samp:`travis` and :samp:`appveyor`) and `ignore` files for source control
+  management tools (:samp:`git` and :samp:`.hg`).
+
+* Files for building GHDL: :samp:`configure` and :samp:`Makefile.in`.
+
+* Auxiliar files for development: :samp:`.gdbinit` and :samp:`ghdl.gpr.in`
+  (GNAT project file).
+
+* Text files: :samp:`COPYING.md`, :samp:`NEWS.md` and :samp:`README.md`.
+
+
+.. TODO::
+
+	- [@1138-4EB|@Paebbels] Replace link to VendorPrimitives, when the file is translated from md to rst.
+	
+	- [@Paebbels] Add brief description of how the content in dist/windows is ordered. From :ghdlsharp:`279`:
+		- The content in dist/appveyor is for the AppVeyor flow. AppVeyor is a continuous integration service like Travis-CI, but is offers a Windows Server 2012 R2 machine. The AppVeyor flow has more scripts than the Travis-CI flow, so we put them into a separate directory.
+		- The code in dist/windows/mcode is special code needed to build mcode in windows. mcode is supported on Linux (32/64-bit) and Windows (32-bit).
diff --git a/doc/building/PrecompileVendorPrimitives.rst b/doc/building/PrecompileVendorPrimitives.rst
new file mode 100644
index 000000000..2495055b0
--- /dev/null
+++ b/doc/building/PrecompileVendorPrimitives.rst
@@ -0,0 +1,380 @@
+.. _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 can not
+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]_, VUnit
+[#f2]_ 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
+
+* VUnit (for VHDL-2008)
+
+    * vunit_lib
+
+* UVVM (for VHDL-2008)
+
+  * 
+
+---------------------------------------------------------------------
+
+Script Configuration
+====================
+
+The vendor library compile scripts need to know where the used / latest vendor
+tool chain is installed. Therefore, the script implement a default installation
+directory search as well as environment variable checks. If a vendor tool could
+not be detected or the script choses 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 to configure
+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 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-vunit.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 Nov 30 17:41 altera
+    drwxr-xr-x  2 <user> <group>  56K Nov 30 17:42 lattice
+    drwxr-xr-x  2 <user> <group>  56K Nov 30 17:48 osvvm
+    drwxr-xr-x  2 <user> <group>  56K Nov 30 17:58 vunit
+    drwxr-xr-x  2 <user> <group>  56K Nov 30 17:58 xilinx-ise
+    drwxr-xr-x  2 <user> <group>  56K Nov 30 17:48 xilinx-vivado
+    ```
+
+
+---------------------------------------------------------------------
+
+Compiling on Windows
+====================
+
+* **Step 0 - Configure the scripts (optional)**
+
+  See 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-vunit.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----    20.11.2015    19:33        <DIR> altera
+     d----    20.11.2015    19:38        <DIR> lattice
+     d----    20.11.2015    19:38        <DIR> osvvm
+     d----    20.11.2015    19:45        <DIR> vunit_lib
+     d----    20.11.2015    19:06        <DIR> xilinx-ise
+     d----    20.11.2015    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 the appropriate directory 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/16.0"
+   InstallationDirectory[LatticeDiamond]="/opt/Diamond/3.8_x64"
+   InstallationDirectory[OSVVM]="/home/<user>/git/GitHub/osvvm"
+   InstallationDirectory[VUnit]="/home/<user>/git/GitHub/vunit"
+   InstallationDirectory[XilinxISE]="/opt/Xilinx/14.7"
+   InstallationDirectory[XilinxVivado]="/opt/Xilinx/Vivado/2016.3"
+
+
+For Windows: `config.psm1`
+--------------------------
+
+Please open the `config.psm1` file and set the dictionary entries for the
+installed vendor tools to the appropriate directory to your tool's installation
+folder. Use an empty string `""` for not installed tools.
+
+`config.psm1`:
+
+.. code-block:: PowerShell
+
+   $InstallationDirectory = @{
+     "AlteraQuartus" =   "C:\Altera\16.0";
+     "LatticeDiamond" =  "C:\Lattice\Diamond\3.8_x64";
+     "XilinxISE" =       "C:\Xilinx\14.7\ISE_DS";
+     "XilinxVivado" =    "C:\Xilinx\Vivado\2016.3";
+     "OSVVM" =           "D:\git\GitHub\osvvm";
+     "VUnit" =           "D:\git\GitHub\vunit"
+   }
+
+
+Selectable Options for the Bash Scripts:
+----------------------------------------
+
+*First I should translate the scripts before writing the docu...*
+
+* Common parameters to most scripts:
+  
+  .. code-block::
+	
+     -h --help             Print the embedded help page(s).
+     -c --clean            Cleanup directory before analyzing.
+     -n --no-warnings	     Don't show warnings. Report errors only.
+     -s --skip-existing    Skip already compiled files (an *.o file exists).
+     -S --skip-largefiles  Don't compile large entities like DSP and PCIe primitives.
+     -H --halt-on-error    Stop compiling if an error occured.
+
+* `compile-altera.sh`
+
+   Selectable libraries:
+
+        -a --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:
+
+           --vhdl93           Compile selected libraries with VHDL-93 (default).
+           --vhdl2008         Compile selected libraries with VHDL-2008.
+
+* `compile-xilinx-ise.sh`
+
+    Selectable libraries:
+
+        -a --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:
+
+           --vhdl93           Compile selected libraries with VHDL-93 (default).
+           --vhdl2008         Compile selected libraries with VHDL-2008.
+
+* `compile-xilinx-vivado.sh`
+
+    Selectable libraries:
+
+        -a --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:
+
+           --vhdl93           Compile selected libraries with VHDL-93 (default).
+           --vhdl2008         Compile selected libraries with VHDL-2008.
+
+* `compile-osvvm.sh`
+
+    Selectable libraries:
+
+        -a --all              Compile all.
+           --osvvm            Compile the OSVVM library.
+
+* `compile-vunit.sh`
+
+    Selectable libraries:
+
+        -a --all              Compile all.
+           --osvvm            Compile the VUnit library.
+
+Selectable Options for the PowerShell Scripts:
+----------------------------------------------
+
+* Common parameters to all scripts:
+
+        -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:
+
+        -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:
+
+        -VHDL93              Compile selected libraries with VHDL-93 (default).
+        -VHDL2008            Compile selected libraries with VHDL-2008.
+
+* `compile-xilinx-ise.ps1`
+
+		Selectable libraries:
+
+        -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:
+
+        -VHDL93              Compile selected libraries with VHDL-93 (default).
+        -VHDL2008            Compile selected libraries with VHDL-2008.
+
+* `compile-xilinx-vivado.ps1`
+
+    Selectable libraries:
+
+        -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:
+
+        -VHDL93              Compile selected libraries with VHDL-93 (default).
+        -VHDL2008            Compile selected libraries with VHDL-2008.
+
+* `compile-osvvm.ps1`
+
+    Selectable libraries:
+
+        -All                  Compile all.
+        -OSVVM  		          Compile the OSVVM library.
+
+* `compile-vunit.ps1`
+
+    Selectable libraries:
+
+        -All                  Compile all.
+        -VUnit  		          Compile the VUnit library.
+
+--------------------------------------------------------------------------------
+
+.. container:: footnotes
+
+	 .. rubric:: Footnotes
+
+   .. [#f1] OSVVM http://github.com/OSVVM/OSVVM
+   .. [#f2] VUnit https://github.com/VUnit/vunit
+   .. [#f3] UVVM https://github.com/UVVM/UVVM_All
+   .. [#f4] Generic Colourizer http://kassiopeia.juls.savba.sk/~garabik/software/grc.html
diff --git a/doc/building/TestSuites.rst b/doc/building/TestSuites.rst
new file mode 100644
index 000000000..b4d8807a2
--- /dev/null
+++ b/doc/building/TestSuites.rst
@@ -0,0 +1,11 @@
+.. _BUILD:testsuites:
+	
+Test Suites
+===========
+
+.. TODO::
+
+   * @1138 explain that there are two (maybe three with vhdl08 tests)
+   	 * :samp:`--expect-failure    invert exit status`
+   * :samp:`--has-feature=X       test presence of feature X`
+   * :samp:`--list-features       display the list of features`
diff --git a/doc/building/gcc/GNULinux-GNAT.rst b/doc/building/gcc/GNULinux-GNAT.rst
new file mode 100644
index 000000000..d72de34a2
--- /dev/null
+++ b/doc/building/gcc/GNULinux-GNAT.rst
@@ -0,0 +1,26 @@
+.. _BUILD:mcode:GNULinux-GNAT:
+
+GNU/Linux with GCC/GNAT
+#######################
+
+On Linux, 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. You may need super user privileges (``sudo ...``).
+
+.. rubric:: Example:
+
+.. code-block:: Bash
+   
+   cd <ghdl>
+   mkdir build
+   cd build
+   ../configure --prefix=PREFIX
+   make
+   sudo make install
diff --git a/doc/building/gcc/index.rst b/doc/building/gcc/index.rst
new file mode 100644
index 000000000..73c9d1e97
--- /dev/null
+++ b/doc/building/gcc/index.rst
@@ -0,0 +1,92 @@
+.. _BUILD:gcc:
+
+GCC Backend
+###########
+
+.. rubric:: Requirements
+
+* GCC (Gnu Compiler Collection)
+* GNAT (Ada compiler for GCC)
+
+
+.. rubric:: Supported platforms
+
+* :ref:`GNU/Linux with GCC <BUILD:mcode:GNULinux-GCC>`
+* :ref:`Windows (x86_64) with GNAT GPL (x86) <BUILD:mcode:Windows-GNATGPL>`
+* :ref:`Windows (x86_64) with MinGW32/MinGW64 <BUILD:mcode:Windows-WinGW>`
+
+.. toctree::
+   :hidden:
+
+   GNULinux-GNAT
+   Windows-WinGW
+
+	 
+	 
+.. TODO::
+
+	- You need to download and untar the sources of GCC version 4.9.x, 5.x or 6.x
+	- gcc object dir
+	- Notes for developpers developping with the GCC backend: 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 grt.links           # Locally install the GHDL runtime	
+
+GNU/Linux
+---------
+
+- First configure GHDL, specify GCC source dir and :samp:`prefix` (replace :samp:`/usr/local` with your desired installation directory)::
+
+	./configure --with-gcc=/path/to/gcc/source/dir --prefix=/usr/local
+	
+- Then, invoke :samp:`make` to copy GHDL sources in the source dir::
+
+	make copy-sources
+
+.. HINT:: There are some dependencies for building GCC (:samp:`gmp`, :samp:`mpfr` and :samp:`mpc`). If you have not them installed on your system, you can either build them manually or use the :samp:`download_prerequisite` script provided in the GCC source tree (recommended): :samp:`cd /path/to/gcc/source/dir && ./contrib/download_prerequisites`
+
+- Then, configure GCC. The list of :samp:`--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::
+
+	../gcc-4.9.3/configure --prefix=/usr/local --enable-languages=c,vhdl \
+	--disable-bootstrap --disable-lto --disable-multilib --disable-libssp \
+	--disable-libgomp --disable-libquadmath ``.
+
+.. HINT:: Note that the prefix directory must be the same as the one used to configure GHDL. If you have manually built :samp:`gmp`/:samp:`mpfr`/:samp:`mpc` (without using the script in :samp:`contrib`) and if you have installed them in a non-standard directory, you may need to add :samp:`--with-gmp=GMP_INSTALL_DIR`.
+
+- Then, build and install GCC::
+
+	make -j2 && make install
+
+.. HINT:: If you don't want to install :samp:`makeinfo`, do :samp:`make install MAKEINFO=false` instead.
+
+- Last, build and install GHDL libraries::
+
+	cd /path/to/ghdl/source/dir
+	make ghdllib
+	make install
+
+Windows?
+--------
+
+.. TODO:
+
+    Since the content of BUILD.txt is moved to the docs, what shall we do with this line? +gcc version 6.3 [do not modify this line as this is read by scripts].
+
+	Note for ppc64 (and AIX ?) platform: the object file format contains an identifier for the source language. Because gcc doesn't know about the 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,
+
+	Install file for the binary distribution of GHDL. The binary are installed in /usr/local directory.  You cannot change this default location, unless you set links. You must be root to install this distribution. To install ghdl: `tar -C / -jxvf @TARFILE@.tar.bz2`. Note: you must also have a C compiler and zlib installed.
+	 
\ No newline at end of file
diff --git a/doc/building/llvm/GNULinux-GNAT.rst b/doc/building/llvm/GNULinux-GNAT.rst
new file mode 100644
index 000000000..d72de34a2
--- /dev/null
+++ b/doc/building/llvm/GNULinux-GNAT.rst
@@ -0,0 +1,26 @@
+.. _BUILD:mcode:GNULinux-GNAT:
+
+GNU/Linux with GCC/GNAT
+#######################
+
+On Linux, 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. You may need super user privileges (``sudo ...``).
+
+.. rubric:: Example:
+
+.. code-block:: Bash
+   
+   cd <ghdl>
+   mkdir build
+   cd build
+   ../configure --prefix=PREFIX
+   make
+   sudo make install
diff --git a/doc/building/llvm/index.rst b/doc/building/llvm/index.rst
new file mode 100644
index 000000000..a2faf9d74
--- /dev/null
+++ b/doc/building/llvm/index.rst
@@ -0,0 +1,50 @@
+.. _BUILD:llvm:
+
+LLVM Backend
+############
+
+.. rubric:: Requirements
+
+* GCC (Gnu Compiler Collection)
+* GNAT (Ada compiler for GCC)
+* LLVM (Low-Level-Virtual Machine)
+
+  * 3.5
+  * 3.8
+
+* CLANG (Compiler front-end for LLVM)
+
+  * 3.5
+  * 3.8
+
+.. rubric:: Supported platforms
+
+* :ref:`GNU/Linux with GCC <BUILD:mcode:GNULinux-GCC>`
+* :ref:`Windows (x86_64) with MinGW32/MinGW64 <BUILD:mcode:Windows-WinGW>`
+
+.. toctree::
+   :hidden:
+
+   GNULinux-GNAT
+   Windows-WinGW
+
+	 
+	 
+GNU/Linux
+---------
+
+You need to install LLVM (usually depends on :samp:`libedit`, see :ghdlsharp`29`). The supported versions are 3.5 till 3.9, but debugging is only supported with LLVM 3.5.
+
+- First configure GHDL with the proper arg :samp:`./configure --with-llvm-config`. If :samp:`llvm-config` is not in your path, you can specify it: :samp:`./configure --with-llvm-config=LLVM_INSTALL/bin/llvm-config`.
+
+.. HINT:: If you want to have stack backtraces on errors (like assert failure or index of out bounds), you need to configure and build :samp:`libbacktrace` from GCC (you don't need to configure GCC). Then add the following arg to configure: :samp:`--with-backtrace-lib=/path-to-gcc-build/libbacktrace/.libs/libbacktrace.a`
+
+- Then build with :samp:`make` and install with :samp:`make install`.
+  
+Mac OS?
+-------
+
+Windows MinGW 32/64
+-------------------
+	 
+	 
\ No newline at end of file
diff --git a/doc/building/mcode/GNULinux-GNAT.rst b/doc/building/mcode/GNULinux-GNAT.rst
new file mode 100644
index 000000000..8443c254f
--- /dev/null
+++ b/doc/building/mcode/GNULinux-GNAT.rst
@@ -0,0 +1,27 @@
+.. _BUILD:mcode:GNULinux-GNAT:
+
+GHDL with mcode backend build on GNU/Linux with GCC/GNAT
+########################################################
+
+On Linux, 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``. You may need super user privileges (``sudo ...``).
+
+
+.. rubric:: Example:
+
+.. code-block:: Bash
+   
+   cd <ghdl>
+   mkdir build
+   cd build
+   ../configure --prefix=PREFIX
+   make
+   sudo make install
diff --git a/doc/building/mcode/Windows-GNATGPL.rst b/doc/building/mcode/Windows-GNATGPL.rst
new file mode 100644
index 000000000..d17fe11a8
--- /dev/null
+++ b/doc/building/mcode/Windows-GNATGPL.rst
@@ -0,0 +1,36 @@
+.. _BUILD:mcode:Windows-GNATGPL:
+
+GHDL with mcode backend build 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
new file mode 100644
index 000000000..874807bcf
--- /dev/null
+++ b/doc/building/mcode/Windows-MinGW-GNAT.rst
@@ -0,0 +1,26 @@
+.. _BUILD:mcode:Windows-MinGW-GNAT:
+
+GHDL with mcode backend build on Windows with GCC/GNAT (MinGW)
+##############################################################
+
+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/mcode/index.rst b/doc/building/mcode/index.rst
new file mode 100644
index 000000000..3dc80c2f9
--- /dev/null
+++ b/doc/building/mcode/index.rst
@@ -0,0 +1,28 @@
+.. _BUILD:mcode:
+
+Mcode Backend
+#############
+
+The mcode backend is available for all supported platforms and is also the most
+simplest procedure, because it requires the least dependencies and configuration
+options.
+
+
+.. rubric:: Requirements
+
+* GCC (Gnu Compiler Collection)
+* GNAT (Ada compiler for GCC)
+
+
+.. rubric:: Supported platforms
+
+* :ref:`GNU/Linux with GCC <BUILD:mcode:GNULinux-GNAT>`
+* :ref:`Windows (x86_64) with GNAT GPL (x86) <BUILD:mcode:Windows-GNATGPL>`
+* :ref:`Windows (x86_64) with MinGW32/MinGW64 <BUILD:mcode:Windows-WinGW-GNAT>`
+
+.. toctree::
+   :hidden:
+
+   GNU/Linux with GCC/GNAT <GNULinux-GNAT>
+   Windows with GNAT GPL <Windows-GNATGPL>
+   Windows with GCC/GNAT (MinGW) <Windows-MinGW-GNAT>