Reworking pre-compile scripts for Windows (#1594)

* Updated pre-compile scripts for OSVVM.

* Reworked script for Vivado.

* Reworked script for ISE.

* Reworked UVVM compile script. Cannot be tested due to missing feature in GHDL see #1593.

* Reworked scripts for Altera, Intel and Lattice.

* Updated module imports.

* Adjusted warnings.

* Read OSVVM package files from compile-order file 'osvvm.pro'.

* Support OSVVM and OSVVMLibraries as source directory.

* Added support for OSVVM models to precompile script.

* First update to the pre-compile scripts documentation.

* Minimized file headers and redundant documentation. Using PowerShell's feature to document files, functions and modules.

* Updated README in precompile scripts directory.

* license: update headers of pyGHDL, scripts/windows, libraries/vendors

* Fixed ForegroundColor and InvocationName.

Co-authored-by: umarcor <unai.martinezcorral@ehu.eus>

1 files changed, 145 insertions, 113 deletions

diff --git a/doc/getting/PrecompileVendorPrimitives.rst b/doc/getting/PrecompileVendorPrimitives.rst
index 04a1010f8..aa322d3b7 100644
--- a/doc/getting/PrecompileVendorPrimitives.rst
+++ b/doc/getting/PrecompileVendorPrimitives.rst
@@ -3,73 +3,63 @@
 Precompile Vendor Primitives
 ############################
 
-Vendors like Altera, Lattice and Xilinx have their own simulation libraries,
+Vendors like Lattice, Intel (Altera) and Xilinx have their own simulation libraries,
 especially for FPGA primitives, soft and hard macros. These libraries cannot
-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 [#f1]_ or
-UVVM [#f3]_, which can be pre-compiled, too.
+be shipped with GHDL, but GHDL offers prepared compile scripts to pre-compile
+these vendor libraries, if the vendor tool is present in the environment. There
+are also popular simulation and verification libraries like OSVVM [#f1]_ or
+UVVM [#f2]_, 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` [#f4]_.
+*Windows™* and *Bash* for *GNU/Linux*, *MacOS*, *MSYS2*/*MinGW*. The
+compile scripts can colorize the GHDL warning and error lines with the help
+of ``grc/grcat`` [#f4]_.
 
 Supported Vendors Libraries
 ===========================
 
-* Altera/Intel Quartus (13.0 or later):
-
-  * `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 or later):
 
-  * `ec`
-  * `ecp`, `ecp2`, `ecp3`, `ecp5u`
-  * `lptm`, `lptm2`
-  * `machxo`, `machxo2`, `machxo3l`, `machxo3d`
-  * `sc`, `scm`
-  * `xp`, `xp2`
+  * ``ec``
+  * ``ecp``, ``ecp2``, ``ecp3``, ``ecp5u``
+  * ``lptm``, ``lptm2``
+  * ``machxo``, ``machxo2``, ``machxo3l``, ``machxo3d``
+  * ``sc``, ``scm``
+  * ``xp``, ``xp2``
+  * ...
+
+* Intel (Altera) Quartus (13.0 or later):
+
+  * ``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``
+  * ...
 
 * Xilinx ISE (14.0 or later):
 
-  * `unisim` (incl. `secureip`)
-  * `unimacro`
-  * `simprim` (incl. `secureip`)
-  * `xilinxcorelib`
+  * ``unisim`` (incl. ``secureip``)
+  * ``unimacro``
+  * ``simprim`` (incl. ``secureip``)
+  * ``xilinxcorelib``
 
 * Xilinx Vivado (2014.1 or later):
 
-  * `unisim` (incl. `secureip`)
-  * `unimacro`
+  * ``unisim`` (incl. ``secureip``)
+  * ``unimacro``
 
 Supported Simulation and Verification Libraries
 ===============================================
 
-* OSVVM (for VHDL-2008)
-
-  * osvvm
-
-* UVVM (for VHDL-2008)
+* OSVVM [#f1]_ (for VHDL-2008)
+* UVVM [#f2]_ (for VHDL-2008)
 
-  * uvvm-utilities
-  * uvvm-vvc-framework
-  * uvvm-vip-avalon_mm
-  * uvvm-vip-axi_lite
-  * uvvm-vip-axi_stream
-  * uvvm-vip-gpio
-  * uvvm-vip-i2c
-  * uvvm-vip-sbi
-  * uvvm-vip-spi
-  * uvvm-vip-uart
 
 ---------------------------------------------------------------------
 
@@ -80,56 +70,71 @@ The vendor library compile scripts need to know where the used / latest vendor
 tool chain is installed. Therefore, the scripts implement a default installation
 directory search as well as environment variable checks. If a vendor tool cannot
 be detected or the script chooses the wrong vendor library source directory,
-then it's possible to provide the path via `--source` or `-Source`.
+then it's possible to provide the path via ``--source`` (Bash) or ``-Source``
+(PoSh).
 
 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`.
+be overwritten by the parameter ``--output`` (Bash) or ``-Output`` (PoSh).
 
 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.
+``PATH``. The found default GHDL executable can be overwritten by setting the
+environment variable ``GHDL`` or by passing the parameter ``--ghdl`` (Bash) or
+``-GHDL`` (PoSh) to the scripts.
 
-If the vendor library compilation is used very often, we recommend configuring
-these parameters in `config.sh` or `config.psm1`, so the command line can be
-shortened to the essential parts.
+If the vendor library compilation is used very often, it's recommend to configure
+these parameters in ``config.sh`` (Bash) or ``config.psm1`` (PoSh), so the command
+line can be shortened to the essential parts.
 
 ---------------------------------------------------------------------
 
-Compiling on Linux
-==================
+Compiling in Bash
+=================
+
+The provided Bash scripts support these environments:
+
+* Linux
+* MacOS
+* MSYS2 / MinGW
+* WSL (Windows Subsystem for Linux)
+
+
+Follow these steps:
 
 * **Step 0 - Configure the scripts (optional)**
 
-    See the next section for how to configure `config.sh`.
+  See the next section for how to configure ``config.sh``.
 
 * **Step 1 - Browse to your simulation working directory**
 
   .. code-block:: Bash
 
     $ cd <MySimulationFolder>
-    ```
+
 
 * **Step 2 - Start the compilation script(s)**
 
+  Choose one or multiple of the following scripts to run the pre-compilation
+  process.
+
   .. code-block:: Bash
 
     $ /usr/local/lib/ghdl/vendors/compile-altera.sh --all
+    $ /usr/local/lib/ghdl/vendors/compile-intel.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-uvvm.sh --all
-    ```
+    $ /usr/local/lib/ghdl/vendors/compile-xilinx-ise.sh --all
+    $ /usr/local/lib/ghdl/vendors/compile-xilinx-vivado.sh --all
+
 
-    In most cases GHDL is installed into `/usr/local/`. The scripts are
-    installed into the `lib` directory.
+  In most cases GHDL is installed into ``/usr/local/``. The scripts are
+  installed into the ``lib\ghdl\vendors`` directory.
 
 * **Step 3 - Viewing the result**
 
-    This creates vendor directories in your current working directory and
-    compiles the vendor files into them.
+  This creates vendor directories in your current working directory and
+  compiles the vendor files into them.
 
 
   .. code-block:: Bash
@@ -137,22 +142,30 @@ Compiling on Linux
     $ ls -ahl
     ...
     drwxr-xr-x  2 <user> <group>  56K Mar 09 17:41 altera
+    drwxr-xr-x  2 <user> <group>  56K Mar 09 17:42 intel
     drwxr-xr-x  2 <user> <group>  56K Mar 09 17:42 lattice
     drwxr-xr-x  2 <user> <group>  56K Mar 09 17:48 osvvm
     drwxr-xr-x  2 <user> <group>  56K Mar 09 17:58 uvvm
     drwxr-xr-x  2 <user> <group>  56K Mar 09 17:58 xilinx-ise
     drwxr-xr-x  2 <user> <group>  56K Mar 09 17:48 xilinx-vivado
-    ```
+
 
 
 ---------------------------------------------------------------------
 
-Compiling on Windows
-====================
+Compiling in PowerShell
+=======================
+
+The provided PowerShell scripts support these environments:
+
+* Windows™ 10 (PowerShell 5 and PowerShell 6)
+
+
+Follow these steps:
 
 * **Step 0 - Configure the scripts (optional)**
 
-  See the next section for how to configure `config.psm1`.
+  See the next section for how to configure ``config.psm1``.
 
 * **Step 1 - Browse to your simulation working directory**
 
@@ -162,14 +175,22 @@ Compiling on Windows
 
 * **Step 2 - Start the compilation script(s)**
 
+  Choose one or multiple of the following scripts to run the pre-compilation
+  process.
+
   .. code-block:: 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-uvvm.ps1 -All
+     PS> <GHDL>\lib\ghdl\vendors\compile-altera.ps1 -All
+     PS> <GHDL>\lib\ghdl\vendors\compile-intel.ps1 -All
+     PS> <GHDL>\lib\ghdl\vendors\compile-lattice.ps1 -All
+     PS> <GHDL>\lib\ghdl\vendors\compile-osvvm.ps1 -All
+     PS> <GHDL>\lib\ghdl\vendors\compile-uvvm.ps1 -All
+     PS> <GHDL>\lib\ghdl\vendors\compile-xilinx-ise.ps1 -All
+     PS> <GHDL>\lib\ghdl\vendors\compile-xilinx-vivado.ps1 -All
+
+  .. # In most cases GHDL is installed into ``/usr/local/``.
+
+  The scripts are installed into the ``lib\ghdl\vendors`` directory.
 
 * **Step 3 - Viewing the result**
 
@@ -184,6 +205,7 @@ Compiling on Windows
      Mode           LastWriteTime       Length Name
      ----           -------------       ------ ----
      d----    09.03.2018    19:33        <DIR> altera
+     d----    09.03.2018    19:38        <DIR> intel
      d----    09.03.2018    19:38        <DIR> lattice
      d----    09.03.2018    19:38        <DIR> osvvm
      d----    09.03.2018    19:45        <DIR> uvvm
@@ -194,51 +216,61 @@ Compiling on Windows
 ---------------------------------------------------------------------
 
 Configuration Files
-======================
+===================
 
-For Linux: `config.sh`
-----------------------
+For Bash: `config.sh`
+---------------------
 
-Please open the `config.sh` file and set the dictionary entries for the
-installed vendor tools to your tool's installation
-directories. Use an empty string `""` for not installed tools.
+Please open the ``config.sh`` file and set the dictionary entries for the
+installed vendor tools to your tool's installation directories. Use an empty
+string ``""`` for not installed tools.
 
-`config.sh`:
+``config.sh``:
 
 .. code-block:: Bash
 
    declare -A InstallationDirectory
-   InstallationDirectory[AlteraQuartus]="/opt/Altera/17.1"
-   InstallationDirectory[LatticeDiamond]="/opt/Diamond/3.9_x64"
-   InstallationDirectory[OSVVM]="/home/<user>/git/GitHub/osvvm"
-   InstallationDirectory[UVVM]="/home/<user>/git/GitHub/uvvm_all"
+   InstallationDirectory[AlteraQuartus]="/opt/Altera/16.0"
+   InstallationDirectory[IntelQuartus]="/opt/intelFPGA/20.1"
+   InstallationDirectory[LatticeDiamond]="/opt/Diamond/3.10_x64"
+   InstallationDirectory[OSVVM]="/home/<user>/git/GitHub/OSVVM"
+   InstallationDirectory[UVVM]="/home/<user>/git/GitHub/UVVM"
    InstallationDirectory[XilinxISE]="/opt/Xilinx/14.7"
-   InstallationDirectory[XilinxVivado]="/opt/Xilinx/Vivado/2017.4"
+   InstallationDirectory[XilinxVivado]="/opt/Xilinx/Vivado/2020.2"
 
 
-For Windows: `config.psm1`
---------------------------
+For PowerShell: `config.psm1`
+-----------------------------
 
-Please open the `config.psm1` file and set the dictionary entries for the
+Please open the ``config.psm1`` file and set the dictionary entries for the
 installed vendor tools to your tool's installation
-folder. Use an empty string `""` for not installed tools.
+folder. Use an empty string ``""`` for not installed tools.
 
-`config.psm1`:
+``config.psm1``:
 
 .. code-block:: PowerShell
 
    $InstallationDirectory = @{
-     "AlteraQuartus" =   "C:\Altera\17.1";
-     "LatticeDiamond" =  "C:\Lattice\Diamond\3.9_x64";
+     "AlteraQuartus" =   "C:\Altera\16.0";
+     "IntelQuartus" =    "C:\Altera\20.1";
+     "LatticeDiamond" =  "C:\Lattice\Diamond\3.10_x64";
      "XilinxISE" =       "C:\Xilinx\14.7\ISE_DS";
-     "XilinxVivado" =    "C:\Xilinx\Vivado\2017.4";
-     "OSVVM" =           "D:\git\GitHub\osvvm";
-     "UVVM" =            "D:\git\GitHub\uvvm_all"
+     "XilinxVivado" =    "C:\Xilinx\Vivado\2020.2";
+     "OSVVM" =           "C:\git\GitHub\OSVVM";
+     "UVVM" =            "C:\git\GitHub\UVVM"
    }
 
 
-Selectable Options for the Bash Scripts:
-----------------------------------------
+Additional Script Parameters
+============================
+
+Each script supports partial compilations e.g. of shared packages and
+individual parts. In addition, the amount of printout to the console can be
+controlled. Some scripts may offer vendor specific options.
+
+
+For Bash Scripts:
+-----------------
 
 * Common parameters to most scripts:
 
@@ -251,7 +283,7 @@ Selectable Options for the Bash Scripts:
      --skip-largefiles, -S Don't compile large entities like DSP and PCIe primitives.
      --halt-on-error, -H   Stop compiling if an error occurred.
 
-* `compile-altera.sh`
+* ``compile-altera.sh``
 
   Selectable libraries:
 
@@ -271,7 +303,7 @@ Selectable Options for the Bash Scripts:
      --vhdl93              Compile selected libraries with VHDL-93 (default).
      --vhdl2008            Compile selected libraries with VHDL-2008.
 
-* `compile-xilinx-ise.sh`
+* ``compile-xilinx-ise.sh``
 
   Selectable libraries:
 
@@ -291,7 +323,7 @@ Selectable Options for the Bash Scripts:
      --vhdl93              Compile selected libraries with VHDL-93 (default).
      --vhdl2008            Compile selected libraries with VHDL-2008.
 
-* `compile-xilinx-vivado.sh`
+* ``compile-xilinx-vivado.sh``
 
   Selectable libraries:
 
@@ -309,7 +341,7 @@ Selectable Options for the Bash Scripts:
      --vhdl93              Compile selected libraries with VHDL-93 (default).
      --vhdl2008            Compile selected libraries with VHDL-2008.
 
-* `compile-osvvm.sh`
+* ``compile-osvvm.sh``
 
   Selectable libraries:
 
@@ -318,7 +350,7 @@ Selectable Options for the Bash Scripts:
      --all, -a             Compile all.
      --osvvm               Compile the OSVVM library.
 
-* `compile-uvvm.sh`
+* ``compile-uvvm.sh``
 
   Selectable libraries:
 
@@ -328,8 +360,8 @@ Selectable Options for the Bash Scripts:
      --uvvm                Compile the UVVM libraries.
 
 
-Selectable Options for the PowerShell Scripts:
-----------------------------------------------
+For PowerShell Scripts:
+-----------------------
 
 * Common parameters to all scripts:
 
@@ -339,7 +371,7 @@ Selectable Options for the PowerShell Scripts:
      -Clean                Cleanup directory before analyzing.
      -SuppressWarnings     Don't show warnings. Report errors only.
 
-* `compile-altera.ps1`
+* ``compile-altera.ps1``
 
   Selectable libraries:
 
@@ -359,7 +391,7 @@ Selectable Options for the PowerShell Scripts:
      -VHDL93               Compile selected libraries with VHDL-93 (default).
      -VHDL2008             Compile selected libraries with VHDL-2008.
 
-* `compile-xilinx-ise.ps1`
+* ``compile-xilinx-ise.ps1``
 
   Selectable libraries:
 
@@ -379,7 +411,7 @@ Selectable Options for the PowerShell Scripts:
      -VHDL93               Compile selected libraries with VHDL-93 (default).
      -VHDL2008             Compile selected libraries with VHDL-2008.
 
-* `compile-xilinx-vivado.ps1`
+* ``compile-xilinx-vivado.ps1``
 
   Selectable libraries:
 
@@ -397,7 +429,7 @@ Selectable Options for the PowerShell Scripts:
      -VHDL93               Compile selected libraries with VHDL-93 (default).
      -VHDL2008             Compile selected libraries with VHDL-2008.
 
-* `compile-osvvm.ps1`
+* ``compile-osvvm.ps1``
 
   Selectable libraries:
 
@@ -406,7 +438,7 @@ Selectable Options for the PowerShell Scripts:
      -All                  Compile all.
      -OSVVM                Compile the OSVVM library.
 
-* `compile-uvvm.ps1`
+* ``compile-uvvm.ps1``
 
   Selectable libraries:
 
@@ -422,5 +454,5 @@ Selectable Options for the PowerShell Scripts:
 	 .. rubric:: Footnotes
 
    .. [#f1] OSVVM http://github.com/OSVVM/OSVVM
-   .. [#f3] UVVM https://github.com/UVVM/UVVM_All
+   .. [#f2] UVVM https://github.com/UVVM/UVVM_All
    .. [#f4] Generic Colourizer http://kassiopeia.juls.savba.sk/~garabik/software/grc.html