1.. _PACKAGES: 2 3Getting | Installing 4#################### 5 6Package managers 7**************** 8 9Package managers of many popular distributions provide pre-built packages of GHDL. This is the case for `apt` 10(Debian/Ubuntu), `dnf` (Fedora), `pacman` (Arch Linux, MSYS2) or `brew` (macOS). Since GHDL supports three different backends 11and two library sets (*regular* or *GPL-compatible*), at least six packages with different features might be available in 12each package manager. 13 14As a rule of thumb, mcode backend is the fastest for analysis and synthesis. It also allows setting the base simulation time 15for speeding up execution. Therefore, it is the recommended pick if available on your platform (x86/amd64, on Windows x86 16only). On other platforms, or for using specific features for co-simulation or code coverage, LLVM or GCC need to be used. 17See further differences between backends in :ref:`BUILD`. 18 19.. _RELEASE:packages: 20 21Nightly packages 22**************** 23 24Assets from nightly GHDL builds are available at `github.com/ghdl/ghdl/releases/nightly <https://github.com/ghdl/ghdl/releases/nightly>`__. 25These are mostly meant to be used in Continuous Integration (CI) workflows. Precisely, `setup-ghdl-ci <https://github.com/ghdl/setup-ghdl-ci>`__ 26allows to easily setup nightly assets in GitHub Actions workflows. 27 28However, users on Windows (MSYS2) or Ubuntu might want to download the tarballs/zipfiles and extract/install them locally. 29 30.. _GETTING:PrecompVendor: 31 32Precompile Vendor Primitives 33**************************** 34 35Vendors like Lattice, Intel (Altera) and Xilinx have their own simulation libraries, 36especially for FPGA primitives, soft and hard macros. These libraries cannot 37be shipped with GHDL, but GHDL offers prepared compile scripts to pre-compile 38these vendor libraries, if the vendor tool is present in the environment. There 39are also popular simulation and verification libraries like OSVVM [#f1]_ or 40UVVM [#f2]_, which can be pre-compiled, too. 41 42The compilation scripts are writen in the shell languages: *PowerShell* for 43*Windows™* and *Bash* for *GNU/Linux*, *MacOS* and *MSYS2*/*MinGW*. The 44compile scripts can colorize the GHDL warning and error lines with the help 45of ``grc/grcat`` [#f4]_. 46 47.. HINT:: 48 Vendor precompile scripts for OSVVM and UVVM are tested periodically in `ghdl/extended-tests <https://github.com/ghdl/extended-tests>`__. 49 50Supported Vendors Libraries 51=========================== 52 53* Lattice (3.6 or later): 54 55 * ``ec`` 56 * ``ecp``, ``ecp2``, ``ecp3``, ``ecp5u`` 57 * ``lptm``, ``lptm2`` 58 * ``machxo``, ``machxo2``, ``machxo3l``, ``machxo3d`` 59 * ``sc``, ``scm`` 60 * ``xp``, ``xp2`` 61 * ... 62 63* Intel (Altera) Quartus (13.0 or later): 64 65 * ``lpm``, ``sgate`` 66 * ``altera``, ``altera_mf``, ``altera_lnsim`` 67 * ``arriaii``, ``arriaii_pcie_hip``, ``arriaiigz`` 68 * ``arriav``, ``arriavgz``, ``arriavgz_pcie_hip`` 69 * ``cycloneiv``, ``cycloneiv_pcie_hip``, ``cycloneive`` 70 * ``cyclonev`` 71 * ``max``, ``maxii``, ``maxv`` 72 * ``stratixiv``, ``stratixiv_pcie_hip`` 73 * ``stratixv``, ``stratixv_pcie_hip`` 74 * ``fiftyfivenm``, ``twentynm`` 75 * ... 76 77* Xilinx ISE (14.0 or later): 78 79 * ``unisim`` (incl. ``secureip``) 80 * ``unimacro`` 81 * ``simprim`` (incl. ``secureip``) 82 * ``xilinxcorelib`` 83 84* Xilinx Vivado (2014.1 or later): 85 86 * ``unisim`` (incl. ``secureip``) 87 * ``unimacro`` 88 89Supported Simulation and Verification Libraries 90=============================================== 91 92* OSVVM [#f1]_ (for VHDL-2008) 93* UVVM [#f2]_ (for VHDL-2008) 94 95 96--------------------------------------------------------------------- 97 98Script Configuration 99==================== 100 101The vendor library compile scripts need to know where the used / latest vendor 102tool chain is installed. Therefore, the scripts implement a default installation 103directory search as well as environment variable checks. If a vendor tool cannot 104be detected or the script chooses the wrong vendor library source directory, 105then it's possible to provide the path via ``--source`` (Bash) or ``-Source`` 106(PoSh). 107 108The generated output is stored relative to the current working directory. The 109scripts create a sub-directory for each vendor. The default output directory can 110be overwritten by the parameter ``--output`` (Bash) or ``-Output`` (PoSh). 111 112To compile all source files with GHDL, the simulator executable is searched in 113``PATH``. The found default GHDL executable can be overwritten by setting the 114environment variable ``GHDL`` or by passing the parameter ``--ghdl`` (Bash) or 115``-GHDL`` (PoSh) to the scripts. 116 117If the vendor library compilation is used very often, it's recommend to configure 118these parameters in ``config.sh`` (Bash) or ``config.psm1`` (PoSh), so the command 119line can be shortened to the essential parts. 120 121--------------------------------------------------------------------- 122 123Compiling in Bash 124================= 125 126The provided Bash scripts support these environments: 127 128* Linux 129* MacOS 130* MSYS2 / MinGW 131* WSL (Windows Subsystem for Linux) 132 133 134Follow these steps: 135 136* **Step 0 - Configure the scripts (optional)** 137 138 See the next section for how to configure ``config.sh``. 139 140* **Step 1 - Browse to your simulation working directory** 141 142 .. code-block:: Bash 143 144 $ cd <MySimulationFolder> 145 146 147* **Step 2 - Start the compilation script(s)** 148 149 Choose one or multiple of the following scripts to run the pre-compilation 150 process. 151 152 .. code-block:: Bash 153 154 $ /usr/local/lib/ghdl/vendors/compile-altera.sh --all 155 $ /usr/local/lib/ghdl/vendors/compile-intel.sh --all 156 $ /usr/local/lib/ghdl/vendors/compile-lattice.sh --all 157 $ /usr/local/lib/ghdl/vendors/compile-osvvm.sh --all 158 $ /usr/local/lib/ghdl/vendors/compile-uvvm.sh --all 159 $ /usr/local/lib/ghdl/vendors/compile-xilinx-ise.sh --all 160 $ /usr/local/lib/ghdl/vendors/compile-xilinx-vivado.sh --all 161 162 163 In most cases GHDL is installed into ``/usr/local/``. The scripts are 164 installed into the ``lib\ghdl\vendors`` directory. 165 166* **Step 3 - Viewing the result** 167 168 This creates vendor directories in your current working directory and 169 compiles the vendor files into them. 170 171 172 .. code-block:: Bash 173 174 $ ls -ahl 175 ... 176 drwxr-xr-x 2 <user> <group> 56K Mar 09 17:41 altera 177 drwxr-xr-x 2 <user> <group> 56K Mar 09 17:42 intel 178 drwxr-xr-x 2 <user> <group> 56K Mar 09 17:42 lattice 179 drwxr-xr-x 2 <user> <group> 56K Mar 09 17:48 osvvm 180 drwxr-xr-x 2 <user> <group> 56K Mar 09 17:58 uvvm 181 drwxr-xr-x 2 <user> <group> 56K Mar 09 17:58 xilinx-ise 182 drwxr-xr-x 2 <user> <group> 56K Mar 09 17:48 xilinx-vivado 183 184 185 186--------------------------------------------------------------------- 187 188Compiling in PowerShell 189======================= 190 191The provided PowerShell scripts support these environments: 192 193* Windows™ 10 (PowerShell 5 and PowerShell 6) 194 195 196Follow these steps: 197 198* **Step 0 - Configure the scripts (optional)** 199 200 See the next section for how to configure ``config.psm1``. 201 202* **Step 1 - Browse to your simulation working directory** 203 204 .. code-block:: PowerShell 205 206 PS> cd <MySimulationFolder> 207 208* **Step 2 - Start the compilation script(s)** 209 210 Choose one or multiple of the following scripts to run the pre-compilation 211 process. 212 213 .. code-block:: PowerShell 214 215 PS> <GHDL>\lib\ghdl\vendors\compile-altera.ps1 -All 216 PS> <GHDL>\lib\ghdl\vendors\compile-intel.ps1 -All 217 PS> <GHDL>\lib\ghdl\vendors\compile-lattice.ps1 -All 218 PS> <GHDL>\lib\ghdl\vendors\compile-osvvm.ps1 -All 219 PS> <GHDL>\lib\ghdl\vendors\compile-uvvm.ps1 -All 220 PS> <GHDL>\lib\ghdl\vendors\compile-xilinx-ise.ps1 -All 221 PS> <GHDL>\lib\ghdl\vendors\compile-xilinx-vivado.ps1 -All 222 223 .. # In most cases GHDL is installed into ``/usr/local/``. 224 225 The scripts are installed into the ``lib\ghdl\vendors`` directory. 226 227* **Step 3 - Viewing the result** 228 229 This creates vendor directories in your current working directory and 230 compiles the vendor files into them. 231 232 .. code-block:: 233 234 PS> dir 235 Directory: D:\temp\ghdl 236 237 Mode LastWriteTime Length Name 238 ---- ------------- ------ ---- 239 d---- 09.03.2018 19:33 <DIR> altera 240 d---- 09.03.2018 19:38 <DIR> intel 241 d---- 09.03.2018 19:38 <DIR> lattice 242 d---- 09.03.2018 19:38 <DIR> osvvm 243 d---- 09.03.2018 19:45 <DIR> uvvm 244 d---- 09.03.2018 19:06 <DIR> xilinx-ise 245 d---- 09.03.2018 19:40 <DIR> xilinx-vivado 246 247 248--------------------------------------------------------------------- 249 250Configuration Files 251=================== 252 253For Bash: `config.sh` 254--------------------- 255 256Please open the ``config.sh`` file and set the dictionary entries for the 257installed vendor tools to your tool's installation directories. Use an empty 258string ``""`` for not installed tools. 259 260``config.sh``: 261 262.. code-block:: Bash 263 264 declare -A InstallationDirectory 265 InstallationDirectory[AlteraQuartus]="/opt/Altera/16.0" 266 InstallationDirectory[IntelQuartus]="/opt/intelFPGA/20.1" 267 InstallationDirectory[LatticeDiamond]="/opt/Diamond/3.10_x64" 268 InstallationDirectory[OSVVM]="/home/<user>/git/GitHub/OSVVM" 269 InstallationDirectory[UVVM]="/home/<user>/git/GitHub/UVVM" 270 InstallationDirectory[XilinxISE]="/opt/Xilinx/14.7" 271 InstallationDirectory[XilinxVivado]="/opt/Xilinx/Vivado/2020.2" 272 273 274For PowerShell: `config.psm1` 275----------------------------- 276 277Please open the ``config.psm1`` file and set the dictionary entries for the 278installed vendor tools to your tool's installation 279folder. Use an empty string ``""`` for not installed tools. 280 281``config.psm1``: 282 283.. code-block:: PowerShell 284 285 $InstallationDirectory = @{ 286 "AlteraQuartus" = "C:\Altera\16.0"; 287 "IntelQuartus" = "C:\Altera\20.1"; 288 "LatticeDiamond" = "C:\Lattice\Diamond\3.10_x64"; 289 "XilinxISE" = "C:\Xilinx\14.7\ISE_DS"; 290 "XilinxVivado" = "C:\Xilinx\Vivado\2020.2"; 291 "OSVVM" = "C:\git\GitHub\OSVVM"; 292 "UVVM" = "C:\git\GitHub\UVVM" 293 } 294 295 296Additional Script Parameters 297============================ 298 299Each script supports partial compilations e.g. of shared packages and 300individual parts. In addition, the amount of printout to the console can be 301controlled. Some scripts may offer vendor specific options. 302 303 304For Bash Scripts: 305----------------- 306 307* Common parameters to most scripts: 308 309 .. code-block:: none 310 311 --help, -h Print the embedded help page(s). 312 --clean, -c Cleanup directory before analyzing. 313 --no-warnings, -n Don't show warnings. Report errors only. 314 --skip-existing, -s Skip already compiled files (an *.o file exists). 315 --skip-largefiles, -S Don't compile large entities like DSP and PCIe primitives. 316 --halt-on-error, -H Stop compiling if an error occurred. 317 318* ``compile-altera.sh`` 319 320 Selectable libraries: 321 322 .. code-block:: none 323 324 --all, -a Compile all libraries, including common libraries, packages and device libraries. 325 --altera Compile base libraries like 'altera' and 'altera_mf' 326 --max Compile device libraries for Max CPLDs 327 --arria Compile device libraries for Arria FPGAs 328 --cyclone Compile device libraries for Cyclone FPGAs 329 --stratix Compile device libraries for Stratix FPGAs 330 331 Compile options: 332 333 .. code-block:: none 334 335 --vhdl93 Compile selected libraries with VHDL-93 (default). 336 --vhdl2008 Compile selected libraries with VHDL-2008. 337 338* ``compile-xilinx-ise.sh`` 339 340 Selectable libraries: 341 342 .. code-block:: none 343 344 --all, -a Compile all libraries, including common libraries, packages and device libraries. 345 --unisim Compile the unisim primitives 346 --unimacro Compile the unimacro macros 347 --simprim Compile the simprim primitives 348 --corelib Compile the xilinxcorelib macros 349 --secureip Compile the secureip primitives 350 351 Compile options: 352 353 .. code-block:: none 354 355 --vhdl93 Compile selected libraries with VHDL-93 (default). 356 --vhdl2008 Compile selected libraries with VHDL-2008. 357 358* ``compile-xilinx-vivado.sh`` 359 360 Selectable libraries: 361 362 .. code-block:: none 363 364 --all, -a Compile all libraries, including common libraries, packages and device libraries. 365 --unisim Compile the unisim primitives 366 --unimacro Compile the unimacro macros 367 --secureip Compile the secureip primitives 368 369 Compile options: 370 371 .. code-block:: none 372 373 --vhdl93 Compile selected libraries with VHDL-93 (default). 374 --vhdl2008 Compile selected libraries with VHDL-2008. 375 376* ``compile-osvvm.sh`` 377 378 Selectable libraries: 379 380 .. code-block:: none 381 382 --all, -a Compile all. 383 --osvvm Compile the OSVVM library. 384 385* ``compile-uvvm.sh`` 386 387 Selectable libraries: 388 389 .. code-block:: none 390 391 --all, -a Compile all. 392 --uvvm Compile the UVVM libraries. 393 394 395For PowerShell Scripts: 396----------------------- 397 398* Common parameters to all scripts: 399 400 .. code-block:: none 401 402 -Help Print the embedded help page(s). 403 -Clean Cleanup directory before analyzing. 404 -SuppressWarnings Don't show warnings. Report errors only. 405 406* ``compile-altera.ps1`` 407 408 Selectable libraries: 409 410 .. code-block:: none 411 412 -All Compile all libraries, including common libraries, packages and device libraries. 413 -Altera Compile base libraries like 'altera' and 'altera_mf' 414 -Max Compile device libraries for Max CPLDs 415 -Arria Compile device libraries for Arria FPGAs 416 -Cyclone Compile device libraries for Cyclone FPGAs 417 -Stratix Compile device libraries for Stratix FPGAs 418 419 Compile options: 420 421 .. code-block:: none 422 423 -VHDL93 Compile selected libraries with VHDL-93 (default). 424 -VHDL2008 Compile selected libraries with VHDL-2008. 425 426* ``compile-xilinx-ise.ps1`` 427 428 Selectable libraries: 429 430 .. code-block:: none 431 432 -All Compile all libraries, including common libraries, packages and device libraries. 433 -Unisim Compile the unisim primitives 434 -Unimacro Compile the unimacro macros 435 -Simprim Compile the simprim primitives 436 -CoreLib Compile the xilinxcorelib macros 437 -Secureip Compile the secureip primitives 438 439 Compile options: 440 441 .. code-block:: none 442 443 -VHDL93 Compile selected libraries with VHDL-93 (default). 444 -VHDL2008 Compile selected libraries with VHDL-2008. 445 446* ``compile-xilinx-vivado.ps1`` 447 448 Selectable libraries: 449 450 .. code-block:: none 451 452 -All Compile all libraries, including common libraries, packages and device libraries. 453 -Unisim Compile the unisim primitives 454 -Unimacro Compile the unimacro macros 455 -Secureip Compile the secureip primitives 456 457 Compile options: 458 459 .. code-block:: none 460 461 -VHDL93 Compile selected libraries with VHDL-93 (default). 462 -VHDL2008 Compile selected libraries with VHDL-2008. 463 464* ``compile-osvvm.ps1`` 465 466 Selectable libraries: 467 468 .. code-block:: none 469 470 -All Compile all. 471 -OSVVM Compile the OSVVM library. 472 473* ``compile-uvvm.ps1`` 474 475 Selectable libraries: 476 477 .. code-block:: none 478 479 -All Compile all. 480 -UVVM Compile the UVVM libraries. 481 482-------------------------------------------------------------------------------- 483 484.. container:: footnotes 485 486 .. rubric:: Footnotes 487 488 .. [#f1] OSVVM http://github.com/OSVVM/OSVVM 489 .. [#f2] UVVM https://github.com/UVVM/UVVM_All 490 .. [#f4] Generic Colourizer http://kassiopeia.juls.savba.sk/~garabik/software/grc.html 491