Provide initial skeleton for libghdl documentation. #1445
Conversation
eine
added
Documentation: General
|
FTR, I believe this is the most simple (and single) example available using libghdl: https://github.com/ghdl/ghdl/tree/master/testsuite/python/units01 |
doc/libghdl/ASTTraversing.rst
Outdated
| AST Traversing | ||
| ############## | ||
|
|
||
| If someone wants to use `libghdl`, then he probably wants to know how to traverse the AST to get the information about nodes of design units. |
There was a problem hiding this comment.
There are examples of traverse functions in pyutils.py. The function nodes_iter is a visitor on all nodes, while declarations_iter and concurrent_stmts_iter are more selective.
doc/libghdl/ASTTraversing.rst
Outdated
| ############## | ||
|
|
||
| If someone wants to use `libghdl`, then he probably wants to know how to traverse the AST to get the information about nodes of design units. | ||
| It would be really nice to provide an example showing how to traverse the tree. |
There was a problem hiding this comment.
Have a look at vhdl_langserver/symbols.py to see how symbols are gathered from a vhdl file. Or references.py.
doc/libghdl/ASTTraversing.rst
Outdated
| In the `vhdl_ls` Load_File function is used to parse the file and get the tree root. | ||
| The return value is an integer. | ||
|
|
||
| * What does this integer represent? |
There was a problem hiding this comment.
It is not an integer, but a reference to a node (which is an index so indeed an integer). In Ada the fact that this is an integer is almost hidden, but that is clear in the low-level binding. (Hence a reason why we should have a high-level and more pythonic API).
The value, if not null, represents an Iir_Kind_Design_File.
doc/libghdl/ASTTraversing.rst
Outdated
| The return value is an integer. | ||
|
|
||
| * What does this integer represent? | ||
| * How to use this integer to traverse the AST and get information about nodes? |
There was a problem hiding this comment.
I think you can call the various iterators defined in pyutils.py
doc/libghdl/Initialization.rst
Outdated
|
|
||
| To be able to use `libghdl`, it first must be initialized. | ||
|
|
||
| * Why does it must be initialized? |
There was a problem hiding this comment.
There are many data that must be set up, like the name table. You cannot do anything useful without it. And then there are also some higher levels constructs that should also be initialized, like the content of the ieee library.
doc/libghdl/Initialization.rst
Outdated
|
|
||
| * Why does it must be initialized? | ||
| * What does the initialization do? | ||
| * Is there any use case where someone would want to use libghdl without initialization? |
doc/libghdl/Initialization.rst
Outdated
| * Why does it must be initialized? | ||
| * What does the initialization do? | ||
| * Is there any use case where someone would want to use libghdl without initialization? | ||
| * If no, then why it does not initialize itself automatically? |
There was a problem hiding this comment.
One reason is because it is a low-level binding. The other reason is because some initialization (like which ieee library is loaded) depends on some options.
doc/libghdl/Initialization.rst
Outdated
|
|
||
| .. code-block:: python | ||
|
|
||
| libghdl.libghdl_init() |
There was a problem hiding this comment.
This one does Ada elaboration. Nothing visible and could be automatic (but that would make the build infrastructure more complex).
doc/libghdl/Initialization.rst
Outdated
| .. code-block:: python | ||
|
|
||
| libghdl.libghdl_init() | ||
| libghdl.libghdl__set_hooks_for_analysis() |
There was a problem hiding this comment.
Basically, it defines the back-end, which is invoked when a unit is analyzed.
doc/libghdl/Initialization.rst
Outdated
|
|
||
| # Set the prefix in order to locate the vhdl libraries. | ||
| libghdl.libghdl__set_exec_prefix( | ||
| *_to_char_p(dirname(dirname(_libghdl_path)).encode('utf-8'))) |
There was a problem hiding this comment.
If the comment is not clear enough, please tell me.
But this is 'just' the start of the initialization. If you look at vhdl_langsever/workspace.py you will see the remaining (in __init__):
- redirecting errors
- setting flags and options
- end of initialization (load libraries).
doc/libghdl/Overview.rst
Outdated
|
|
||
| Here we should write superficially how `libghdl` works. | ||
|
|
||
| * Does it return structures such as AST to the calling code, or does it store them internally? |
There was a problem hiding this comment.
The AST are always internally stored. The reason is that a unit may reference another unit.
At some point, we may want to introduce a notion of context that would contain all the global variables.
doc/libghdl/Overview.rst
Outdated
| Here we should write superficially how `libghdl` works. | ||
|
|
||
| * Does it return structures such as AST to the calling code, or does it store them internally? | ||
| * Is it thread safe? |
|
@m-kru, did you close this on purpose? Or was it an undesired effect of updating your master branch? |
|
@eine ehhh, again undesired effect. |
|
Do you know how to get it back? |
Reopen of #1441