Quick Start Guide

Since this is the user and reference manual for GHDL, it does not contain an introduction to VHDL. Thus, the reader should have at least a basic knowledge of VHDL. A good knowledge of VHDL language reference manual (usually called LRM) is a plus. Nevertheless, multiple examples are provided, in the hope that they are useful for users to learn about both GHDL and VHDL. For advanced examples using specific features see Examples.

As explained in What is GHDL?, GHDL is a compiler which translates VHDL files to machine code. Hence, the regular workflow is composed of three steps:

  • Analysis [-a]: convert design units (VHDL sources) to an internal representation.
  • Elaboration [-e]: generate executable machine code for a target module (top-level entity).
  • Run [-r]: execute the design to test the behaviour, generate output/waveforms, etc.

The following tips might be useful:

  • Don’t forget to select the version of the VHDL standard you want to use (see VHDL standards). The default is --std=93c. Use --std=08 for VHDL-2008 (albeit not fully implemented).
    • Use --ieee=synopsys if your design depends on a non-standard implementation of the IEEE library.
    • Use -fexplicit and -frelaxed-rules if needed. For instance when relaxing VHDL 2008’s need for shared variables to be protected types, you can use –std=08 -frelaxed.
  • Use --work=LIB_NAME to analyze files into the LIB_NAME library. To use files analyzed to a different directory, give the path to the LIB_NAME library using -P/path/to/name/directory/.
  • Use the same options for analysis and elaboration. E.g., first analyse with ghdl -a --std=08 --work=mylib myfile.vhdl; and then elaborate and run with ghdl --elab-run --std=08 top.

Due to the fact that VHDL is processed as a general purpose language (instead of an HDL), all the language features are to be supported. I.e., VHDL sources do not need to be limited to the synthesisable subset. However, distinction between synthesisable and non-synthesisable (simulation-only) subsets is often misleading for users who are new to the language. Different examples are provided, in the hope of helping understand the different use cases: