More restructuring.

7 files changed, 247 insertions, 144 deletions

diff --git a/doc/building/PrecompileVendorPrimitives.rst b/doc/building/PrecompileVendorPrimitives.rst
index 2495055b0..d0bf55394 100644
--- a/doc/building/PrecompileVendorPrimitives.rst
+++ b/doc/building/PrecompileVendorPrimitives.rst
@@ -236,7 +236,7 @@ Selectable Options for the Bash Scripts:
 
 * Common parameters to most scripts:
   
-  .. code-block::
+  .. code-block:: raw
 	
      -h --help             Print the embedded help page(s).
      -c --clean            Cleanup directory before analyzing.
@@ -247,126 +247,186 @@ Selectable Options for the Bash Scripts:
 
 * `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:
+  Selectable libraries:
+  
+  .. code-block:: raw
 
-           --vhdl93           Compile selected libraries with VHDL-93 (default).
-           --vhdl2008         Compile selected libraries with VHDL-2008.
+     -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-xilinx-ise.sh`
+   Compile options:
+  
+   .. code-block:: raw
+	
 
-    Selectable libraries:
+        --vhdl93           Compile selected libraries with VHDL-93 (default).
+        --vhdl2008         Compile selected libraries with VHDL-2008.
 
-        -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:
+* `compile-xilinx-ise.sh`
 
-           --vhdl93           Compile selected libraries with VHDL-93 (default).
-           --vhdl2008         Compile selected libraries with VHDL-2008.
+  Selectable libraries:
+  
+  .. code-block:: raw
+	
+     -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:
+  
+  .. code-block:: raw
+	
+        --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:
+  Selectable libraries:
+  
+  .. code-block:: raw
+	
+     -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
 
-           --vhdl93           Compile selected libraries with VHDL-93 (default).
-           --vhdl2008         Compile selected libraries with VHDL-2008.
+  Compile options:
+  
+  .. code-block:: raw
+	
+        --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.
+  Selectable libraries:
+  
+  .. code-block:: raw
+	
+     -a --all              Compile all.
+        --osvvm            Compile the OSVVM library.
 
 * `compile-vunit.sh`
 
-    Selectable libraries:
+  Selectable libraries:
+  
+  .. code-block:: raw
+	
+     -a --all              Compile all.
+        --osvvm            Compile the VUnit library.
+
+* `compile-uvvm.sh`
+
+  Selectable libraries:
+  
+  .. code-block:: raw
+	
+     -a --all              Compile all.
+        --uvvm             Compile the VUnit library.
 
-        -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.
+  
+  .. code-block:: raw
+	
+     -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:
+  Selectable libraries:
+  
+  .. code-block:: raw
+	
+     -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
 
-        -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:
+  Compile options:
+		
+  .. code-block:: raw
 
-        -VHDL93              Compile selected libraries with VHDL-93 (default).
-        -VHDL2008            Compile selected libraries with VHDL-2008.
+     -VHDL93               Compile selected libraries with VHDL-93 (default).
+     -VHDL2008             Compile selected libraries with VHDL-2008.
 
 * `compile-xilinx-ise.ps1`
 
-		Selectable libraries:
+  Selectable libraries:
+  
+  .. code-block:: raw
+
+     -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
 
-        -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:
+  Compile options:
+  
+  .. code-block:: raw
 
-        -VHDL93              Compile selected libraries with VHDL-93 (default).
-        -VHDL2008            Compile selected libraries with VHDL-2008.
+     -VHDL93               Compile selected libraries with VHDL-93 (default).
+     -VHDL2008             Compile selected libraries with VHDL-2008.
 
 * `compile-xilinx-vivado.ps1`
 
-    Selectable libraries:
+  Selectable libraries:
+  
+  .. code-block:: raw
 
-        -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:
+     -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
 
-        -VHDL93              Compile selected libraries with VHDL-93 (default).
-        -VHDL2008            Compile selected libraries with VHDL-2008.
+  Compile options:
+  
+  .. code-block:: raw
+
+     -VHDL93               Compile selected libraries with VHDL-93 (default).
+     -VHDL2008             Compile selected libraries with VHDL-2008.
 
 * `compile-osvvm.ps1`
 
-    Selectable libraries:
+  Selectable libraries:
+  
+  .. code-block:: raw
 
-        -All                  Compile all.
-        -OSVVM  		          Compile the OSVVM library.
+     -All                  Compile all.
+     -OSVVM  		           Compile the OSVVM library.
 
 * `compile-vunit.ps1`
 
-    Selectable libraries:
+  Selectable libraries:
+  
+  .. code-block:: raw
+
+     -All                  Compile all.
+     -VUnit  		           Compile the VUnit library.
+
+* `compile-uvvm.ps1`
+
+  Selectable libraries:
+  
+  .. code-block:: raw
 
-        -All                  Compile all.
-        -VUnit  		          Compile the VUnit library.
+     -All                  Compile all.
+     -UVVM  		           Compile the UVVM libraries.
 
 --------------------------------------------------------------------------------
 
diff --git a/doc/building/gcc/GNULinux-GNAT.rst b/doc/building/gcc/GNULinux-GNAT.rst
index d72de34a2..e35768fdb 100644
--- a/doc/building/gcc/GNULinux-GNAT.rst
+++ b/doc/building/gcc/GNULinux-GNAT.rst
@@ -24,3 +24,35 @@ On Linux, GHDL is configured by ``configure`` and build by ``make``.
    ../configure --prefix=PREFIX
    make
    sudo make install
+
+.. TODO::
+   - 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
+   
\ No newline at end of file
diff --git a/doc/building/gcc/Windows-MinGW-GNAT.rst b/doc/building/gcc/Windows-MinGW-GNAT.rst
new file mode 100644
index 000000000..0ba1526bb
--- /dev/null
+++ b/doc/building/gcc/Windows-MinGW-GNAT.rst
@@ -0,0 +1,30 @@
+.. _BUILD:gcc:Windows-MinGW-GNAT:
+
+GHDL with GCC backend build 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
index 73c9d1e97..377392681 100644
--- a/doc/building/gcc/index.rst
+++ b/doc/building/gcc/index.rst
@@ -6,20 +6,20 @@ GCC Backend
 .. rubric:: Requirements
 
 * GCC (Gnu Compiler Collection)
+* GCC source files
 * 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>`
+* :ref:`GNU/Linux with GCC <BUILD:gcc:GNULinux-GNAT>`
+* :ref:`Windows (x86_64) with MinGW32/MinGW64 <BUILD:gcc:Windows-WinGW-GNAT>`
 
 .. toctree::
    :hidden:
 
-   GNULinux-GNAT
-   Windows-WinGW
+   GNU/Linux with GCC/GNAT <GNULinux-GNAT>
+   Windows with GCC/GNAT (MinGW) <Windows-MinGW-GNAT>
 
 	 
 	 
@@ -35,46 +35,9 @@ GCC Backend
 		$ 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
diff --git a/doc/building/llvm/GNULinux-GNAT.rst b/doc/building/llvm/GNULinux-GNAT.rst
index d72de34a2..b0f26b991 100644
--- a/doc/building/llvm/GNULinux-GNAT.rst
+++ b/doc/building/llvm/GNULinux-GNAT.rst
@@ -24,3 +24,15 @@ On Linux, GHDL is configured by ``configure`` and build by ``make``.
    ../configure --prefix=PREFIX
    make
    sudo make install
+
+
+.. TODO::
+   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`.
+
diff --git a/doc/building/llvm/Windows-MinGW-GNAT.rst b/doc/building/llvm/Windows-MinGW-GNAT.rst
new file mode 100644
index 000000000..1329b80a1
--- /dev/null
+++ b/doc/building/llvm/Windows-MinGW-GNAT.rst
@@ -0,0 +1,26 @@
+.. _BUILD:llvm:Windows-MinGW-GNAT:
+
+GHDL with LLVM 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/llvm/index.rst b/doc/building/llvm/index.rst
index a2faf9d74..4f60cd083 100644
--- a/doc/building/llvm/index.rst
+++ b/doc/building/llvm/index.rst
@@ -19,32 +19,12 @@ LLVM Backend
 
 .. rubric:: Supported platforms
 
-* :ref:`GNU/Linux with GCC <BUILD:mcode:GNULinux-GCC>`
-* :ref:`Windows (x86_64) with MinGW32/MinGW64 <BUILD:mcode:Windows-WinGW>`
+* :ref:`GNU/Linux with GCC <BUILD:llvm:GNULinux-GNAT>`
+* Mac OS
+* :ref:`Windows (x86_64) with MinGW32/MinGW64 <BUILD:llvm:Windows-WinGW-GNAT>`
 
 .. 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
+   GNU/Linux with GCC/GNAT <GNULinux-GNAT>
+   Windows with GCC/GNAT (MinGW) <Windows-MinGW-GNAT>