From 60fd762fa36f72b9ddad8cda84b6c16c6936d942 Mon Sep 17 00:00:00 2001
From: Tristan Gingold <gingold@adacore.com>
Date: Sat, 21 Nov 2015 05:54:42 +0100
Subject: Convert documentation to sphinx.

---
 doc/Invoking_GHDL.rst | 1114 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 1114 insertions(+)
 create mode 100644 doc/Invoking_GHDL.rst

(limited to 'doc/Invoking_GHDL.rst')

diff --git a/doc/Invoking_GHDL.rst b/doc/Invoking_GHDL.rst
new file mode 100644
index 000000000..c126c255f
--- /dev/null
+++ b/doc/Invoking_GHDL.rst
@@ -0,0 +1,1114 @@
+*************
+Invoking GHDL
+*************
+
+The form of the :program:`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.
+
+Building commands
+=================
+
+The mostly used commands of GHDL are those to analyze and elaborate a design.
+
+Analysis command
+----------------
+
+.. index:: analysis
+
+.. index:: *-a* command
+
+Analyze one or severals 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
+:option:`-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 :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
+
+
+.. _Elaboration_command:
+
+Elaboration command
+-------------------
+
+.. index:: elaboration
+
+.. index:: *-e* command
+
+Elaborate a design::
+
+  ghdl -e [options..] primary_unit [secondary_unit]
+
+
+On GNU/Linux the elaboration command creates an executable
+containing the code of the `VHDL` sources, the elaboration code
+and simulation code to execute a design hierarchy. On Windows this
+command elaborates the design but does not generate anything.
+
+The elaboration command is selected with :option:`-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 :option:`--work=NAME`
+option, as described in :ref:`GHDL_options`.
+
+See :ref:`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 :option:`-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 command
+-----------
+
+.. index:: run
+
+.. index:: *-r* 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, :ref:`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.
+
+This command exists for three reasons:
+
+* You don't have to create the executable program name.
+* It is coherent with the :option:`-a` and :option:`-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 :ref:`Simulation_and_runtime`, for details on options.
+
+Elaborate and run command
+-------------------------
+
+.. index:: elaborate and run
+
+.. index:: *--elab-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 :ref:`Elaboration_command`)
+followed by the run command (see :ref:`Run_command`).
+
+.. _Bind_command:
+
+Bind command
+------------
+
+.. index:: binding
+
+.. index:: *--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.
+
+.. _Link_command:
+
+Link command
+------------
+
+.. index:: linking
+
+.. index:: *--link* command
+
+Link an already bound design unit::
+
+  ghdl --link [options] primary_unit [secondary_unit]
+
+This 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_command:
+
+List link command
+-----------------
+
+.. index:: *--list-link* command
+
+Display files which will be linked::
+
+  ghdl --list-link primary_unit [secondary_unit]
+
+This command is only available on GNU/Linux.
+
+This command may be used only after a bind command.  GHDL displays all
+the files which will be linked to create an executable.  This command is
+intended to add object files in a link of a foreign program.
+
+.. _Check_syntax_command:
+
+Check syntax command
+--------------------
+
+.. index:: checking syntax
+
+.. index:: *-s* 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 and elaborate command
+-----------------------------
+
+.. index:: Analyze and elaborate command
+
+.. index:: *-c* 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 :samp:`std` and :samp:`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:
+
+GHDL options
+============
+
+.. index:: IEEE 1164
+
+.. index:: 1164
+
+.. index:: IEEE 1076.3
+
+.. index:: 1076.3
+
+Besides the options described below, `GHDL` passes any debugging options
+(those that begin with :option:`-g`) and optimizations options (those that
+begin with :option:`-O` or :option:`-f`) to `GCC`.  Refer to the `GCC`
+manual for details.
+
+
+
+.. option::--work=<NAME>
+
+  .. index:: WORK library
+
+  Specify the name of the :samp:`WORK` library.  Analyzed units are always
+  placed in the library logically named :samp:`WORK`.  With this option,
+  you can set its name.  By default, the name is :samp:`work`.
+
+  `GHDL` checks whether :samp:`WORK` is a valid identifier.  Although being
+  more or less supported, the :samp:`WORK` identifier should not be an
+  extended identifier, since the filesystem may prevent it from correctly
+  working (due to case sensitivity or forbidden characters in filenames).
+
+  `VHDL` rules forbid you to add units to the :samp:`std` library.
+  Furthermore, you should not put units in the :samp:`ieee` library.
+
+
+.. option:: --workdir=<DIR>
+
+  Specify the directory where the :samp:`WORK` library is located.  When this
+  option is not present, the :samp:`WORK` library is in the current
+  directory.  The object files created by the compiler are always placed
+  in the same directory as the :samp:`WORK` library.
+
+  Use option :option:`-P` to specify where libraries other than :samp:`WORK`
+  are placed.
+
+
+.. option:: --std=<STD>
+
+  Specify the standard to use.  By default, the standard is :samp:`93c`, which
+  means VHDL-93 accepting VHDL-87 syntax.  For details on :samp:`STD` values see
+  :ref:`VHDL_standards`.
+
+
+.. option:: --ieee=<VER>
+
+  .. index:: ieee library
+  .. index:: synopsys library
+  .. index:: mentor library
+
+  Select the :samp:`IEEE` library to use. :samp:`VER` must be one of:
+
+  none
+    Do not supply an `IEEE` library.  Any library clause with the :samp:`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
+    :samp:`ieee` standards.  Currently, there are the multivalue logic system
+    packages :samp:`std_logic_1164` defined by IEEE 1164, the synthesis
+    packages , :samp:`numeric_bit` and :samp:`numeric_std` defined by IEEE
+    1076.3, and the :samp:`vital` packages :samp:`vital_timing` and
+    :samp:`vital_primitives`, defined by IEEE 1076.4.  The version of these
+    packages is defined by the VHDL standard used.  See :ref:`VITAL_packages`,
+    for more details.
+
+  synopsys
+    Supply the former packages and the following additional packages:
+    :samp:`std_logic_arith`, :samp:`std_logic_signed`,
+    :samp:`std_logic_unsigned`, :samp:`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 :samp:`ieee`.
+
+  mentor
+    Supply the standard packages and the following additional package:
+    :samp:`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.
+
+
+.. option:: -P<DIRECTORY>
+
+  Add `DIRECTORY` to the end of the list of directories to be searched for
+  library files.
+
+  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 :samp:`std_logic_arith`
+  package.  See :ref:`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 :samp:`numeric_std` package.
+
+
+.. option:: -frelaxed-rules
+
+  Within an object declaration, allow to reference the name (which
+  references the hidden declaration).  This ignores the error in the
+  following code:
+
+  .. code-block:: VHDL
+
+    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 :samp:`state1` constant start at the `constant`
+  word. Because the constant :samp:`state1` and the enumeration literal
+  :samp:`state1` are homograph, the enumeration literal is hidden in the
+  immediate scope of the constant).
+
+
+.. option:: -fpsl
+
+  Enable parsing of PSL assertions within comments.  See :ref:`PSL_implementation`,
+  for more details.
+
+
+.. 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 :samp:`VITAL_Level0` and :samp:`VITAL_Level1`, both
+  declared in the :samp:`ieee.VITAL_Timing` package.
+
+  Currently, VITAL checks are only partially implemented.  See
+  :ref:`VHDL_restrictions_for_VITAL`, for more details.
+
+
+.. 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.
+
+  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.
+
+
+.. option:: --PREFIX=<PATH>
+
+  Use :file:`PATH` as the prefix path to find commands and pre-installed (std and
+  ieee) libraries.
+
+
+.. option:: --GHDL1=<COMMAND>
+
+  Use :samp:`COMMAND` as the command name for the compiler.  If :samp:`COMMAND` is
+  not a path, then it is search in the list of program directories.
+
+
+.. option:: -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.
+
+
+
+.. option:: -Wc,<OPTION>
+
+  Pass `OPTION` as an option to the compiler.
+
+
+.. option:: -Wa,<OPTION>
+
+  Pass `OPTION` as an option to the assembler.
+
+
+.. option:: -Wl,<OPTION>
+
+  Pass `OPTION` as an option to the linker.
+
+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 :samp:`--warn-no-XXX`
+instead of :samp:`--warn-XXX`.
+
+
+.. option:: --warn-reserved
+
+  Emit a warning if an identifier is a reserved word in a later VHDL standard.
+
+
+.. 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 component if you don't use
+  configuration.  :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.
+
+  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.
+
+
+.. option:: --warn-library
+
+  Warns if a design unit replaces another design unit with the same name.
+
+
+.. option:: --warn-vital-generic
+
+  Warns if a generic name of a vital entity is not a vital generic name.  This
+  is set by default.
+
+
+.. 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).
+
+  These are checks for no wait statement in a procedure called in a
+  sensitized process and checks for pure rules of a function.
+
+
+.. option:: --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.
+
+
+.. option:: --warn-specs
+
+  Emit a warning if an all or others specification does not apply.
+
+
+.. option:: --warn-unused
+
+  Emit a warning when a subprogram is never used.
+
+
+.. option:: --warn-error
+
+  When this option is set, warnings are considered as errors.
+
+
+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
+--------------
+
+.. index:: importing files
+
+.. index:: *-i* 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 :ref:`Make_command`, to actually build the design.
+
+.. _Make_command:
+
+Make command
+------------
+
+.. index:: make
+
+.. index:: *-m* command
+
+
+Analyze automatically outdated files and elaborate a design::
+
+  ghdl -m [options] primary [secondary]
+
+
+The primary unit denoted by the :samp:`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 :option:`-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
+-------------------------
+
+.. index:: *--gen-makefile* command
+
+Generate a Makefile to build a design unit::
+
+  ghdl --gen-makefile [options] primary [secondary]
+
+
+This command works like the make command (see :ref:`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
+-----------------
+
+.. index:: displaying library
+
+.. index:: *-d* command
+
+Display the name of the units contained in a design library::
+
+  ghdl -d [options]
+
+
+The directory command, selected with the `-d` command line argument
+displays the content of the work design library.  All options are
+allowed, but only a few are meaningful: :option:`--work=NAME`,
+:option:`--workdir=PATH` and :option:`--std=VER`.
+
+Clean command
+-------------
+
+.. index:: cleaning
+
+.. index:: *--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:
+
+Remove command
+--------------
+
+.. index:: cleaning all
+
+.. index:: *--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:
+
+Copy command
+------------
+
+.. index:: copying library
+
+.. index:: *--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 :samp:`ieee` library:
+
+.. code-block:: shell
+
+  ghdl --copy --work=ieee --ieee=synopsys
+  ghdl -a --work=ieee numeric_unsigned.vhd
+
+
+.. _Create_a_Library:
+
+Create a Library
+----------------
+
+.. index:: create your own 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 :option:`--workdir` option::
+
+  ghdl -a --work=my_custom_lib --workdir=my_custom_libdir my_custom_lib_srcdir/my_file.vhd
+
+
+See also the :option:`-PPATH` command line option.
+
+.. _Cross-reference_command:
+
+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 :samp:`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 :samp:`file`  are analyzed, and then, if the analysis is
+successful, html files are generated in the directory specified by the
+:option:`-o dir` option, or :file:`html/` directory by default.
+
+If the option :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 :option:`--format=css` is specified, then the generated html 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.
+
+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
+--------------------
+
+.. index:: *--pp-html* command
+
+.. index:: pretty printing
+
+.. index:: vhdl to html
+
+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 :option:`--format=` option.
+By default or when the :option:`--format=html2` option is specified, the output
+is an HTML 2.0 file, with colours set through `<FONT>` tags.  When the
+:option:`--format=css` option is specified, the output is an HTML 4.0 file,
+with colours set through a CSS file, whose name is :file:`ghdl.css`.
+See :ref:`Cross-reference_command`, for more details about this CSS file.
+
+Find command
+------------
+
+.. index:: *-f* 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
+------------
+
+.. index:: *--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 :file:`NAME.vhdl`, where `NAME` is the name of the design
+unit.  For a package body, the filename is :file:`NAME-body.vhdl`.
+Finally, for an architecture `ARCH` of an entity `ENTITY`, the
+filename is :file:`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
+-------------
+
+.. index:: *--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:
+
+Help command
+------------
+
+.. index:: *-h* command
+
+.. index:: *--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:
+
+Disp config command
+-------------------
+
+.. index:: *--disp-config* command
+
+.. index:: display configuration
+
+Display the program paths and options used by GHDL::
+
+  ghdl --disp-config [options]
+
+
+This may be useful to track installation errors.
+
+Disp standard command
+---------------------
+
+.. index:: *--disp-standard* command
+
+.. index:: display :samp:`std.standard`
+
+Display the :samp:`std.standard` package::
+
+  ghdl --disp-standard [options]
+
+
+Version command
+---------------
+
+.. index:: *--version* command
+
+.. index:: version
+
+Display the `GHDL` version and exit::
+
+  ghdl --version
+
+
+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 :option:`--PREFIX=` command line option
+
+* the :envvar:`GHDL_PREFIX` environment variable
+
+*
+  a built-in default path.  It is a hard-coded path on GNU/Linux and the
+  value of the :samp:`HKLM\Software\Ghdl\Install_Dir` registry entry on Windows.
+
+You should use the :option:`--disp-config` command (:ref:`Disp_config_command` for details) to disp and debug installation problems.
+
+.. _ieee_library_pitfalls:
+
+IEEE library pitfalls
+=====================
+
+When you use options :option:`--ieee=synopsys` or :option:`--ieee=mentor`,
+the `IEEE` library contains non standard packages such as
+:samp:`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:
+
+.. code-block:: VHDL
+
+  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):
+
+.. code-block:: shell
+
+  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.
+:ref:`GHDL_options`, for more details.
+
+However it is easy to fix this error, by using a selected name:
+
+.. code-block:: VHDL
+
+  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:
+
+.. code-block:: VHDL
+
+  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
+==================
+
+.. index:: Math_Real
+
+.. index:: Math_Complex
+
+The :samp:`ieee` math packages (:samp:`math_real` and
+:samp:`math_complex`) provided with `GHDL` are fully compliant with
+the `IEEE` standard.
-- 
cgit v1.2.3