Additional Command Reference

Hint

The most common commands and options are shown in section Invoking GHDL. Here the advanced and experimental features are described.

Environment variables

GHDL_PREFIX

Misc commands

There are a few GHDL commands which are seldom useful.

Help [-h]

--help, -h

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 that second command are displayed:

ghdl --help
ghdl -h
ghdl -h command

Help [--help-options]

--help-options,

Display (on the standard output) a short description of the all the analysis options.

ghdl –help-options

Help [--help-warnings]

--help-warnings,

Display (on the standard output) a short description of the all the warnings, and those which are enabled by default.

ghdl –help-warnings

Display config [--disp-config]

--disp-config <[options]>

Display the program paths and options used by GHDL. This may be useful to track installation errors.

Display standard [--disp-standard]

--disp-standard <[options]>

Display the std.standard package.

Version [--version]

--version, -v

Display the GHDL version.

File commands

The following commands act on one or several files. These are not analyzed, therefore, they work even if a file has semantic errors.

Format [fmt]

fmt <file>

Format on the standard output the input file.

Pretty print [--pp-html]

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

Find [-f]

-f <file...>

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

Chop [--chop]

--chop <files...>

The provided files are read, and a file is written in the current directory for every design unit. Each filename is built according to the type:

  • 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 doesn’t have enough memory to compile such files. The size of the executable is reduced too.

Lines [--lines]

--lines <files...>

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

XML tree generation [--file-to-xml]

--file-to-xml

Outputs an XML representation of the decorated syntax tree for the input file and its dependencies. It can be used for VHDL tooling using semantic information, like style checkers, documentation extraction, complexity estimation, etc.

Warning

  • The AST slightly changes from time to time (particularly when new nodes are added for new language features), so be liberal in what is allowed by your tool. Also, the XML can be quite large so consider it only during prototyping.

  • Note that at this time there is no XML dump of the elaborated design.

MCODE only commands

coverage <[format] files>

Merge and output results of coverage generated by simulations run with the --coverage option. There are different output formats.

The default format, also selected with --format=summary displays on the standard output a line for each file, containing the file name and the coverage ratio (with numbers and also with a percentage). The last line displays the total ratio.

The option --format=lcov displays on the standard output a tracefile of the lcov format. You can directly use genhtml tool (from lcov) and generates HTML files from the results.

Finally, the option --format=gcov generates .gcov files in the current directory, which are compatible with the gcov output. A .gcov file is generated for each source file, which contains the text source prefixed with coverage informations.

GCC/LLVM only commands

Bind [--bind]

--bind <[options] [library.]top_unit [arch]>

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

Hint

Currently, the objects generated by --bind are created in the working directory. This behaviour is different from other object files generated with -a, which are always placed in the same directory as the WORK library. It is possible to provide an output path with ghdl --bind -o path/top_unit [library.]top_unit [arch]. However, ghdl --list-link will only search in the current path.

Options

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

Passing options to other programs

Warning

These options are only available with GCC/LLVM.

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.