From 48cb17bc2a6fd8ee130e549f3b8d13bf20dedcef Mon Sep 17 00:00:00 2001 From: 1138-4EB <1138-4EB@users.noreply.github.com> Date: Tue, 28 Feb 2017 22:19:30 +0100 Subject: Describe commands as options. Fix internal refs to options. Apply suggestions about ch 2. Add options given by the executable but not documented earlier. --- doc/changelog/Meta.rst | 15 +- doc/changelog/Roadmap.rst | 26 +--- doc/conf.py | 3 +- doc/getting/Building.rst | 18 ++- doc/references/CommandReference.rst | 135 +++++++--------- doc/using/InvokingGHDL.rst | 301 +++++++++++------------------------- doc/using/QuickStartGuide.rst | 30 ++-- doc/using/Simulation.rst | 145 ++++++++++++----- 8 files changed, 310 insertions(+), 363 deletions(-) diff --git a/doc/changelog/Meta.rst b/doc/changelog/Meta.rst index 4b86d7d32..b14927205 100644 --- a/doc/changelog/Meta.rst +++ b/doc/changelog/Meta.rst @@ -5,7 +5,7 @@ Meta * Python snippet for Sphinx's `conf.py` to extract the current version number from Git (latest tag name). - * :ghdlsharp:`200` + * :ghdlsharp:`200`, :ghdlsharp:`221` * Reference :samp:`genindex.html` from the navigation bar. @@ -15,4 +15,17 @@ Meta * :ghdlsharp:`200` +* Intersphinx files + + * :ghdlsharp:`200` + * To decompress the inventory file: `curl -s http://ghdl.readthedocs.io/en/latest/objects.inv | tail -n+5 | openssl zlib -d`. From `how-to-uncompress-zlib-data-in-unix `_. + * External ref and link to section:: + + :ref:`GHDL Roadmap ` + + * External ref to option (no link):: + + :ghdl:option:`--ieee` + :option:`ghdl:--ieee` + * Ubuntu uses `dash` instead of `bash` when a shell script is run. As a result, some functionalities, such as arrays like :samp:`array[1]`, are not supported. Therefore, build scripts in `dist/linux` should not use those functionalities unless they are sourced in a `bash` shell. That is, :file:`tavis-ci.sh` uses arrays, since it is sourced in the Travis CI machine. But :file:`docker-buildtest.sh` and :file:`buildtest.sh` do not use any. The same applies to the scripts in `testsuite`. \ No newline at end of file diff --git a/doc/changelog/Roadmap.rst b/doc/changelog/Roadmap.rst index 5dfba58b1..93589170e 100644 --- a/doc/changelog/Roadmap.rst +++ b/doc/changelog/Roadmap.rst @@ -22,27 +22,11 @@ TODOs Options shown in the command line help, but not found in the doc: -* :samp:`--expect-failure invert exit status` -* :samp:`--has-feature=X test presence of feature X` -* :samp:`--list-features display the list of features` -* :samp:`--vpi=FILENAME load VPI module` -* :samp:`--vpi-trace[=FILE] trace vpi calls to FILE` -* :samp:`--dump-rti dump Run Time Information` -* :samp:`--trace-signals disp signals after each cycle` -* :samp:`--trace-processes disp process name before each cycle` -* :samp:`--stats display run-time statistics` -* :samp:`--disp-order disp signals order` -* :samp:`--disp-sources disp sources while displaying signals` -* :samp:`--disp-sig-types disp signal types` -* :samp:`--disp-signals-map disp map bw declared sigs and internal sigs` -* :samp:`--disp-signals-table disp internal signals` -* :samp:`--checks do internal checks after each process run` -* :samp:`--activity=LEVEL watch activity of LEVEL signals: LEVEL is all, min (default) or none (unsafe)` -* :samp:`-C --mb-comments allow multi-bytes chars in a comment` - - * https://github.com/tgingold/ghdl/issues/132 - -* :samp:`--bootstrap allow --work=std` * :samp:`--syn-binding use synthesis default binding rule` +* VPI Commands + + * :samp:`--vpi=FILENAME load VPI module` + * :samp:`--vpi-trace[=FILE] trace vpi calls to FILE` + .. todolist:: \ No newline at end of file diff --git a/doc/conf.py b/doc/conf.py index 516275077..a4eee999f 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -348,7 +348,8 @@ texinfo_documents = [ # Sphinx.Ext.InterSphinx # ============================================================================== intersphinx_mapping = { - 'python': ('https://docs.python.org/3.5/', None) + 'python': ('https://docs.python.org/3.5/', None), + 'poc': ('http://poc-library.readthedocs.io/en/release', None), # 'ghdl': ('http://ghdl.readthedocs.io/en/latest', None) } diff --git a/doc/getting/Building.rst b/doc/getting/Building.rst index 64e72bccb..9df115f3c 100644 --- a/doc/getting/Building.rst +++ b/doc/getting/Building.rst @@ -31,6 +31,11 @@ After making your choice, you can jump to the corresponding section below. Howev - @1138 Backtraces optional -patchable- - Very briefly, why is mcode faster for analysis and GCC/LLVM for simulation? - The only other dependency is zlib (On ubuntu/debian, install zlib1g-dev). + - From :ghdlsharp:`279`: + - GCC: GHDL generates an intermediate representation for GCC, which creates an executable. So GHDL acts a a new language frontend like C for the GCC and uses the existing backend to generated e.g. x86(-64) binary code. + - LLVM: GHDL generates instructions for the LLVM abstract register machine, which then generates x86(-64) instructions for the host system. + - mcode: GHDL generates the x86(-64) instructions in memory and executes the model. + - gcc is currently only supported on Linux, because you need to compile a complete GCC from zero and add GHDL as a frontend into the GCC. Compiling the complete GCC suite plus GHDL takes a lot of time. I think it's not possible to finish the compile task in the bounds of a Travis-CI run. .. _BUILD:dir_structure: @@ -53,7 +58,7 @@ Directory structure * :samp:`mcode`: - * :samp:`appveyor`: + * :samp:`appveyor`: * :samp:`doc`: `Markdown` and `reStructuredText` sources and auxiliar files to build the documentation with `Sphinx `_. Indeed, `Read the docs `_ (RTD) is used to automatically build and deploy this site and/or PDF you are reading. @@ -71,8 +76,10 @@ Directory structure - [@1138-4EB|@Paebbels] Replace link to VendorPrimitives, when the file is translated from md to rst. - - [@Paebbels] Add brief description of how the content in dist/windows is ordered. - + - [@Paebbels] Add brief description of how the content in dist/windows is ordered. From :ghdlsharp:`279`: + - The content in dist/appveyor is for the AppVeyor flow. AppVeyor is a continuous integration service like Travis-CI, but is offers a Windows Server 2012 R2 machine. The AppVeyor flow has more scripts than the Travis-CI flow, so we put them into a separate directory. + - The code in dist/windows/mcode is special code needed to build mcode in windows. mcode is supported on Linux (32/64-bit) and Windows (32-bit). + Mcode backend ================= @@ -196,4 +203,7 @@ Test suites .. TODO:: - @1138 explain that there are two (maybe three with vhdl08 tests) \ No newline at end of file + * @1138 explain that there are two (maybe three with vhdl08 tests) + * :samp:`--expect-failure invert exit status` + * :samp:`--has-feature=X test presence of feature X` + * :samp:`--list-features display the list of features` \ No newline at end of file diff --git a/doc/references/CommandReference.rst b/doc/references/CommandReference.rst index 771d2386e..4adb2dd36 100644 --- a/doc/references/CommandReference.rst +++ b/doc/references/CommandReference.rst @@ -1,3 +1,4 @@ +.. program:: ghdl .. _REF:Command: Command Reference @@ -5,19 +6,24 @@ Command Reference .. HINT:: The most common commands and options are shown in section :ref:`USING:Invoking`. Here the advanced and experimental features are described. +Environment variables +============= + +.. envvar:: GHDL_PREFIX + + .. TODO:: Add short description to :option:`GHDL_PREFIX` + Misc commands ============= There are a few GHDL commands which are seldom useful. -.. _Help_command: +.. index:: cmd help Help [:samp:`-h`] ------------ -.. index:: -h command - -.. index:: --help command +.. option:: --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 @@ -27,57 +33,46 @@ for this later command are displayed:: ghdl -h ghdl -h command - -.. _Disp_config_command: - +.. index:: cmd display configuration + Display config [:samp:`--disp-config`] ------------------- -.. index:: --disp-config command - -.. index:: display configuration - -:samp:`ghdl --disp-config [options]` +.. option:: --disp-config <[options]> Display the program paths and options used by GHDL. This may be useful to track installation errors. +.. index:: cmd display standard +.. index:: display :samp:`std.standard` + Display standard [:samp:`--disp-standard`] --------------------- -.. index:: --disp-standard command - -.. index:: display :samp:`std.standard` - -:samp:`ghdl --disp-standard [options]` +.. option:: --disp-standard <[options]> Display the :samp:`std.standard` package. +.. index:: cmd version + Version [:samp:`--version`] --------------- -.. index:: --version command - -.. index:: version +.. option:: --version, -v -:samp:`ghdl --version` - -Display the `GHDL` version and exit. +Display the GHDL version and exit. 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. +.. index:: cmd file pretty printing +.. index:: vhdl to html + Pretty print [:samp:`--pp-html`] -------------------- -.. index:: --pp-html command - -.. index:: pretty printing - -.. index:: vhdl to html - -:samp:`ghdl --pp-html [options] file...` +.. option:: --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. @@ -86,21 +81,21 @@ 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 `` 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. +.. index:: cmd file find + Find [:samp:`-f`] ------------ -.. index:: -f command - -:samp:`ghdl -f file...` +.. option:: -f 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. +.. index:: cmd file chop + Chop [:samp:`--chop`] ------------ -.. index:: --chop command - -:samp:`ghdl --chop files` +.. option:: --chop The provided files are read, and a file is written in the current directory for every design unit. Each filename is build according to the type: @@ -114,87 +109,73 @@ 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. +.. index:: cmd file lines + Lines [:samp:`--lines`] ------------- -.. index:: --lines command - -:samp:`ghdl --lines files` +.. option:: --lines Display on the standard output lines of files preceded by line number. GCC/LLVM only commands ================= -.. _Bind_command: +.. index:: cmd GCC/LLVM binding Bind [:samp:`--bind`] ------------ -.. index:: binding - -.. index:: --bind command - -:samp:`ghdl --bind [options] primary_unit [secondary_unit]` +.. option:: --bind <[options] primary_unit [secondary_unit]> 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: +.. index:: cmd GCC/LLVM linking Link [:samp:`--link`] ------------ -.. index:: linking - -.. index:: --link command - -:samp:`ghdl --link [options] primary_unit [secondary_unit]` +.. option:: --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_command: +.. index:: cmd GCC/LLVM list link List link [:samp:`--list-link`] ----------------- -.. index:: --list-link command - -:samp:`ghdl --list-link primary_unit [secondary_unit]` +.. option:: --list-link 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. -GHDL options +Options ================= +.. option:: --mb-comments, -C + +Allow multi-bytes chars in a comment + .. 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 synthesizer rule. +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. +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. +This option is only useful during elaboration. -.. option:: --GHDL1= +.. option:: --GHDL1<=COMMAND> - Use :samp:`COMMAND` as the command name for the compiler. If :samp:`COMMAND` is - not a path, then it is searched in the path. +Use :samp:`COMMAND` as the command name for the compiler. If :samp:`COMMAND` is not a path, then it is searched in the path. -.. option:: --AS= +.. option:: --AS<=COMMAND> - Use :samp:`COMMAND` as the command name for the assembler. If :samp:`COMMAND` is - not a path, then it is searched in the path. The default is :samp:`as`. +Use :samp:`COMMAND` as the command name for the assembler. If :samp:`COMMAND` is not a path, then it is searched in the path. The default is :samp:`as`. -.. option:: --LINK= +.. option:: --LINK<=COMMAND> - Use :samp:`COMMAND` as the linker driver. If :samp:`COMMAND` is - not a path, then it is searched in the path. The default is :samp:`gcc`. +Use :samp:`COMMAND` as the linker driver. If :samp:`COMMAND` is not a path, then it is searched in the path. The default is :samp:`gcc`. Passing options to other programs ================================= @@ -207,12 +188,12 @@ Both the compiler and the linker are in fact GCC programs. See the GCC manual fo .. option:: -Wc,