fix doc/building

12 files changed, 137 insertions, 95 deletions

diff --git a/doc/building/Building.rst b/doc/building/Building.rst
index f8f939c57..b06548157 100644
--- a/doc/building/Building.rst
+++ b/doc/building/Building.rst
@@ -61,3 +61,13 @@ created.
    (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 ``gcc-ada`` or ``gcc-gnat``.
+
+.. 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 ...
diff --git a/doc/building/Directories.rst b/doc/building/Directories.rst
index 36c0f2d9e..94fcf49d5 100644
--- a/doc/building/Directories.rst
+++ b/doc/building/Directories.rst
@@ -14,7 +14,7 @@ Directory Structure
     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 ``libraries/vendor``.
-    See Vendor Primitives <VendorPrimitives.html> for information on how to
+    See :ref:`GETTING:PrecompVendor` for information on how to
     use them.
 
 * ``dist``: scripts and auxiliar files to build GHDL in different
diff --git a/doc/building/gcc/GNULinux-GNAT.rst b/doc/building/gcc/GNULinux-GNAT.rst
index 3733d763f..a8617449d 100644
--- a/doc/building/gcc/GNULinux-GNAT.rst
+++ b/doc/building/gcc/GNULinux-GNAT.rst
@@ -1,26 +1,38 @@
-.. _BUILD:mcode:GNULinux-GNAT:
+.. _BUILD:gcc:GNULinux-GNAT:
 
-GNU/Linux with GCC/GNAT
-#######################
+GCC Backend on GNU/Linux with GCC/GNAT
+######################################
 
-On Linux, GHDL is configured by ``configure`` and build by ``make``.
+.. HINT:: There are some dependencies for building GCC (``gmp``, ``mpfr`` and ``mpc``). If you have not them installed 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, 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.
+* First configure GHDL, specify GCC source directory and ``PREFIX`` (installation directory like  ``/usr/local`` or ``/opt/ghdl``).
+* Next, invoke ``make`` 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.
 
-* Next, ``make`` starts the compilation process.
+* Now, build and install GCC with ``make``.
 
-* Finally, ``make install`` installs GHDL into the installation directory
-  specified by PREFIX. You may need super user privileges (``sudo ...``).
+* Last, build and install GHDL libraries.
 
 .. rubric:: Example:
 
 .. code-block:: Bash
 
-   cd <ghdl>
-   mkdir build
-   cd build
-   ../configure --prefix=PREFIX
-   make
-   sudo make install
+ $ cd <ghdl>
+ $ mkdir build
+ $ cd build
+ $ ../configure --with-gcc=/path/to/gcc/source/dir --prefix=PREFIX
+ $ 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
+ $ make ghdllib
+ $ make install
+
+.. HINT:: Note that the prefix directory 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=false`` instead.
diff --git a/doc/building/gcc/Windows-MinGW-GNAT.rst b/doc/building/gcc/Windows-MinGW-GNAT.rst
index 0ba1526bb..09274a534 100644
--- a/doc/building/gcc/Windows-MinGW-GNAT.rst
+++ b/doc/building/gcc/Windows-MinGW-GNAT.rst
@@ -1,30 +1,30 @@
 .. _BUILD:gcc:Windows-MinGW-GNAT:
 
-GHDL with GCC backend build on Windows with GCC/GNAT (MinGW)
-############################################################
+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
+
+      $ 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 c17775e23..2b6e33c8c 100644
--- a/doc/building/gcc/index.rst
+++ b/doc/building/gcc/index.rst
@@ -3,17 +3,48 @@
 GCC Backend
 ###########
 
+.. HINT::
+
 .. rubric:: Requirements
 
 * GCC (Gnu Compiler Collection)
-* GCC source files
 * 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
 
-* :ref:`GNU/Linux with GCC <BUILD:gcc:GNULinux-GNAT>`
-* :ref:`Windows (x86_64) with MinGW32/MinGW64 <BUILD:gcc:Windows-WinGW-GNAT>`
+* :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 grt.links           # Locally install the GHDL runtime
+
+  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
+
+.. HINT :: 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),
 
 .. toctree::
    :hidden:
diff --git a/doc/building/llvm/GNULinux-GNAT.rst b/doc/building/llvm/GNULinux-GNAT.rst
index 3733d763f..5f97c99b7 100644
--- a/doc/building/llvm/GNULinux-GNAT.rst
+++ b/doc/building/llvm/GNULinux-GNAT.rst
@@ -1,26 +1,23 @@
-.. _BUILD:mcode:GNULinux-GNAT:
+.. _BUILD:llvm:GNULinux-GNAT:
 
-GNU/Linux with GCC/GNAT
-#######################
+LLVM Backend on GNU/Linux with GCC/GNAT
+#######################################
 
-On Linux, GHDL is configured by ``configure`` and build by ``make``.
+.. HINT:: You need to install LLVM (usually depends on ``libedit``, see :ghdlsharp:`29`). The supported versions are 3.5 till 5.0, but debugging is only supported with LLVM 3.5.
 
-* 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.
+* 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``.
 
-* 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 ...``).
+* Then, build with ``make`` and install with ``make install``.
 
 .. rubric:: Example:
 
 .. code-block:: Bash
 
-   cd <ghdl>
-   mkdir build
-   cd build
-   ../configure --prefix=PREFIX
-   make
-   sudo make install
+   $ 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
index 1329b80a1..0fce8f068 100644
--- a/doc/building/llvm/Windows-MinGW-GNAT.rst
+++ b/doc/building/llvm/Windows-MinGW-GNAT.rst
@@ -1,7 +1,7 @@
 .. _BUILD:llvm:Windows-MinGW-GNAT:
 
-GHDL with LLVM backend build on Windows with GCC/GNAT (MinGW)
-#############################################################
+LLVM Backend on Windows with GCC/GNAT (MinGW)
+#############################################
 
 On Windows with MinGW, GHDL is configured by ``configure`` and build by ``make``.
 
@@ -17,10 +17,10 @@ On Windows with MinGW, GHDL is configured by ``configure`` and build by ``make``
 .. rubric:: Example:
 
 .. code-block:: Bash
-   
-   cd <ghdl>
-   mkdir build
-   cd build
-   ../configure --prefix=PREFIX
-   make
-   make install
+
+   $ 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 9f0bcc98a..dd01a8043 100644
--- a/doc/building/llvm/index.rst
+++ b/doc/building/llvm/index.rst
@@ -7,15 +7,7 @@ LLVM Backend
 
 * GCC (Gnu Compiler Collection)
 * GNAT (Ada compiler for GCC)
-* LLVM (Low-Level-Virtual Machine)
-
-  * 3.5
-  * 3.8
-  * 3.9
-  * 4.0
-  * 5.0
-
-* CLANG (Compiler front-end for LLVM)
+* LLVM (Low-Level-Virtual Machine) and CLANG (Compiler front-end for LLVM)
 
   * 3.5
   * 3.8
@@ -25,9 +17,9 @@ LLVM Backend
 
 .. rubric:: Supported platforms
 
-* :ref:`GNU/Linux with GCC <BUILD:llvm:GNULinux-GNAT>`
+* :doc:`GNULinux-GNAT`
+* :doc:`Windows-MinGW-GNAT`
 * Mac OS
-* :ref:`Windows (x86_64) with MinGW32/MinGW64 <BUILD:llvm:Windows-WinGW-GNAT>`
 
 .. toctree::
    :hidden:
diff --git a/doc/building/mcode/GNULinux-GNAT.rst b/doc/building/mcode/GNULinux-GNAT.rst
index 8443c254f..2c75efa96 100644
--- a/doc/building/mcode/GNULinux-GNAT.rst
+++ b/doc/building/mcode/GNULinux-GNAT.rst
@@ -1,7 +1,7 @@
 .. _BUILD:mcode:GNULinux-GNAT:
 
-GHDL with mcode backend build on GNU/Linux with GCC/GNAT
-########################################################
+mcode Backend on GNU/Linux with GCC/GNAT
+########################################
 
 On Linux, GHDL is configured by ``configure`` and build by ``make``.
 
@@ -18,10 +18,10 @@ On Linux, GHDL is configured by ``configure`` and build by ``make``.
 .. rubric:: Example:
 
 .. code-block:: Bash
-   
-   cd <ghdl>
-   mkdir build
-   cd build
-   ../configure --prefix=PREFIX
-   make
-   sudo make install
+
+   $ 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
index d17fe11a8..c767343be 100644
--- a/doc/building/mcode/Windows-GNATGPL.rst
+++ b/doc/building/mcode/Windows-GNATGPL.rst
@@ -1,7 +1,7 @@
 .. _BUILD:mcode:Windows-GNATGPL:
 
-GHDL with mcode backend build on Windows with GNAT GPL
-######################################################
+mcode Backend on Windows with GNAT GPL
+######################################
 
 Requirements
 ============
diff --git a/doc/building/mcode/Windows-MinGW-GNAT.rst b/doc/building/mcode/Windows-MinGW-GNAT.rst
index 874807bcf..960ced421 100644
--- a/doc/building/mcode/Windows-MinGW-GNAT.rst
+++ b/doc/building/mcode/Windows-MinGW-GNAT.rst
@@ -1,7 +1,7 @@
 .. _BUILD:mcode:Windows-MinGW-GNAT:
 
-GHDL with mcode backend build on Windows with GCC/GNAT (MinGW)
-##############################################################
+mcode Backend on Windows with GCC/GNAT (MinGW)
+##############################################
 
 On Windows with MinGW, GHDL is configured by ``configure`` and build by ``make``.
 
@@ -17,10 +17,10 @@ On Windows with MinGW, GHDL is configured by ``configure`` and build by ``make``
 .. rubric:: Example:
 
 .. code-block:: Bash
-   
-   cd <ghdl>
-   mkdir build
-   cd build
-   ../configure --prefix=PREFIX
-   make
-   make install
+
+   $ 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
index 7d850c4a3..0b081392a 100644
--- a/doc/building/mcode/index.rst
+++ b/doc/building/mcode/index.rst
@@ -16,9 +16,9 @@ options.
 
 .. 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>`
+* :doc:`GNULinux-GNAT`
+* :doc:`Windows-GNATGPL`
+* :doc:`Windows-MinGW-GNAT`
 
 .. toctree::
    :hidden: