1# Compile Scripts for Vendor VHDL Libraries
2
3Vendors like Altera, Lattice and Xilinx have their own simulation libraries,
4especially for FPGA primitives, soft and hard macros. These libraries cannot be
5shipped with GHDL, but GHDL offers prepared compile scripts to pre-compile the
6vendor libraries, if the vendor tool is present on the computer.
7
8There are also popular simulation and verification libraries like [OSVVM][osvvm]
9and [UVVM][uvvm], which can be pre-compile, too.
10
11The compilation scripts are writen in the shell languages: PowerShell for Windows
12and Bash for Linux, MacOS, MSYS2/MinGW. The compile scripts can colorize the GHDL
13warning and error lines with the help of grc/grcat ([generic colourizer][grc]).
14
15 [osvvm]: http://osvvm.org/
16 [uvvm]: https://github.com/UVVM/UVVM_All
17 [grc]: http://kassiopeia.juls.savba.sk/~garabik/software/grc.html
18
19See the [GHDL Documentation](https://ghdl.github.io/ghdl) for a detailed
20documentation on how to use [Precompile Scripts](https://ghdl.github.io/ghdl/getting/PrecompileVendorPrimitives.html)
21
22---------------------------------------------------------------------
23
24## Quick Start
25### Compiling in Bash (e.g. Linux)
26
27 - **Step 1 - Browse to your simulation working directory**
28    ```Bash
29    $ cd <MySimulationFolder>
30    ```
31
32 - **Step 2 - Start the compilation script(s)**
33	 Choose one of the provided pre-compilation scripts and run:
34    ```Bash
35    $ /usr/local/lib/ghdl/vendors/compile-osvvm.sh --all --source ../path/to/osvvm
36    ```
37
38    In most cases GHDL is installed into `/usr/local/`. The scripts are
39    installed into the `lib/ghdl/vendors` directory.
40
41 - **Step 3 - Viewing the result**
42    This creates vendor directories in your current working directory and
43    compiles the vendor files into them.
44
45    ```Bash
46    $ ls -ahl
47    ...
48    drwxr-xr-x  2 <user> <group>  56K Nov 30 17:48 osvvm
49    drwxr-xr-x  2 <user> <group>  56K Nov 30 17:58 osvvm_common
50    drwxr-xr-x  2 <user> <group>  56K Nov 30 17:58 osvvm_axi4
51    drwxr-xr-x  2 <user> <group>  56K Nov 30 17:48 osvvm_uart
52    ```
53
54
55---------------------------------------------------------------------
56### Compiling in PowerShell (e.g. Windows)
57
58 - **Step 1 - Browse to your simulation working directory**
59    ```PowerShell
60    PS> cd <MySimulationFolder>
61    ```
62
63 - **Step 2 - Start the compilation script(s)**
64	 Choose one of the provided pre-compilation scripts and run:
65    ```PowerShell
66    PS> <GHDL>\lib\ghdl\vendors\compile-osvvm.ps1 -All -Source ..\path\to\osvvm
67    ```
68
69 - **Step 3 - Viewing the result**
70    This creates vendor directories in your current working directory and
71    compiles the vendor files into them.
72
73    ```PowerShell
74    PS> dir
75        Directory: D:\temp\ghdl
76
77    Mode           LastWriteTime       Length Name
78    ----           -------------       ------ ----
79    d----    20.11.2019    19:38        <DIR> osvvm
80    d----    20.11.2019    19:45        <DIR> osvvm_common
81    d----    20.11.2019    19:06        <DIR> osvvm_axi4
82    d----    20.11.2019    19:40        <DIR> osvvm_uart
83    ```
84
85---------------------------------------------------------------------
86
87## Usage
88
89*TODO*
90
91
92
93---------------------------------------------------------------------
94
95## Options
96
97Each script has an integrated help. Use `script.sh --help` (Bash) or
98`script.ps1 -Help` (PoSh) to print all options. When setting verbose or debug
99mode, scripts will print more information or all commands executed by
100the script itself.
101
102With `--source` (Bash) or `-Source` (PoSh) the 3rd party libraries VHDL
103directory can be specified. With `-output` (Bash) or `-Output` (PoSh) the
104output directory can be specified. If GHDL is not automatically found, then
105the path to the GHDL executable can be specified with `--ghdl` (Bash) or
106`-GHDL` (PoSh).
107
108For a detailed documentation and all command line options see
109[Precompile Scripts](https://ghdl.github.io/ghdl/getting/PrecompileVendorPrimitives.html)
110
111
112---------------------------------------------------------------------
113
114## TODOs
115
116- OSVVM
117  - switch / search directories if normal OSVVM or OsvvmLibraries is specified as source
118- Missing features
119  - Implement `-Clean` ```--clean` commands
120- describe usage with -P
121- document offered procedures and functions
122- don't enforce `--output` if `--source` is used.
123- UVVM (OSVVM)
124  - create a list of components as array and generate from that:
125	  - variables
126	  - cli options
127	  - help text
128	  - default values
129
130------------------------
131Author: Patrick Lehmann
132Last update: 14.01.2020
133