3 files changed, 77 insertions, 34 deletions
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: