aboutsummaryrefslogtreecommitdiffstats
path: root/doc/using/InvokingGHDL.rst
diff options
context:
space:
mode:
authorumarcor <unai.martinezcorral@ehu.eus>2021-04-22 15:27:46 +0200
committertgingold <tgingold@users.noreply.github.com>2021-04-22 18:53:03 +0200
commit7b638f1a4c40d2ce858a8edea7c8ca36edcf05e6 (patch)
treeff34ec354980abd90ced473feef6b303b190ccbe /doc/using/InvokingGHDL.rst
parent4a6b6dbda139e8265570cd2a51b6c371abef4912 (diff)
downloadghdl-7b638f1a4c40d2ce858a8edea7c8ca36edcf05e6.tar.gz
ghdl-7b638f1a4c40d2ce858a8edea7c8ca36edcf05e6.tar.bz2
ghdl-7b638f1a4c40d2ce858a8edea7c8ca36edcf05e6.zip
doc: add/rename '[library.]top_unit [arch]', style (849a25e0)
Diffstat (limited to 'doc/using/InvokingGHDL.rst')
-rw-r--r--doc/using/InvokingGHDL.rst508
1 files changed, 271 insertions, 237 deletions
diff --git a/doc/using/InvokingGHDL.rst b/doc/using/InvokingGHDL.rst
index 29f5e1681..1b0805591 100644
--- a/doc/using/InvokingGHDL.rst
+++ b/doc/using/InvokingGHDL.rst
@@ -4,15 +4,17 @@
Invoking GHDL
#############
-The form of the :program:`ghdl` command is ``ghdl command [options...]``. There are multiple available commands, but these
-general rules apply:
+The form of the :program:`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.
+* 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.
.. HINT::
- 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
+ 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).
.. HINT::
@@ -20,8 +22,8 @@ general rules apply:
:ref:`REF:Command`.
.. WARNING::
- 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):
+ 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 :option:`--PREFIX` command line option
* the :envvar:`GHDL_PREFIX` environment variable
@@ -45,12 +47,14 @@ Analysis [``-a``]
.. option:: -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).
+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 :ref:`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``.
+See :ref:`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``.
.. index:: cmd elaboration
@@ -60,35 +64,44 @@ numbers, use: ``ghdl -a -g my_design.vhdl``.
Elaboration [``-e``]
--------------------
-.. option:: -e <[options...] primary_unit [secondary_unit]>
+.. option:: -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.
+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, :option:`-e`, must be followed by a name of either:
+The elaboration command, :option:`-e`, must be followed by a ``top_unit`` name denoting either of:
* a configuration unit
* an entity unit
- * an entity unit followed by a name of an architecture unit
+ * an entity unit followed by a secondary unit (the 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
- :option:`--work=NAME <--work>` option, as described in :ref:`GHDL:options`. See section :ref:`Top_entity`, for the
- restrictions on the root design of a hierarchy.
+* 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 :option:`--work=NAME <--work>` described in :ref:`GHDL:options`:
+ ``-e <[options...] --work=library top_unit [arch]>``.
+ It selects the name of the library to be used as ``WORK``.
+ See section :ref:`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 to execute 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 (or architecture).
+ 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.
+* 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.
- .. WARNING::
- 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 :option:`--no-run`.
+.. WARNING::
+ 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 :option:`--no-run`.
.. index:: cmd run
@@ -98,22 +111,25 @@ files required for the executable. Then, it links all these files with the runti
Run [``-r``]
------------
-.. option:: -r <[options...] primary_unit [secondary_unit] [simulation_options...]>
+.. option:: -r <[options...] [library.]top_unit [arch] [simulation_options...]>
-Runs/simulates a design. Two sets of options are accepted, both of them being separated by ``primary_unit [secondary_unit]``.
-For the first set, ``options...``, arguments are the same as for the :ref:`elaboration command <Elaboration:command>`. For
-the second set, ``simulation_options...``, arguments are defined in :ref:`USING:Simulation`.
+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 :ref:`elaboration command <Elaboration:command>`.
+For the second set, ``simulation_options...``, arguments are defined in :ref:`USING:Simulation`.
-* 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.
+* 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 :option:`-a` and :option:`-e` commands.
-* It works with mcode implementation, where the executable code is generated in memory.
.. index:: cmd elaborate and run
@@ -123,10 +139,11 @@ This command exists for three reasons:
Elaborate and run [``--elab-run``]
----------------------------------
-.. option:: --elab-run <[options...] primary_unit [secondary_unit] [simulation_options...]>
+.. option:: --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
-:option:`-e`, :option:`-r` and :ref:`USING:Simulation`.
+Acts like the elaboration command followed by the run command.
+Note that this command accepts two sets of options.
+See :option:`-e`, :option:`-r` and :ref:`USING:Simulation`.
.. index:: cmd checking syntax
@@ -136,8 +153,9 @@ Check syntax [``-s``]
.. option:: -s <[options] files>
-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 files but do not generate code.
+This command may be used to check the syntax of files.
+It does not update the library.
.. index:: cmd analyze and elaborate
@@ -145,16 +163,18 @@ library.
Analyze and elaborate [``-c``]
------------------------------
-.. option:: -c <[options] file... -<e|r> primary_unit [secondary_unit]>
+.. option:: -c <[options] file... -<e|r> top_unit [arch]>
.. HINT::
With GCC/LLVM, :option:`-e` should be used, and :option:`-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 :option:`-a`. With GCC/LLVM, code is generated during the
-elaboration. With mcode, the simulation is launched after the elaboration.
+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 :option:`-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.
+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:
@@ -166,8 +186,9 @@ The advantages over the traditional approach (analyze and then elaborate) are:
.. HINT::
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.
+ 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.
.. WARNING::
This command is still under development. In case of problems, you should go back to the traditional way.
@@ -176,8 +197,8 @@ The advantages over the traditional approach (analyze and then elaborate) are:
Design rebuilding commands
==========================
-Analyzing and elaborating a design consisting of several files can be tricky, due to dependencies. GHDL has a few commands
-to rebuild a design.
+Analyzing and elaborating a design consisting of several files can be tricky, due to dependencies.
+GHDL has a few commands for rebuilding a design.
.. index:: cmd importing files
@@ -189,15 +210,16 @@ Import [``-i``]
.. option:: -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.
+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.
.. HINT::
- * 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.
+ * 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 :option:`-m`, to actually build the design.
@@ -209,36 +231,44 @@ See :option:`-m`, to actually build the design.
Make [``-m``]
-------------
-.. option:: -m <[options] primary [secondary]>
+.. option:: -m <[options] [library.]top_unit [arch]>
-Analyze automatically outdated files and elaborate a design. 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. 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 of course recursive.
+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).
+* 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.
+.. IMPORTANT::
+ 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 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 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.
+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.
+.. HINT::
+ 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.
.. index:: cmd generate makefile
@@ -246,7 +276,7 @@ are analyzed. In such a case, re-run the make command of GHDL.
Generate Makefile [``--gen-makefile``]
--------------------------------------
-.. option:: --gen-makefile <[options] primary [secondary]>
+.. option:: --gen-makefile <[options] [library.]top_unit [arch]>
This command works like the make command (see :option:`-m`), but only a makefile is generated on the standard output.
@@ -255,7 +285,7 @@ This command works like the make command (see :option:`-m`), but only a makefile
Generate dependency file command [``--gen-depends``]
----------------------------------------------------
-.. option:: --gen-depends <[options] primary [secondary]>
+.. option:: --gen-depends <[options] [library.]top_unit [arch]>
Generate a Makefile containing only dependencies to build a design unit.
@@ -277,42 +307,47 @@ Options
.. option:: --work=<LIB_NAME>
- 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``.
+ 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).
+ `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.
+ .. ATTENTION::
+ `VHDL` rules forbid you from adding units to the ``std`` library.
+ Furthermore, you should not put units in the ``ieee`` library.
+
+ .. HINT::
+ Since `849a25e0 <https://github.com/ghdl/ghdl/commit/849a25e02cfb359e3d9313060156b0643495548b>`__, this option can
+ be alternatively provided to several commands by prepending the library name to the top unit name.
+ See, for instance, :option:`-e`.
.. option:: --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.
+ 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 :option:`-P <-P>` to specify where libraries other than ``WORK`` are placed.
.. option:: --std=<STANDARD>
- 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 :ref:`VHDL_standards`.
+ 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 :ref:`VHDL_standards`.
- .. IMPORTANT:: This option resets the effect of :option:`-frelaxed`, so it should
- be the first option.
+ .. IMPORTANT:: This option resets the effect of :option:`-frelaxed`, so it should be the first option.
.. option:: -fsynopsys
- 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.
+ 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``.
+ 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``.
.. option:: --ieee=<IEEE_VAR>
@@ -322,63 +357,58 @@ Options
Select the ``IEEE`` library to use. ``IEEE_VAR`` must be one of:
none
- 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.
+ 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.
standard
- 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 :ref:`VITAL_packages`,
- for more details.
+ 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 :ref:`VITAL_packages`, for more details.
synopsys
- This option is now deprecated. It is equivalent to
- ``--ieee=standard`` and ``-fsynopsys``.
+ 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.
+ To avoid errors, you must use the same `IEEE` library for all units of your design, and during elaboration.
.. option:: -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`
+ 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
- :option:`--workdir` option, or in the current directory if the latter
- option is not specified.
+ The `WORK` library is always searched in the path specified by the :option:`--workdir` option, or in the current
+ directory if the latter option is not specified.
.. option:: -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 section :ref:`IEEE_library_pitfalls`, for an example.
+ This may be used to avoid the most common pitfall of the ``std_logic_arith`` package.
+ See section :ref:`IEEE_library_pitfalls`, for an example.
-.. WARNING:: 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 do better to fix your
- design and use the ``numeric_std`` package.
+.. WARNING::
+ 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.
.. option:: -frelaxed
.. option:: -frelaxed-rules
.. IMPORTANT:: The effects of this option are reset by :option:`--std`, so it should be placed *after* that option.
- Slightly relax some rules to be compatible with various other
- simulators or synthesizers:
+ 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.
+ * Default binding indication rules of VHDL-02 are used. Default binding rules are often used, but they are
+ particularly obscure before VHDL-02.
- * Within an object declaration, allow references to the name (which references the hidden declaration). This ignores the
- error in the following code:
+ * Within an object declaration, allow references to the name (which references the hidden declaration).
+ This ignores the error in the following code:
.. code-block:: VHDL
@@ -393,39 +423,37 @@ Options
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
+ (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.
+ This option also relaxes the rules about pure functions.
+ Violations result in warnings instead of errors.
.. option:: -fpsl
- Enable parsing of PSL assertions within comments. See section :ref:`PSL_implementation` for more details.
+ Enable parsing of PSL assertions within comments.
+ See section :ref:`PSL_implementation` for more details.
.. option:: --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.
+ 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.
.. option:: --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.
+ 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.
+ 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.
@@ -433,23 +461,26 @@ Options
Define the output format of some options, such as :option:`--pp-html` or :option:`--xref-html`.
- * By default or when :option:`--format=html2 <--format>` is specified, generated files follow the HTML 2.0 standard, and
- colours are specified with `<FONT>` tags. However, colours are hard-coded.
+ * By default or when :option:`--format=html2 <--format>` is specified, generated files follow the HTML 2.0 standard,
+ and colours are specified with `<FONT>` tags.
+ However, colours are hard-coded.
- * If :option:`--format=css <--format>` is specified, generated files follow the HTML 4.0 standard, and use the CSS-1 file
- :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.
+ * If :option:`--format=css <--format>` is specified, generated files follow the HTML 4.0 standard, and use the CSS-1
+ file :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.
.. option:: --no-vital-checks
.. option:: --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.
+ 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 :ref:`VHDL_restrictions_for_VITAL` for more details.
+ Currently, VITAL checks are only partially implemented.
+ See section :ref:`VHDL_restrictions_for_VITAL` for more details.
.. option:: --PREFIX=<PATH>
@@ -461,37 +492,38 @@ Options
.. option:: -o=<FNAME>
- All the commands that perform a link (:option:`-e`, :option:`--elab-run`, :option:`--link`, :option:`-c`, :option:`-m`,
- etc.) support overriding the location and name of the generated artifact.
+ All the commands that perform a link (:option:`-e`, :option:`--elab-run`, :option:`--link`, :option:`-c`,
+ :option:`-m`, etc.) support overriding the location and name of the generated artifact.
.. option:: --time-resolution=<UNIT>
.. ATTENTION::
- 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.
+ 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 :option:`-a` and :option:`-r` only.
- Allowed values are ``auto`` (default), ``fs``, ``ps``, ``ns``, ``us``, ``ms`` or ``sec``. With LLVM/GCC, the value is fixed
- to ``fs``.
+ Set the base time resolution of the simulation.
+ This option is supported in commands :option:`-a` and :option:`-r` only.
+ Allowed values are ``auto`` (default), ``fs``, ``ps``, ``ns``, ``us``, ``ms`` or ``sec``.
+ With LLVM/GCC, the value is fixed to ``fs``.
.. HINT::
- 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.
+ 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.
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.
+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.
.. HINT::
You could disable a warning by using the ``--warn-no-XXX`` or ``-Wno-XXX`` instead of ``--warn-XXX`` or ``-WXXX``.
.. HINT::
- The warnings ``-Wbinding``, ``-Wlibrary``, ``-Wshared``,
- ``-Wpure``, ``-Wspecs``, ``-Whide``, ``-Wport`` are enabled by
- default.
+ The warnings ``-Wbinding``, ``-Wlibrary``, ``-Wshared``, ``-Wpure``, ``-Wspecs``, ``-Whide``, ``-Wport`` are enabled
+ by default.
.. option:: --warn-library
@@ -499,19 +531,20 @@ warnings are reported only during analysis, others during elaboration.
.. option:: --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 components if you don't use configuration. See section
- :ref:`VHDL_standards` for more details about default binding rules.
+ 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 :ref:`VHDL_standards` for more details about default binding rules.
.. option:: --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.
+ 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.
+ 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.
.. option:: --warn-reserved
@@ -532,11 +565,12 @@ warnings are reported only during analysis, others during elaboration.
.. option:: --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).
+ 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.
+ These are checks for no wait statements in a procedure called in a sensitized process and checks for pure rules of a
+ function.
.. option:: --warn-body
@@ -549,13 +583,11 @@ warnings are reported only during analysis, others during elaboration.
.. option:: --warn-runtime-error
- Emit a warning in case of runtime error that is detected during
- analysis.
+ Emit a warning in case of runtime error that is detected during analysis.
.. option:: --warn-shared
- Emit a warning when a shared variable is declared and its type it
- not a protected type.
+ Emit a warning when a shared variable is declared and its type it not a protected type.
.. option:: --warn-hide
@@ -567,18 +599,15 @@ warnings are reported only during analysis, others during elaboration.
.. option:: --warn-others
- Emit a warning is an `others` choice is not required because all the
- choices have been explicitly covered.
+ Emit a warning is an `others` choice is not required because all the choices have been explicitly covered.
.. option:: --warn-pure
- Emit a warning when a pure rules is violated (like declaring a pure
- function with access parameters).
+ Emit a warning when a pure rules is violated (like declaring a pure function with access parameters).
.. option:: --warn-static
- Emit a warning when a non-static expression is used at a place where
- the standard requires a static expression.
+ Emit a warning when a non-static expression is used at a place where the standard requires a static expression.
.. option:: --warn-error
@@ -596,14 +625,13 @@ Diagnostics Control
.. option:: -fdiagnostics-show-option
.. option:: -fno-diagnostics-show-option
- 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 warning option is displayed at the end of warning messages, so that the user can easily know how
+ to disable it.
.. option:: -fcaret-diagnostics
.. option:: -fno-caret-diagnostics
- Control whether the source line of the error is displayed with a
- caret indicating the column of the error.
+ Control whether the source line of the error is displayed with a caret indicating the column of the error.
Library commands
@@ -612,11 +640,13 @@ Library commands
.. _Create_a_Library:
.. index:: create your own library
-A new library is created implicitly, by compiling entities (packages etc.) into it: ``ghdl -a --work=my_custom_lib my_file.vhdl``.
+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 :option:`--workdir`
-option: ``ghdl -a --work=my_custom_lib --workdir=my_custom_libdir my_custom_lib_srcdir/my_file.vhdl``. See also the
-:option:`-P <-P>` command line option.
+A library's source code is usually stored and compiled into its own directory, that you specify with the
+:option:`--workdir` option:
+``ghdl -a --work=my_custom_lib --workdir=my_custom_libdir my_custom_lib_srcdir/my_file.vhdl``.
+See also the :option:`-P <-P>` command line option.
Furthermore, GHDL provides a few commands which act on a library:
@@ -625,8 +655,8 @@ Furthermore, GHDL provides a few commands which act on a library:
.. option:: --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: :option:`--work`, :option:`--workdir` and :option:`--std`.
+Displays the content of the design libraries (by default the ``work`` library).
+All options are allowed, but only a few are meaningful: :option:`--work`, :option:`--workdir` and :option:`--std`.
.. index:: cmd library clean
@@ -635,7 +665,9 @@ meaningful: :option:`--work`, :option:`--workdir` and :option:`--std`.
.. option:: --clean <[options]>
-Try to remove any object, executable or temporary file it could have created. Source files are not removed. The library is kept.
+Try to remove any object, executable or temporary file it could have created.
+Source files are not removed.
+The library is kept.
.. index:: cmd library remove
@@ -644,15 +676,16 @@ Try to remove any object, executable or temporary file it could have created. So
.. option:: --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.
+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.
.. index:: cmd library copy
.. option:: --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:
+Make a local copy of an existing library.
+This is very useful if you want to add units to the ``ieee`` library:
.. code-block:: shell
@@ -664,10 +697,10 @@ Make a local copy of an existing library. This is very useful if you want to add
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.
+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.
.. index:: cmd VPI compile
@@ -740,15 +773,14 @@ Display the library directory added by the link flags, forcing UNIX syntax.
IEEE library pitfalls
=====================
-When you use options :option:`--ieee=synopsys <--ieee>`, 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:
+When you use options :option:`--ieee=synopsys <--ieee>`, 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:
.. code-block:: VHDL
@@ -799,15 +831,17 @@ When you analyze this design, GHDL does not accept it (two long lines have been
[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.
+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.
+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 :ref:`GHDL:options` for further details). However it
-is easy to fix this error, by using a selected name:
+You can force GHDL to use this rule with the *-fexplicit* option (see :ref:`GHDL:options` for further details).
+However it is easy to fix this error, by using a selected name:
.. code-block:: VHDL
@@ -866,5 +900,5 @@ It is better to only use the standard packages defined by IEEE, which provide th
.. index:: Math_Complex
.. HINT::
- The ``ieee`` math packages (``math_real`` and ``math_complex``) provided with `GHDL` are fully compliant with the `IEEE`
- standard.
+ The ``ieee`` math packages (``math_real`` and ``math_complex``) provided with `GHDL` are fully compliant with the
+ `IEEE` standard.