vendors: move vendor pre-compile scripts into subdir 'scripts'

1 files changed, 132 insertions, 0 deletions

diff --git a/scripts/vendors/README.md b/scripts/vendors/README.md
new file mode 100644
index 000000000..4b3e90ec9
--- /dev/null
+++ b/scripts/vendors/README.md
@@ -0,0 +1,132 @@
+# 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 cannot be
+shipped with GHDL, but GHDL offers 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 [UVVM][uvvm], which can be pre-compile, too.
+
+The compilation scripts are writen in the shell languages: PowerShell for Windows
+and Bash for Linux, MacOS, MSYS2/MinGW. The compile scripts can colorize the GHDL
+warning and error lines with the help of grc/grcat ([generic colourizer][grc]).
+
+ [osvvm]: http://osvvm.org/
+ [uvvm]: https://github.com/UVVM/UVVM_All
+ [grc]: http://kassiopeia.juls.savba.sk/~garabik/software/grc.html
+
+See the [GHDL Documentation](https://ghdl.github.io/ghdl) for a detailed
+documentation on how to use [Precompile Scripts](https://ghdl.github.io/ghdl/getting/PrecompileVendorPrimitives.html)
+
+---------------------------------------------------------------------
+
+## Quick Start
+### Compiling in Bash (e.g. Linux)
+
+ - **Step 1 - Browse to your simulation working directory**
+    ```Bash
+    $ cd <MySimulationFolder>
+    ```
+
+ - **Step 2 - Start the compilation script(s)**
+	 Choose one of the provided pre-compilation scripts and run:
+    ```Bash
+    $ /usr/local/lib/ghdl/vendors/compile-osvvm.sh --all --source ../path/to/osvvm
+    ```
+
+    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.
+
+    ```Bash
+    $ ls -ahl
+    ...
+    drwxr-xr-x  2 <user> <group>  56K Nov 30 17:48 osvvm
+    drwxr-xr-x  2 <user> <group>  56K Nov 30 17:58 osvvm_common
+    drwxr-xr-x  2 <user> <group>  56K Nov 30 17:58 osvvm_axi4
+    drwxr-xr-x  2 <user> <group>  56K Nov 30 17:48 osvvm_uart
+    ```
+
+
+---------------------------------------------------------------------
+### Compiling in PowerShell (e.g. Windows)
+
+ - **Step 1 - Browse to your simulation working directory**
+    ```PowerShell
+    PS> cd <MySimulationFolder>
+    ```
+
+ - **Step 2 - Start the compilation script(s)**
+	 Choose one of the provided pre-compilation scripts and run:
+    ```PowerShell
+    PS> <GHDL>\lib\ghdl\vendors\compile-osvvm.ps1 -All -Source ..\path\to\osvvm
+    ```
+
+ - **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.2019    19:38        <DIR> osvvm
+    d----    20.11.2019    19:45        <DIR> osvvm_common
+    d----    20.11.2019    19:06        <DIR> osvvm_axi4
+    d----    20.11.2019    19:40        <DIR> osvvm_uart
+    ```
+
+---------------------------------------------------------------------
+
+## Usage
+
+*TODO*
+
+
+
+---------------------------------------------------------------------
+
+## Options
+
+Each script has an integrated help. Use `script.sh --help` (Bash) or
+`script.ps1 -Help` (PoSh) to print all options. When setting verbose or debug
+mode, scripts will print more information or all commands executed by
+the script itself.
+
+With `--source` (Bash) or `-Source` (PoSh) the 3rd party libraries VHDL
+directory can be specified. With `-output` (Bash) or `-Output` (PoSh) the
+output directory can be specified. If GHDL is not automatically found, then
+the path to the GHDL executable can be specified with `--ghdl` (Bash) or
+`-GHDL` (PoSh).
+
+For a detailed documentation and all command line options see
+[Precompile Scripts](https://ghdl.github.io/ghdl/getting/PrecompileVendorPrimitives.html)
+
+
+---------------------------------------------------------------------
+
+## TODOs
+
+- OSVVM
+  - switch / search directories if normal OSVVM or OsvvmLibraries is specified as source
+- Missing features
+  - Implement `-Clean` ```--clean` commands
+- describe usage with -P
+- document offered procedures and functions
+- don't enforce `--output` if `--source` is used.
+- UVVM (OSVVM)
+  - create a list of components as array and generate from that:
+	  - variables
+	  - cli options
+	  - help text
+	  - default values
+
+------------------------
+Author: Patrick Lehmann
+Last update: 14.01.2020