Additional Command Reference¶
Hint
The most common commands and options are shown in section Invoking GHDL. Here the advanced and experimental features are described.
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
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.
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.
GCC/LLVM only commands¶
Bind [--bind
]¶
-
--bind
<[options] primary_unit [secondary_unit]>
¶
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/primary_unit primary_unit
. However, ghdl --list-link
will only search in the current path.
Link [--link
]¶
-
--link
<[options] primary_unit [secondary_unit]>
¶
Performs only the second stage of the elaboration command: the executable is created by linking the files of the object files list. This command is available only for completeness. The elaboration command is equivalent to the bind command followed by the link command.
List link [--list-link
]¶
-
--list-link
<primary_unit [secondary_unit]>
¶
This command may be used only after a bind command. GHDL displays all the files which will be linked to create an executable and additional arguments for the linker. This command is intended to add object files in a link of a foreign program. This command should be used only after ghdl --bind
, as some files generated by it are looked for in the current path.
Hint
One of the arguments returned by --list-link
is -Wl,--version-script=PREFIX/lib/ghdl/grt.ver
, where PREFIX is the installation path of GHDL. This will hide most of the symbols when the target executable binary is built. In some contexts, where the binary is to be loaded dynamically, the user might want additional symbols to be accessible. There are two possible approaches to have it done:
- Filter the output of
--list-link
with e.g.sed
. - Provide an additional non-anonymous version script:
-Wl,-Wl,--version-script=file.ver
.
Options¶
-
--mb-comments
,
-C
¶
Allow multi-bytes chars in a comment.
-
--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 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.
-
--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
.
-
--LINK<
=COMMAND>
¶
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.