Invoking GHDL

The form of the ghdl command is:

ghdl command [options...]

The GHDL program has several commands. 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).

Building commands

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

Analysis command

Analyze one or several files:

ghdl -a [options...] file...

The analysis command compiles one or more files, and creates an object file for each source file. The analysis command is selected with -a switch. 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 (the following files are not analyzed).

See GHDL 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 command

Elaborate a design:

ghdl -e [options..] primary_unit [secondary_unit]

On GNU/Linux, if the GCC 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 to execute a design hierarchy. The executable is created in the current directory. On Windows or if the GCC backend was not enabled, this command elaborates the design but does not generate anything.

The elaboration command is selected with -e switch, and must be followed by either:

  • a name of a configuration unit
  • a name of an entity unit
  • a name of an entity unit followed by a name of an architecture unit

Name of the units must be a simple name, without any dot. You can select the name of the WORK library with the --work=NAME option, as described in GHDL options.

See Top entity, for the restrictions on the root design of a hierarchy.

On GNU/Linux the filename of the executable is the name of the primary unit, or for the later case, the concatenation of the name of the primary unit, a dash, and the name of the secondary unit (or architecture). On Windows there is no executable generated.

The -o followed by a filename can override the default executable filename.

For the elaboration command, GHDL 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 objects files required for the executable. Then, it links all these files with the runtime library.

The actual elaboration is performed at runtime.

On Windows this command can be skipped because it is also done by the run command.

Run command

Run (or simulate) a design:

ghdl -r [options...] primary_unit [secondary_unit] [simulation_options...]

The options and arguments are the same as for the elaboration command, Elaboration command.

On GNU/Linux this command simply determines the filename of the executable and executes it. Options are ignored. You may also directly execute the program. The executable must be in the current directory.

This command exists for three reasons:

  • You don’t have to create the executable program name.
  • It is coherent with the -a and -e commands.
  • It works with the Windows implementation, where the code is generated in memory.

On Windows this command elaborates and launches the simulation. As a consequence you must use the same options used during analysis.

See Simulation and runtime, for details on options.

Elaborate and run command

Elaborate and then simulate a design unit:

ghdl --elab-run [elab_options...] primary_unit [secondary_unit] [run_options...]

This command acts like the elaboration command (see Elaboration command) followed by the run command (see Run command).

Bind command

Bind a design unit and prepare the link step:

ghdl --bind [options] primary_unit [secondary_unit]

This command is only available on GNU/Linux.

This performs only the first stage of the elaboration command; the list of objects files is created but the executable is not built. This command should be used only when the main entry point is not ghdl.

Check syntax command

Analyze files but do not generate code:

ghdl -s [options] files

This command may be used to check the syntax of files. It does not update the library.

Analyze and elaborate command

Analyze files and elaborate them at the same time.

On GNU/Linux:

ghdl -c [options] file... -e primary_unit [secondary_unit]

On Windows:

ghdl -c [options] file... -r primary_unit [secondary_unit]

This command combines analysis and elaboration: files are analyzed and the unit is then elaborated. However, code is only generated during the elaboration. On Windows the simulation is launched.

To be more precise, the files are first parsed, and then the elaboration drives the analysis. Therefore, there is no analysis order, and you don’t need to care about it.

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 smaller executable, since unused units and subprograms do not generate code.

However, you should know that currently most of the time is spent in code generation and the analyze and elaborate command generate 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 experimental. In case of problems, you should go back to the traditional way.

GHDL options

Besides the options described below, GHDL passes any debugging options (those that begin with -g) and optimizations options (those that begin with -O or -f) to GCC. Refer to the GCC manual for details.

--workdir=<DIR>

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.

--std=<STD>

Specify the standard to use. By default, the standard is 93c, which means VHDL-93 accepting VHDL-87 syntax. For details on STD values see VHDL standards.

--ieee=<VER>

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

none
Do not supply an IEEE library. Any library clause with the IEEE identifier will fail, unless you have created by your own a library with the IEEE name.
standard
Supply an IEEE library containing only packages defined by ieee standards. Currently, there are the multivalue logic system packages 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 VITAL packages, for more details.
synopsys

Supply the former packages and the following additional packages: std_logic_arith, std_logic_signed, std_logic_unsigned, std_logic_textio.

These 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.

mentor
Supply the standard packages and the following additional package: std_logic_arith. The package is a slight variation of a definitely not standard but widely mis-used package.

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

-P<DIRECTORY>

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.

-fexplicit

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 IEEE library pitfalls, for an example.

This option is not set by default. I 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 better to fix your design and use the numeric_std package.

-frelaxed-rules

Within an object declaration, allow to reference 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 valid.

(The scope of the state1 constant start at the constant word. Because the constant state1 and the enumeration literal state1 are homograph, 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.

-fpsl

Enable parsing of PSL assertions within comments. See PSL implementation, for more details.

--no-vital-checks
--vital-checks

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 VHDL restrictions for VITAL, for more details.

--syn-binding

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 synthesizer rule.

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

This option is only useful during elaboration.

--PREFIX=<PATH>

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

--GHDL1=<COMMAND>

Use COMMAND as the command name for the compiler. If COMMAND is not a path, then it is searched in the path.

--AS=<COMMAND>

Use COMMAND as the command name for the assembler. If COMMAND is not a path, then it is searched in the path. The default is as.

Use COMMAND as the linker driver. If COMMAND is not a path, then it is searched in the path. The default is gcc.

-v

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

Passing options to other programs

These options are only available on GNU/Linux.

For many commands, GHDL acts as a driver: it invokes programs to perform the command. You can pass arbitrary options to these programs.

Both the compiler and the linker are in fact GCC programs. See the GCC manual for details on GCC options.

-Wc,<OPTION>

Pass OPTION as an option to the compiler.

-Wa,<OPTION>

Pass OPTION as an option to the assembler.

-Wl,<OPTION>

Pass OPTION as an option to the linker.

GHDL Diagnostics Control

-fcolor-diagnostics
-fno-color-diagnostics

Control whether diagnostic messages are displayed in color. The default is on when the standard output is a terminal.

-fdiagnostics-show-option
-fno-diagnostics-show-option

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

GHDL warnings

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-XX instead of --warn-XXX or -WXXX.

--warn-reserved

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

--warn-default-binding

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 component if you don’t use configuration. VHDL standards, for more details about default binding rules.

--warn-binding

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 even 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.

--warn-library

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

--warn-vital-generic

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

--warn-delayed-checks

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 statement in a procedure called in a sensitized process and checks for pure rules of a function.

--warn-body

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.

--warn-specs

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

--warn-unused

Emit a warning when a subprogram is never used.

--warn-error

When this option is set, warnings are considered as errors.

--warn-nested-comment

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

--warn-parenthesis

Emit a warning in case of weird use of parenthesis

--warn-runtime-error

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

Rebuilding commands

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

Import command

Add files in the work design library:

ghdl -i [options] file...

All the files specified in the command line are scanned, parsed and added in the libraries but as not yet analyzed. No object files are created.

The purpose of this command 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.

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

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

See Make command, to actually build the design.

Make command

Analyze automatically outdated files and elaborate a design:

ghdl -m [options] primary [secondary]

The primary unit denoted by the primary 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. GHDL analyzes all outdated files. A file may be outdated because it has been modified (e.g. you just have edited it), or because a design unit contained in the file depends on a unit which is outdated. This rule is of course recursive.

With the @code{-b} (bind only) option, 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 the -f (force) option, GHDL analyzes all the units of the work library needed to create the design hierarchy. Not 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 file. 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 command

Generate a Makefile to build a design unit:

ghdl --gen-makefile [options] primary [secondary]

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

Library commands

GHDL has a few commands which act on a library.

Directory command

Display the name of the units contained in a design library:

ghdl --dir [options] [libs]

The directory command, selected with the –dir command line argument displays the content of the design libraries (by default the work library). All options are allowed, but only a few are meaningful: --work=NAME, --workdir=PATH and --std=VER.

Clean command

Remove object and executable files but keep the library:

ghdl --clean [options]

GHDL tries to remove any object, executable or temporary file it could have created. Source files are not removed.

There is no short command line form for this option to prevent accidental clean up.

Remove command

Do like the clean command but remove the library too:

ghdl --remove [options]

There is no short command line form for this option to prevent accidental clean up. Note that after removing a design library, the files are not known anymore by GHDL.

Copy command

Make a local copy of an existing library:

ghdl --copy --work=name [options]

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

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

Create a Library

A new library is created by compiling entities (packages etc.) into it:

ghdl -a --work=my_custom_lib my_file.vhd

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.vhd

See also the -PPATH command line option.

Cross-reference command

To easily navigate through your sources, you may generate cross-references:

ghdl --xref-html [options] file...

This command generates an html file for each file given in the command line, with syntax highlighting and full cross-reference: every identifier is a link to its declaration. Besides, an index of the files is created too.

The set of file are analyzed, and then, if the analysis is successful, html files are generated in the directory specified by the -o dir option, or html/ directory by default.

If the option --format=html2 is specified, then the generated html files follow the HTML 2.0 standard, and colours are specified with <FONT> tags. However, colours are hard-coded.

If the option --format=css is specified, then the generated html 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.

File commands

The following commands act on one or several files. They do not analyze files, therefore, they work even if a file has semantic errors.

Pretty print command

Generate HTML on standard output from VHDL:

ghdl --pp-html [options] file...

The files are just scanned and an html file, with syntax highlighting is generated on standard output.

Since the files are not even parsed, erroneous files or incomplete designs can be pretty printed.

The style of the html file can be modified with the --format= option. By default or when the --format=html2 option is specified, the output is an HTML 2.0 file, with colours set through <FONT> tags. When the --format=css option is specified, the output is an HTML 4.0 file, with colours set through a CSS file, whose name is ghdl.css. See Cross-reference command, for more details about this CSS file.

Find command

Display the name of the design units in files:

ghdl -f file...

The files are scanned, parsed and the names of design units are displayed. Design units marked with two stars are candidate to be at the apex of a design hierarchy.

Chop command

Chop (or split) files at design unit:

ghdl --chop files

GHDL reads files, and writes a file in the current directory for every design unit.

The filename of a design unit is build according to the unit. For an entity declaration, a package declaration or a configuration the file name is NAME.vhdl, where NAME is the name of the design unit. For a package body, the filename is NAME-body.vhdl. Finally, for an architecture ARCH of an entity ENTITY, the filename is ENTITY-ARCH.vhdl.

Since the input files are parsed, this command aborts in case of syntax error. The command aborts too if a file to be written already exists.

Comments between design units are stored into the most adequate files.

This command may be useful to split big files, if your computer has not enough memory to compile such files. The size of the executable is reduced too.

Lines command

Display on the standard output lines of files preceded by line number:

ghdl --lines files

Misc commands

There are a few GHDL commands which are seldom useful.

Help command

Display (on the standard output) a short description of the all the commands available. If the help switch is followed by a command switch, then options for this later command are displayed:

ghdl --help
ghdl -h
ghdl -h command

Disp config command

Display the program paths and options used by GHDL:

ghdl --disp-config [options]

This may be useful to track installation errors.

Disp standard command

Display the std.standard package:

ghdl --disp-standard [options]

Version command

Display the GHDL version and exit:

ghdl --version

VPI build commands

These commands simplify the compile and the link of a user vpi module. They are all wrapper: 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 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

VPI cflags command

Display flags added by --vpi-compile:

ghdl --vpi-cflags

VPI ldflags command

Display flags added by --vpi-link:

ghdl --vpi-ldflags

VPI include dir command

Display the include directory added by the compile flags:

ghdl --vpi-include-dir

VPI library dir command

Display the library directory added by the link flags:

ghdl --vpi-library-dir

Installation Directory

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 priority order):

  • 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 the value of the HKLMSoftwareGhdlInstall_Dir registry entry on Windows.

You should use the --disp-config command (Disp config command for details) to disp and debug installation problems.

IEEE library pitfalls

When you use options --ieee=synopsys or --ieee=mentor, 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, their use has pitfalls. For example, this description has 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
is
   signal v : std_logic_vector (3 downto 0);
begin
   process (ck, rst)
   begin
     if rst = '1' then
        v <= x"0";
     elsif rising_edge (ck) then
        if v = "1010" then -- Error
           v <= x"0";
        else
           v <= v + 1;
        end if;
     end if;
   end process;

   val <= v;
end bad;

When you analyze this design, GHDL does not accept it (too 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 semantic of an unsigned comparison.

With some analyser, 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. GHDL options, for more 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
is
   signal v : std_logic_vector (3 downto 0);
begin
   process (ck, rst)
   begin
     if rst = '1' then
        v <= x"0";
     elsif rising_edge (ck) then
        if ieee.std_logic_unsigned."=" (v, "1010") then
           v <= x"0";
        else
           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 provides the same functionalities:

library ieee;
use ieee.numeric_std.all;

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

   val <= std_logic_vector (v);
end good;

IEEE math packages

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