Invoking GHDL#

The form of the ghdl command is ghdl command [options...]. There are multiple available commands, but these general rules apply:

  • The first argument selects the command. The options are used to slightly modify the action.

  • No option is allowed before the command. Except for the run command, no option is allowed after a filename or a unit name.


If the number of options is large and the command line length is beyond the system limit, you can use a response file. An argument that starts with a @ is considered as a response file; it is replaced by arguments read from the file (separated by blanks and end of line).


Only the most common commands and options are shown here. For the most advanced and experimental features see section Additional Command Reference.


During analysis and elaboration GHDL may read the std and ieee files. The location of these files is based on the prefix, which is (in order of priority):

  • the --PREFIX command line option

  • the GHDL_PREFIX environment variable

  • a built-in default path. It is a hard-coded path on GNU/Linux, and it corresponds to the value of the HKLM\Software\Ghdl\Install_Dir registry entry on Windows.

You should use the --disp-config command to display and debug installation problems.

Design building commands#

The most commonly used commands of GHDL are those to analyze and elaborate a design.

Analysis [-a]#

-a <[options...] file...>#

Analyzes/compiles one or more files, and creates an object file for each source file. Any argument starting with a dash is an option, the others are filenames. No options are allowed after a filename argument. GHDL analyzes each filename in the given order, and stops the analysis in case of error (remaining files are not analyzed).

See Options, for details on the GHDL options. For example, to produce debugging information such as line numbers, use: ghdl -a -g my_design.vhdl.

Elaboration [-e]#

-e <[options...] [library.]top_unit [arch]>#

Re-analyzes all the configurations, entities, architectures and package declarations, and creates the default configurations and the default binding indications according to the LRM rules. It also generates the list of object files required for the executable. Then, it links all these files with the runtime library (GRT).

The elaboration command, -e, must be followed by a top_unit name denoting either of:

  • a configuration unit

  • an entity unit

  • an entity unit followed by a secondary unit (the name of an architecture unit)

  • Name of the top units can be either a simple name (without dots), or the name of a logical library followed by a dot and a simple name. The latter is equivalent to using --work=NAME described in Options: -e <[options...] --work=library top_unit [arch]>. It selects the name of the library to be used as WORK. See section Top entity, for the restrictions on the root/top unit of a hierarchy.

  • Name of the secondary units must be a simple name; they cannot contain any dot.

With regard to the artifacts:

  • If the GCC/LLVM backend was enabled during the compilation of GHDL, the elaboration command creates an executable containing the code of the VHDL sources, the elaboration code and simulation code for executing a design hierarchy. The executable is created in the current directory and the the filename is the name of the primary unit, or for the latter case, the concatenation of the name of the primary unit, a dash, and the name of the secondary unit. Option -o followed by a filename can override the default executable filename.

  • If mcode is used, this command elaborates the design but does not generate anything. Since the run command also elaborates the design, this can be skipped.


This elaboration command is not a complete elaboration in terms of the VHDL standard. The actual elaboration is performed at runtime. Therefore, in order to get a complete VHDL elaboration without running the simulation, ghdl --elab-run --no-run is required. See --no-run.

Run [-r]#

-r <[options...] [library.]top_unit [arch] [simulation_options...]>#

Runs/simulates a design. Two sets of options are accepted, both of them being separated by [library.]top_unit [arch]. For the first set, options..., arguments are the same as for the elaboration command. For the second set, simulation_options..., arguments are defined in Simulation (runtime).

  • GGC/LLVM: the filename of the executable is determined and it is executed. Elaboration options are ignored. You may also directly execute the program. The executable must be in the current directory.

  • mcode: the design is elaborated and the simulation is launched. As a consequence, you must use the same options used during analysis.

This command exists for three reasons:

  • It works with mcode implementation, where the executable code is generated in memory.

  • You are using GCC/LLVM, but you don’t need to create the executable program name.

  • It is coherent with the -a and -e commands.

Elaborate and run [--elab-run]#

--elab-run <[options...] [library.]top_unit [arch] [simulation_options...]>#

Acts like the elaboration command followed by the run command. Note that this command accepts two sets of options. See -e, -r and Simulation (runtime).

Check syntax [-s]#

-s <[options...] file...>#

Analyze files but do not generate code. This command may be used to check the syntax of files. It does not update the library.

Analyze and elaborate [-c]#

-c <[options...] file... -<e|r> top_unit [arch]>#


With GCC/LLVM, -e should be used, and -r with mcode.

The files are first parsed, and then a elaboration is performed, which drives an analysis. Effectively, analysis and elaboration are combined, but there is no explicit call to -a. With GCC/LLVM, code is generated during the elaboration. With mcode, the simulation is launched after the elaboration.

All the units of the files are put into the work library. But, the work library is neither read from disk nor saved. Therefore, you must give all the files of the work library your design needs.

The advantages over the traditional approach (analyze and then elaborate) are:

  • The compilation cycle is achieved in one command.

  • Since the files are only parsed once, the compilation cycle may be faster.

  • You don’t need to know an analysis order.

  • This command produces a smaller executable, since unused units and subprograms do not generate code.


However, you should know that most of the time is spent in code generation and the analyze and elaborate command generates code for all units needed, even units of std and ieee libraries. Therefore, according to the design, the time for this command may be higher than the time for the analyze command followed by the elaborate command.


This command is still under development. In case of problems, you should go back to the traditional way.

Design rebuilding commands#

Analyzing and elaborating a design consisting of several files can be tricky, due to dependencies. GHDL has a few commands for rebuilding a design.

Import [-i]#

-i <[options...] file...>#

All the files specified in the command line are scanned, parsed and added into the libraries but as not yet analyzed. No object files are created. Its purpose is to localize design units in the design files. The make command will then be able to recursively build a hierarchy from an entity name or a configuration name.


  • Note that all the files are added to the work library. If you have many libraries, you must use the command for each library.

  • Since the files are parsed, there must be correct files. However, since they are not analyzed, many errors are tolerated by this command.

See -m, to actually build the design. See also --elab-order, for retrieving the compilation order guessed recursively.

Elab-order [--elab-order]#

--elab-order <[options...] [library.]top_unit [arch]>#

Print the list of sources required for elaborating a unit, in order for them to be analyzed without dependency issues. This is expected to be used after -i, or for retrieving the order for some unit analyzed through third-party scripts.

With the --libraries option, each line contains first the library name followed by the file name.

Without the --libraries option, the list does not include information about the logical library names where each source needs to be analyzed. Hence, it is useful when all sources belong to the same WORK library.

Make [-m]#

-m <[options...] [library.]top_unit [arch]>#

Analyze automatically outdated files and elaborate a design. The primary unit denoted by the [library.]top_unit argument must already be known by the system, either because you have already analyzed it (even if you have modified it) or because you have imported it. A file may be outdated because it has been modified (e.g. you have just edited it), or because a design unit contained in the file depends on a unit which is outdated. This rule is recursive.

  • With option --bind, GHDL will stop before the final linking step. This is useful when the main entry point is not GHDL and you’re linking GHDL object files into a foreign program.

  • With option -f (force), GHDL analyzes all the units of the work library needed to create the design hierarchy. Outdated units are recompiled. This is useful if you want to compile a design hierarchy with new compilation flags (for example, to add the -g debugging option).


The make command will only re-analyze design units in the work library. GHDL fails if it has to analyze an outdated unit from another library.

The purpose of this command is to be able to compile a design without prior knowledge of file order. In the VHDL model, some units must be analyzed before others (e.g. an entity before its architecture). It might be a nightmare to analyze a full design of several files if you don’t have the ordered list of files. This command computes an analysis order.

The make command fails when a unit was not previously parsed. For example, if you split a file containing several design units into several files, you must either import these new files or analyze them so that GHDL knows in which file these units are.

The make command imports files which have been modified. Then, a design hierarchy is internally built as if no units are outdated. Then, all outdated design units, using the dependencies of the design hierarchy, are analyzed. If necessary, the design hierarchy is elaborated.


This is not perfect, since the default architecture (the most recently analyzed one) may change while outdated design files are analyzed. In such a case, re-run the make command of GHDL.

Generate Makefile [--gen-makefile]#

--gen-makefile <[options...] [library.]top_unit [arch]>#

This command works like the make command (see -m), but only a makefile is generated on the standard output.

Generate dependency file command [--gen-depends]#

--gen-depends <[options...] [library.]top_unit [arch]>#

Generate a Makefile containing only dependencies to build a design unit.

This command works like the make and gen-makefile commands (see -m), but instead of a full makefile only dependencies without rules are generated on the standard output. These rules can then be integrated in another Makefile.

This command is not available with the mcode backend.



Specify the name of the WORK library. Analyzed units are always placed in the library logically named WORK. With this option, you can set its name. By default, the name is work.

GHDL checks whether WORK is a valid identifier. Although being more or less supported, the WORK identifier should not be an extended identifier, since the filesystem may prevent it from working correctly (due to case sensitivity or forbidden characters in filenames).


VHDL rules forbid you from adding units to the std library. Furthermore, you should not put units in the ieee library.


Since 849a25e0, this option can be alternatively provided to several commands by prepending the library name to the top unit name. See, for instance, -e.


Specify the directory where the WORK library is located. When this option is not present, the WORK library is in the current directory. The object files created by the compiler are always placed in the same directory as the WORK library.

Use option -P to specify where libraries other than WORK are placed.


Specify the standard to use. By default, the standard is 93c, which means VHDL-93 with relaxed rules. For details on STANDARD values see section VHDL standards.


This option resets the effect of -frelaxed, so it should be the first option.


Allow the use of synopsys non-standard packages (std_logic_arith, std_logic_signed, std_logic_unsigned, std_logic_textio). These packages are present in the ieee library but without this option it’s an error to use them.

The synopsys packages were created by some companies, and are popular. However they are not standard packages, and have been placed in the IEEE library without the permission from the ieee.


Select the IEEE library to use. IEEE_VAR must be one of:


Do not supply an IEEE library. Any library clause with the IEEE identifier will fail, unless you have created your own library with the IEEE name.


Supply an IEEE library containing only packages defined by ieee standards. Currently, there are the multivalue logic system package std_logic_1164 defined by IEEE 1164, the synthesis packages numeric_bit and numeric_std defined by IEEE 1076.3, and the vital packages vital_timing and vital_primitives, defined by IEEE 1076.4. The version of these packages is defined by the VHDL standard used. See section VITAL packages, for more details.


This option is now deprecated. It is equivalent to --ieee=standard and -fsynopsys.

To avoid errors, you must use the same IEEE library for all units of your design, and during elaboration.


Add DIRECTORY to the end of the list of directories to be searched for library files. A library is searched in DIRECTORY and also in DIRECTORY/LIB/vVV (where LIB is the name of the library and VV the vhdl standard).

The WORK library is always searched in the path specified by the --workdir option, or in the current directory if the latter option is not specified.


When two operators are overloaded, give preference to the explicit declaration. This may be used to avoid the most common pitfall of the std_logic_arith package. See section IEEE library pitfalls, for an example.


This option is not set by default. We don’t think this option is a good feature, because it breaks the encapsulation rule. When set, an operator can be silently overridden in another package. You’d do better to fix your design and use the numeric_std package.



The effects of this option are reset by --std, so it should be placed after that option.

Slightly relax some rules to be compatible with various other simulators or synthesizers:

  • VHDL-87 file declarations are accepted;

  • Default binding indication rules of VHDL-02 are used. Default binding rules are often used, but they are particularly obscure before VHDL-02.

  • Allow a subprogram body to match its declaration when the argument lists are semantically identical but do not satisfy formal rules (e.g when a function declaration uses the keyword in for an argument but its body does not).

  • Within an object declaration, allow references to the name (which references the hidden declaration). This ignores the error in the following code:

    package pkg1 is
      type state is (state1, state2, state3);
    end pkg1;
    use work.pkg1.all;
    package pkg2 is
      constant state1 : state := state1;
    end pkg2;

    Some code (such as Xilinx packages) have such constructs, which are invalid.

    (The scope of the state1 constant starts at the constant keyword. Because the constant state1 and the enumeration literal state1 are homographs, the enumeration literal is hidden in the immediate scope of the constant).

This option also relaxes the rules about pure functions. Violations result in warnings instead of errors.


Enable parsing of PSL assertions within comments. See section PSL support for more details.

--mb-comments, -C#

Allow UTF8 or multi-bytes chars in a comment.

According to the VHDL standards before 2002, the only characters allowed in a source file (and that includes the comments) are the graphical characters of the ISO 8859-1 character set. This is incompatible with comments using UTF-8 or some other encoding. This option lift this restriction.


Use synthesizer rules for component binding. During elaboration, if a component is not bound to an entity using VHDL LRM rules, try to find in any known library an entity whose name is the same as the component name.

This rule is known as the synthesizer rule.

There are two key points: normal VHDL LRM rules are tried first and entities are searched only in known libraries. A known library is a library which has been named in your design.

This option is only useful during elaboration.


Define the output format of some options, such as --pp-html or --xref-html.

  • By default or when --format=html2 is specified, generated files follow the HTML 2.0 standard, and colours are specified with <FONT> tags. However, colours are hard-coded.

  • If --format=css is specified, generated files follow the HTML 4.0 standard, and use the CSS-1 file ghdl.css to specify colours. This file is generated only if it does not already exist (it is never overwritten) and can be customized by the user to change colours or appearance. Refer to a generated file and its comments for more information.


Disable or enable checks of restriction on VITAL units. Checks are enabled by default.

Checks are performed only when a design unit is decorated by a VITAL attribute. The VITAL attributes are VITAL_Level0 and VITAL_Level1, both declared in the ieee.VITAL_Timing package.

Currently, VITAL checks are only partially implemented. See section VHDL restrictions for VITAL for more details.


Use PATH as the prefix path to find commands and pre-installed (std and ieee) libraries.


Be verbose. For example, for analysis, elaboration and make commands, GHDL displays the commands executed.


All the commands that perform a link (-e, --elab-run, --link, -c, -m, etc.) support overriding the location and name of the generated artifact.



This feature is supported with mcode backend only. It is not possible to support it with either LLVM or GCC backends, because it needs to apply globally.

Set the base time resolution of the simulation. This option is supported in commands -a and -r only. Allowed values are auto (default), fs, ps, ns, us, ms or sec. With LLVM/GCC, the value is fixed to fs.


When overriding the time resolution, all the time units that are used in the design must be larger. Using units below the resolution will produce a failure.


Some constructions are not erroneous but dubious. Warnings are diagnostic messages that report such constructions. Some warnings are reported only during analysis, others during elaboration.


You could disable a warning by using the --warn-no-XXX or -Wno-XXX instead of --warn-XXX or -WXXX.


The warnings -Wbinding, -Wlibrary, -Wshared, -Wpure, -Wspecs, -Whide, -Wport are enabled by default.


Warns if a design unit replaces another design unit with the same name.


During analyze, warns if a component instantiation has neither configuration specification nor default binding. This may be useful if you want to detect during analyze possibly unbound components if you don’t use configuration. See section VHDL standards for more details about default binding rules.


During elaboration, warns if a component instantiation is not bound (and not explicitly left unbound). Also warns if a port of an entity is not bound in a configuration specification or in a component configuration. This warning is enabled by default, since default binding rules are somewhat complex and an unbound component is most often unexpected.

However, warnings are still emitted if a component instantiation is inside a generate statement. As a consequence, if you use the conditional generate statement to select a component according to the implementation, you will certainly get warnings.


Emit a warning on unconnected input port without defaults (in relaxed mode).


Emit a warning if an identifier is a reserved word in a later VHDL standard.


Emit a warning for unknown pragma


Emit a warning if a /* appears within a block comment (vhdl 2008).


Emit an option on tool directive


Emit a warning in case of weird use of parentheses.


Warns if a generic name of a vital entity is not a vital generic name. This is set by default.


Warns for checks that cannot be done during analysis time and are postponed to elaboration time. This is because not all procedure bodies are available during analysis (either because a package body has not yet been analysed or because GHDL doesn’t read not required package bodies).

These are checks for no wait statements in a procedure called in a sensitized process and checks for pure rules of a function.


Emit a warning if a package body which is not required is analyzed. If a package does not declare a subprogram or a deferred constant, the package does not require a body.


Emit a warning if an all or others specification does not apply.


Emit a warning on incorrect use of universal values.


Emit a warning on bounds mismatch between the actual and formal in a scalar port association


Emit a warning in case of runtime error that is detected during analysis.


Emit a warning if a signal assignemnt creates a delta cycle in a postponed process.


Emit a warning if there is no wait statement in a non-sensitized process


Emit a warning when a shared variable is declared and its type it not a protected type.


Emit a warning when a declaration hides a previous hide.


Emit a warning when a subprogram is never used.


Emit a warning if a variable or a signal is never assigned (only for synthesis).


Emit a warning is an others choice is not required because all the choices have been explicitly covered.


Emit a warning when a pure rules is violated (like declaring a pure function with access parameters).


Emit a warning for assertions that are statically evaluated during analysis.


Emit a warning on incorrect use of attributes.


Emit a warning on useless code (like conditions that are always false or true, assertions that cannot be triggered).


Emit a warning on missing association for a port association. Open associations are required.


Emit a warning when a non-static expression is used at a place where the standard requires a static expression.


When this option is set, warnings are considered as errors. With the parameter, only the specific warning is turned into an error.

Diagnostics Control#


Control whether diagnostic messages are displayed in color. The default is on when the standard output is a terminal. For compatibility with other tools, when colors are enabled the diagnostic level is always displayed. When colors are not enabled, level error is not displayed.


Control whether the warning option is displayed at the end of warning messages, so that the user can easily know how to disable it.


Control whether the source line of the error is displayed with a caret indicating the column of the error.

Library commands#

A new library is created implicitly, by compiling entities (packages etc.) into it: ghdl -a --work=my_custom_lib my_file.vhdl.

A library’s source code is usually stored and compiled into its own directory, that you specify with the --workdir option: ghdl -a --work=my_custom_lib --workdir=my_custom_libdir my_custom_lib_srcdir/my_file.vhdl. See also the -P command line option.

Furthermore, GHDL provides a few commands which act on a library:

--dir <[options...] [libs]>#

Displays the content of the design libraries (by default the work library). All options are allowed, but only a few are meaningful: --work, --workdir and --std.

--clean <[options...]>#

Try to remove any object, executable or temporary file it could have created. Source files are not removed. The library is kept.

--remove <[options...]>#

Acts like the clean command but removes the library too. Note that after removing a design library, the files are not known anymore by GHDL.

--copy <--work=name [options...]>#

Make a local copy of an existing library. This is very useful if you want to add units to the ieee library:

ghdl --copy --work=ieee --ieee=synopsys
ghdl -a --work=ieee numeric_unsigned.vhd

VPI/VHPI build commands#

These commands simplify the compile and the link of a user VPI or VHPI module. They are all wrappers: the arguments are in fact a whole command line that is executed with additional switches. Currently a unix-like compiler (like cc, gcc or clang) is expected: the additional switches use their syntax. The only option is -v which displays the command before its execution.

--vpi-compile <command>#

Add an include path to the command and execute it:

ghdl --vpi-compile command

This will execute:

command -Ixxx/include

For example, ghdl --vpi-compile gcc -c vpi1.c executes gcc -c vpi1.c -fPIC -Ixxx/include.

Add a library path and name to the command and execute it:

ghdl --vpi-link command

This will execute:

command -Lxxx/lib -lghdlvpi

For example, ghdl --vpi-link gcc -o vpi1.vpi vpi1.o executes gcc -o vpi1.vpi vpi1.o --shared -Lxxx/lib -lghdlvpi.


Display flags added by --vpi-compile.


Display flags added by --vpi-link.


Display the include directory added by the compile flags.


Display the library directory added by the link flags.


Display the library directory added by the link flags, forcing UNIX syntax.

IEEE library pitfalls#

When you use options --ieee=synopsys, the ieee library contains non standard packages such as std_logic_arith. These packages are not standard because there are not described by an IEEE standard, even if they have been put in the IEEE library. Furthermore, they are not really de-facto standard, because there are slight differences between the packages of Mentor and those of Synopsys. Furthermore, since they are not well thought out, their use has pitfalls. For example, this description has an error during compilation:

library ieee;
use ieee.std_logic_1164.all;

--  A counter from 0 to 10.
entity counter is
  port (val : out std_logic_vector (3 downto 0);
        ck : std_logic;
        rst : std_logic);
end counter;

library ieee;
use ieee.std_logic_unsigned.all;

architecture bad of counter
  signal v : std_logic_vector (3 downto 0);
  process (ck, rst)
    if rst = '1' then
      v <= x"0";
    elsif rising_edge (ck) then
      if v = "1010" then -- Error
        v <= x"0";
        v <= v + 1;
      end if;
    end if;
  end process;

  val <= v;
end bad;

When you analyze this design, GHDL does not accept it (two long lines have been split for readability):

ghdl -a --ieee=synopsys bad_counter.vhdl
bad_counter.vhdl:13:14: operator "=" is overloaded
bad_counter.vhdl:13:14: possible interpretations are:
../../libraries/ieee/std_logic_1164.v93:69:5: implicit function "="
    [std_logic_vector, std_logic_vector return boolean]
../../libraries/synopsys/std_logic_unsigned.vhdl:64:5: function "="
    [std_logic_vector, std_logic_vector return boolean]
../translate/ghdldrv/ghdl: compilation error

Indeed, the “=” operator is defined in both packages, and both are visible at the place it is used. The first declaration is an implicit one, which occurs when the std_logic_vector type is declared and is an element to element comparison. The second one is an explicit declared function, with the semantics of an unsigned comparison.

With some analysers, the explicit declaration has priority over the implicit declaration, and this design can be analyzed without error. However, this is not the rule given by the VHDL LRM, and since GHDL follows these rules, it emits an error.

You can force GHDL to use this rule with the -fexplicit option (see Options for further details). However it is easy to fix this error, by using a selected name:

library ieee;
use ieee.std_logic_unsigned.all;

architecture fixed_bad of counter
  signal v : std_logic_vector (3 downto 0);
  process (ck, rst)
    if rst = '1' then
      v <= x"0";
    elsif rising_edge (ck) then
      if ieee.std_logic_unsigned."=" (v, "1010") then
        v <= x"0";
        v <= v + 1;
      end if;
    end if;
  end process;

  val <= v;
end fixed_bad;

It is better to only use the standard packages defined by IEEE, which provide the same functionalities:

library ieee;
use ieee.numeric_std.all;

architecture good of counter
  signal v : unsigned (3 downto 0);
  process (ck, rst)
    if rst = '1' then
      v <= x"0";
    elsif rising_edge (ck) then
      if v = "1010" then
        v <= x"0";
        v <= v + 1;
      end if;
    end if;
  end process;

  val <= std_logic_vector (v);
end good;


The ieee math packages (math_real and math_complex) provided with GHDL are fully compliant with the IEEE standard.