Add theme_overrrides.css

Move WhatIs* to About. Move About, Contributing and Copying to doc. Rename Copying to License. Append CC-BY-SA-4.0 legalcode to COPYING.md
Chapter Introduction ready for review.
Starting to rewrite Building

2 files changed, 471 insertions, 0 deletions

diff --git a/doc/getting/Building.rst b/doc/getting/Building.rst
new file mode 100644
index 000000000..c52d3f5da
--- /dev/null
+++ b/doc/getting/Building.rst
@@ -0,0 +1,166 @@
+.. _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.
+
+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).
+  
+.. _BUILD:dir_structure:
+  
+Directory structure
+=================
+
+.. TODO::
+
+  Directory structure of the main branch [1138: #279]
+  
+Mcode backend
+=================
+
+This is the most simple procedure, because it requires the least dependencies and configuration options.
+
+GNU/Linux
+----------------
+
+- First, execute :samp:`./configure --prefix=PREFIX`, where :samp:`PREFIX` is the directory for installation.
+- Then :samp:`make`, that builds the :samp:`ghdl_mcode` executable, which can be used as is.
+- Last, :samp:`make install` to install within :samp:`PREFIX`.
+- That's all!
+
+Windows MinGW 32/64
+----------------
+
+.. TODO:: For example, on Windows, you may want to set it to :samp:`--prefix=/c/Program Files (x86)/GHDL` .
+
+Windows GNAT GPL (32 only)
+----------------
+
+.. TODO::
+	Note: this was tested with Windows XP SP2 familly edition.
+	Note: If you want to create the installer, GHDL should be built on a FAT partition.  NSIS rounds files date to be FAT compliant (seconds are always even) and because GHDL stores dates, the files date must not be modified.
+	The Ada95 GNAT compiler (GNAT GPL 2005 is known to work), along with NSIS to create the installer. Then unzip, edit winbuild to use correct path for makensis, and run winbuild. The installer is in the windows directory.
+	   
+LLVM backend 
+=================
+
+GNU/Linux
+----------------
+
+You need to install `LLVM` (usually depends on :samp:`libedit`). 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
+----------------
+
+GCC backend
+=================
+
+.. TODO::
+
+	- You need to download and untar the sources of `GCC` version 4.9 [do not modify this line as this is read by scripts].
+	- 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.
+
+	
+Test suites
+=================
+
+.. TODO::
+
+  @1138 explain that there are two (maybe three with vhdl08 tests)
\ No newline at end of file
diff --git a/doc/getting/VendorPrimitives.md b/doc/getting/VendorPrimitives.md
new file mode 100644
index 000000000..3b9c9b11f
--- /dev/null
+++ b/doc/getting/VendorPrimitives.md
@@ -0,0 +1,305 @@
+## 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][osvvm] and [VUnit][vunit], 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` ([generic colourizer][grc]).
+
+- [osvvm]: http://osvvm.org/
+- [vunit]: https://github.com/LarsAsplund/vunit
+- [grc]: http://kassiopeia.juls.savba.sk/~garabik/software/grc.html
+
+##### Supported Vendors Libraries
+
+ - Altera/Intel Quartus (&ge;13.0):
+     - `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 (&ge;3.6):
+     - `ec`
+     - `ecp`, `ecp2`, `ecp3`, `ecp5u`
+     - `lptm`, `lptm2`
+     - `machxo`, `machxo2`, `machxo3l`
+     - `sc`, `scm`
+     - `xp`, `xp2`
+ - Xilinx ISE (&ge;14.0):
+     - `unisim` (incl. `secureip`)
+     - `unimacro`
+     - `simprim` (incl. `secureip`)
+     - `xilinxcorelib`
+ - Xilinx Vivado (&ge;2014.1):
+     - `unisim` (incl. `secureip`)
+     - `unimacro`
+
+##### Supported Simulation and Verification Libraries
+
+ - OSVVM (for VHDL-2008)
+     - osvvm
+ - VUnit (for VHDL-2008)
+     - vunit_lib
+
+---------------------------------------------------------------------
+### 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**
+    ```Bash
+    $ cd <MySimulationFolder>
+    ```
+
+ - **Step 2 - Start the compilation script(s)**
+    ```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.
+
+    ```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**
+    ```PowerShell
+    PS> cd <MySimulationFolder>
+    ```
+
+ - **Step 2 - Start the compilation script(s)**
+    ```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.
+
+    ```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`:
+```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`:
+```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:
+
+        -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.
+
+------------------------
+Author: Patrick Lehmann  
+Last update: 28.10.2016
+
+------------------------
\ No newline at end of file