New documentation structure: ch. GHDL Usage #296
Comments
|
On 25/02/17 03:48, 1138-4EB wrote:
Following #280 <#280>, I need
some help to finish chapter 2:
*
There is a list of commands/options in Roadmap
<http://ghdl-devfork.readthedocs.io/en/new-documentation-structure/changelog/Roadmap.html#todos>,
which I obtained with |ghdl -h|, but I couldn't find any reference
in the doc. Which should be documented and which can be kept in the
todo-list?
Most of them are internal debugging commands. Maybe just a mention
would be ok.
--disp-order disp signals order
--disp-sources disp sources while displaying signals
--disp-sig-types disp signal types
--disp-signals-map disp map bw declared sigs and internal sigs
--disp-signals-table disp internal signals
--checks do internal checks after each process run
--activity=LEVEL watch activity of LEVEL signals: LEVEL is all, min
(default) or none (unsafe)
--dump-rti dump Run Time Information
--bootstrap allow --work=std
The VPI commands should be documented:
--vpi=FILENAME load VPI module
--vpi-trace[=FILE] trace vpi calls to FILE
Some commands are for testsuites:
--expect-failure invert exit status
--has-feature=X test presence of feature X
--list-features display the list of features
Some can be useful to the users:
--trace-signals disp signals after each cycle
--trace-processes disp process name before each cycle
--stats display run-time statistics
-C --mb-comments allow multi-bytes chars in a comment
--syn-binding use synthesis default binding rule
*
I added a subsection named 'Export waveforms' to 'Simulation and
runtime':
o Undocumented |–vcd-nodate do not write date in VCD file|. Relevant?
That's for testsuites. Not really relevant for users.
o In the manual of GtkWave it is explained that a pipe can be used
to pass a waveform directly, so that interactive simulation is
possible. However, only VCD is mentioned. Can it be done with
either FST or GHW?
No, I don't think so.
*
A also added a 'Export design hierarchy' subsection:
o /The json format is not documented, except it should be
self-documented. Maybe worth adding a small example?/ A sentence
explaining what is exported would be very helpful.
Option --psl-report= generate a JSON file at the end of the simulation
reporting for each PSL cover and assert statements the name, source
location and whether it passed or failed.
o /The XML format (for –file-to-xml) is not documented and it may
change as it shows internal stuff./
+ |--file-to-xml FILEs Dump AST in XML|
+ The AST in not mentioned in the documentation. I think that
including this feature is related to synthesis. Can you
provide a short paragraph explaining it's use case and why
does the AST change 'often'? Something like: /GHDL uses an
internal Abstract Syntax Tree (AST) to represent the
structure of an elaborated design. This structure holds all
the information that GHDL knows about the design. Then, due
to the addition or modification of features, it's format
changes quite often. Therefore, using........ is
recommended, since it's products are more stable between
releases. The XML output is meant for.../
The --file-to-xml command outputs an XML representation of the decorated
syntax tree for the input file and its dependencies. It can be used for
VHDL tooling using semantic information, like style checkers,
documentation extraction, complexity estimation... The AST slightly
changes from time to time (particularly when new nodes are added for new
language features), so be liberal in what is allowed by your tool.
Also, the XML can be quite large so consider it only during prototyping.
(Note that at this time there is no XML dump of the elaborated design).
Tristan.
|
|
While checking #200, @Paebbels and me realized that @tgingold makes difference between 'commands' and 'options'. However, Sphinx only supports 'programs' and 'options': http://www.sphinx-doc.org/en/1.5.1/domains.html#directive-option, where 'program' is 'ghdl' now. As a result, there is no clean way to reference GHDL 'commands' through intersphinx files. There are two possible solutions:
I'm going with the latter. Any ideas? |
|
A command in GHDL's words is just a parameter (or option in Sphinx's words). So e.g. You can then reduce the amount of @tgingold Maybe GHDL should have |
|
On 01/03/17 03:48, 1138-4EB wrote:
While checking #200 <#200>,
@Paebbels <https://github.com/Paebbels> and me realized that @tgingold
<https://github.com/tgingold> makes difference between 'commands' and
'options'. However, Sphinx only supports 'programs' and 'options':
http://www.sphinx-doc.org/en/1.5.1/domains.html#directive-option
As a result, there is no clean way to reference GHDL 'commands' through
intersphinx files. There are two possible solutions:
* Make each 'command' be a 'program'. The problem with this approach
is that, as long as I am aware about, Sphinx does not support
defining 'options' for multiple 'programs'. Therefore, we should
repeat all the common options.
* Make the 'commands' be 'options'. The user would tell the difference
depending on where are described in the doc. Documentation writers
should be aware that, although the same syntax is used, the usage is
not the same.
I'm going with the latter. Any ideas?
I agree with the latter.
|
|
On 01/03/17 03:57, Patrick Lehmann wrote:
A command in GHDL's words is just a parameter (or option in Sphinx's
words). So e.g. |-a| should be documented as |.. option:: -a|.
You can then reduce the amount of |index|directives, because options are
automatically indexed.
@tgingold <https://github.com/tgingold>
I know you like the short command names, but other tools usually have
commands without a dash and use commonly longer words. E.g. |git clone|
or |svn checkout|. Some programs support short forms too like |svn co|
for checkout.
Maybe GHDL should have |analyze|, |elaborate|, ... or |ana|, |elab|, ...
as a command name and |-a|, |-e| for backward compatibility. Especially,
with new commands, the space of meaningful one-character names becomes
smaller.
Why not.
Note that most of the new commands don't have one-character name, so
there is no real small space issue.
Tristan.
|
|
On 01/03/17 03:48, 1138-4EB wrote:
While checking #200 <#200>,
@Paebbels <https://github.com/Paebbels> and me realized that @tgingold
<https://github.com/tgingold> makes difference between 'commands' and
'options'. However, Sphinx only supports 'programs' and 'options':
http://www.sphinx-doc.org/en/1.5.1/domains.html#directive-option
As a result, there is no clean way to reference GHDL 'commands' through
intersphinx files. There are two possible solutions:
* Make each 'command' be a 'program'. The problem with this approach
is that, as long as I am aware about, Sphinx does not support
defining 'options' for multiple 'programs'. Therefore, we should
repeat all the common options.
* Make the 'commands' be 'options'. The user would tell the difference
depending on where are described in the doc. Documentation writers
should be aware that, although the same syntax is used, the usage is
not the same.
I'm going with the latter. Any ideas?
...
But there is still a possible issue: if both command CMD1 and CMD2 have
an option OPT with the same name, we cannot document OPT two times.
(Not sure that such a clash exists).
|
I am actually following a triple approach:
On top of that, I modified the declaration of every option (commands and options), to add Check: |
|
On 01/03/17 05:35, 1138-4EB wrote:
A command in GHDL's words is just a parameter (or option in Sphinx's
words). So e.g. -a should be documented as .. option:: -a.
You can then reduce the amount of indexdirectives, because options
are automatically indexed.
I am actually following a triple approach:
* I converted all the 'commands' to options. Then a reference is
created in the index.
* I added a manual index of the form 'cmd XXXXX' or 'cmd library
XXXXX' to let the user know which options are commands.
* Commands have a header, so that they are shown in the sidebar.
On top of that, I modified the declaration of every option (commands and
options), to add |< >|. This is a major improvement since allows to use
liked references like:
|:option:`-e` :option:`--work` :option:`--PREFIX` |
Check:
* http://ghdl-devfork.readthedocs.io/en/alt-new/using/InvokingGHDL.html
* http://ghdl-devfork.readthedocs.io/en/alt-new/genindex.html
Wonderful!
Thank you for improving the doc. I have never spent enough time on it.
Tell me when you think it's ok for a merge.
Tristan.
|
That would be the case if I think that, even if you add 'ghdl analyze' and so, we should keep with this approach. If not, we would be facing the problem you describe: 'ghdl analyze' and 'ghdl elaborate' would share some options. Therefore, we would need to describe all twice (once in each 'program space'). |
I think this is solvable. I let |
I still need some time to check it. However #297 is ready to be merged, if you agree. |
|
@tgingold, I think it's ready now. See http://ghdl-devfork.readthedocs.io/en/new-documentation-structure/using/QuickStartGuide.html There are two missing points:
Furthermore, it'd be great to add some more content to section Since I'm going to start with ch 3 (Getting GHDL), I think you can merge my As a reference, after ch 3, I'll go with ch 4, then ch 5. Last, I'll review all of them to integrate the suggestions you do. Meanwhile I'll periodically check your branch, to integrate any changes. This way, I hope that all my PRs will be fast-forwarded. |
|
On 01/03/17 08:08, 1138-4EB wrote:
@tgingold <https://github.com/tgingold>, I think it's ready now. See
http://ghdl-devfork.readthedocs.io/en/new-documentation-structure/using/QuickStartGuide.html
There are two missing points:
* |Quick Start Guide / Further examples| has no content (yet). I'll
move forward to the remaining chapters, and check this later.
* |--vpi=FILENAME| and |--vpi-trace[=FILE]| should go in |Invoking
GHDL / VPI build commands| or in |Simulation and runtime|? In the
latter, in which subsection?
That should go to simulation and runtime, as this is a runtime option.
Not sure we need a specific subsection.
Furthermore, it'd be great to add some more content to section
|Simulation and runtime / Debugging|, where I added some of the
previously undocumented features.
Since I'm going to start with ch 3 (Getting GHDL), I think you can merge
my |new-documentation-structure| branch to your
|new-documentation-structure| branch. Then, you can improve the parts
you find unclear in ch 2, so that possible collisions are minimized.
Done.
Tristan.
|
Sorry, I meant in which of the current four subsections in These subsections are:
On top of telling where to put |
|
On 01/03/17 22:34, 1138-4EB wrote:
That should go to simulation and runtime, as this is a runtime
option. Not sure we need a specific subsection.
Sorry, I meant in which of the current four subsections in |Simulation
and runtime| it should go, not to add a specific one. Didn't explain
myself correctly.
These subsections are:
* Simulation options
o --assert-level
o --ieee-asserts
o --stop-time
o --stop-delta
o --disp-time
o --unbuffered
o --sdf
o --help
* Export waveforms
o --read-opt-file
o --write-opt-file
o --vcd
o --vcdgz
o --vcd-nodate
o --fst
o --wave
* Export hierarchy and references
o --disp-tree
o --no-run
o --xref-html
o --psl-report
o --file-to-xml
* Debugging
o --trace-signals
o --trace-processes
o --stats
o --disp-order
o --disp-sources
o --disp-sig-types
o --disp-signals-map
o --disp-signals-table
o --checks
o --activity
o --dump-rti
o --bootstrap
On top of telling where to put |--vpi| and |--vpi-trace|, you might want
to reorder some of those, remove any of the subsections, etc. Write the
order youd like here, and I'll update it in the next iteration.
Simulation options looks fine to me.
|
Following #280, I need some help to finish chapter 2:
There is a list of commands/options in Roadmap, which I obtained with
ghdl -h, but I couldn't find any reference in the doc. Which should be documented and which can be kept in the todo-list?I added a subsection named 'Export waveforms' to 'Simulation and runtime':
–vcd-nodate do not write date in VCD file. Relevant?A also added a 'Export design hierarchy' subsection:
--file-to-xml FILEs Dump AST in XMLThe text was updated successfully, but these errors were encountered: