Removed numbers from folder names.

2 files changed, 370 insertions, 0 deletions

diff --git a/doc/building/VendorPrimitives.rst b/doc/building/VendorPrimitives.rst
new file mode 100644
index 000000000..49c35b5a4
--- /dev/null
+++ b/doc/building/VendorPrimitives.rst
@@ -0,0 +1,328 @@
+.. _VENDOR:
+
+Vendor Primitives
+#############
+
+## Compile Scripts for Vendor VHDL Libraries
+
+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-compile, too.
+
+The compilation scripts are writen in the shell languages: PowerShell for Windows
+and Bash for 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 Quartus (≥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 (≥3.6):
+     - ec
+     - ecp, ecp2, ecp3, ecp5u
+     - lptm, lptm2
+     - machxo, machxo2, machxo3l
+     - sc, scm
+     - xp, xp2
+ - Xilinx ISE (≥14.0):
+     - unisim (incl. secureip)
+     - unimacro
+     - simprim (incl. secureip)
+     - xilinxcorelib
+ - Xilinx Vivado (≥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
+
+------------------------
+
+.. TODO: topic
+
+  - Vendor Primitives 
+    - Alters / Intel
+    - Lattice
+    - OSVVM
+    - UVVM
+    - Xilinx ISE
+    - Xilinx Vivado
diff --git a/doc/building/index.rst b/doc/building/index.rst
new file mode 100644
index 000000000..d240ff94d
--- /dev/null
+++ b/doc/building/index.rst
@@ -0,0 +1,42 @@
+.. _BUILD:
+
+Building GHDL
+#############
+
+.. TODO: topic
+
+  `./BUILD.txt <https://github.com/tgingold/ghdl/blob/master/BUILD.txt>`_
+  Directory structure of the main branch [1138: #279]
+  Coverage, `gcov`, is unique to gcc. That specific difference is not explained anywhere. Should be added.
+  @1138 Backtraces optional -patchable-
+
+GCC backend
+=================
+
+- ./dist/gcc/INSTALL
+- ./gcc/README
+- Linux
+
+LLVM backend 
+=================
+
+- Linux
+- Mac OS?
+- Windows MinGW 32/64
+	  
+Mcode backend
+=================
+
+- ./dist/mcode/README
+- Linux
+- Windows GNAT GPL (32 only)
+- Windows MinGW 32/64
+
+Test suites
+=================
+
+----------------
+
+.. TODO: topic
+
+  @1138 explain that there are two (maybe three with vhdl08 tests)
\ No newline at end of file