v0.23.0

VHDL · Feb 5, 2023 · 14ec13b · 14ec13b
2 parents 7a4b0e0 + cb46f1e
commit 14ec13b
Show file tree

Hide file tree

Showing 12 changed files with 484 additions and 19 deletions.
diff --git a/doc/Analyze/index.rst b/doc/Analyze/index.rst
@@ -0,0 +1,103 @@
+.. _analyze:
+
+Analyze
+#######
+
+1. Dependency analysis
+
+Dependency Analysis
+*******************
+
+1. Create Dependency Graph
+==========================
+
+Create unconnected vertices in the design's dependency graph for every VHDL library object and every design unit.
+
+The vertex's ``ID`` field is set to a unique identifying string. |br|
+The following patterns are used:
+
+Libraries
+   The normalized library name: ``library``.
+Contexts
+   The normalized library and context name: ``library.context``.
+Entities
+   The normalized library and entity name: ``library.entity``.
+Architectures
+   The normalized library, entity and architecture name in parenthesis: ``library.entity(architecture)``.
+Packages
+   The normalized library and package name: ``library.package``.
+Package Bodies
+   The normalized library and package name: ``library.package(body)``.
+
+The vertex's ``Value`` field references to the library or design unit object respectively.
+
+Each vertex has two attributes:
+
+``"kind"``
+   A kind attribute is set to an enumeration value of :py:class:`~pyVHDLModel.DependencyGraphVertexKind` representing
+   vertex kind (type).
+``"predefined"``
+   A predefined attribute is set to ``True``, if the library or design unit is a VHDL predefined language entity from
+   e.g. from ``std`` or ``ieee``.
+
+Lastly, every vertex is assigned to a :py:attr:``~pyVHDLModel.DesignUnit.DesignUnit._dependencyVertex`` field. Thus,
+there is a double reference from graph's vertex via ``Value`` to the DOM object as well as in reverse via
+``_dependencyVertex`` to the representing vertex.
+
+.. code-block:: vhdl
+
+   predefinedLibraries = ("std", "ieee")
+
+   for libraryIdentifier, library in self._libraries.items():
+     dependencyVertex = Vertex(vertexID=f"{libraryIdentifier}", value=library, graph=self._dependencyGraph)
+     dependencyVertex["kind"] = DependencyGraphVertexKind.Library
+     dependencyVertex["predefined"] = libraryIdentifier in predefinedLibraries
+     library._dependencyVertex = dependencyVertex
+
+     for contextIdentifier, context in library._contexts.items():
+       dependencyVertex = Vertex(vertexID=f"{libraryIdentifier}.{contextIdentifier}", value=context, graph=self._dependencyGraph)
+       dependencyVertex["kind"] = DependencyGraphVertexKind.Context
+       dependencyVertex["predefined"] = context._library._normalizedIdentifier in predefinedLibraries
+       context._dependencyVertex = dependencyVertex
+
+
+2. Create Compile Order Graph
+=============================
+
+3. Index Packages
+=================
+
+4. Index Architectures
+======================
+
+5. Link Contexts
+================
+
+6. Link Architectures
+=====================
+
+7. Link Package Bodies
+======================
+
+8. Link Library References
+==========================
+
+9. Link Package References
+==========================
+
+10. Link Context References
+===========================
+
+11. Link Components
+===================
+
+12. Link Instantiations
+=======================
+
+13. Create Hierarchy Graph
+==========================
+
+14. Compute Compile Order
+=========================
+
+
diff --git a/doc/DataStructure/CompileOrderGraph.rst b/doc/DataStructure/CompileOrderGraph.rst
@@ -0,0 +1,4 @@
+.. _datastruct:compileorder:
+
+Compile Order Graph
+###################
diff --git a/doc/DataStructure/DependencyGraph.rst b/doc/DataStructure/DependencyGraph.rst
@@ -0,0 +1,4 @@
+.. _datastruct:dependgraph:
+
+Dependency Graph
+################
diff --git a/doc/DataStructure/HierarchyGraph.rst b/doc/DataStructure/HierarchyGraph.rst
@@ -0,0 +1,4 @@
+.. _datastruct:dependgraph:
+
+Hierarchy Graph
+###############
diff --git a/doc/DataStructure/index.rst b/doc/DataStructure/index.rst
@@ -0,0 +1,70 @@
+.. _datastruct:
+
+Data Structures
+###############
+
+Besides the document object model as a tree-like structure, pyVHDLModel has either lists, lookup dictionaries, direct
+cross-references or dedicated data structure (tree, graph, …) for connecting multiple objects together.
+
+Graphs
+******
+
+pyVHDLModel uses the graph implementation from :pyTool:mod:`pyTooling.Graph` as it provides an object oriented programming
+interface to vertices and edges.
+
+Dependency Graph
+================
+
+The dependency graph describes dependencies between:
+
+* Sourcecode files
+* VHDL libraries
+* Contexts
+* Packages
+* Entities
+* Architectures
+* Packages
+* Package Bodies
+* Configurations
+
+The relation can be:
+
+* Defined in source file
+* references
+* implements
+* instantiates
+* needs to be analyzed before
+
+
+Hierarchy Graph
+===============
+
+The hierarchy graph can be derived from dependency graph by:
+
+1. copying all entity and architecture vertices
+2. copying all implements dependency edges
+3. copying all instantiates edges in reverse direction
+
+The graph can then be scanned for a root vertices (no inbound edges). If only a single root vertex exists, this vertex
+references the toplevel of the design.
+
+
+Compile Order Graph
+===================
+
+The compile order can be derived from dependency graph by:
+
+1. copying all document vertices
+2. iterating all edges in the dependency graph.
+   1. resolve the source and the destination to the referenced design units
+   2. resolved further to the documents these design units are declared in
+   3. resolve further which vertices correspond in the compile order graph
+   4. if edges does not yet exist, add an edge between two documents in the compile order graph
+
+
+.. toctree::
+   :hidden:
+
+   DependencyGraph
+   HierarchyGraph
+   CompileOrderGraph
diff --git a/doc/Dependency.rst b/doc/Dependency.rst
@@ -23,7 +23,7 @@ pyVHDLModel Package
 +--------------------------------------------------------+-------------+------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
 | **Package**                                            | **Version** | **License**                                                                              | **Dependencies**                                                                                                                |
 +========================================================+=============+==========================================================================================+=================================================================================================================================+
-| `pyTooling <https://GitHub.com/pyTooling/pyTooling>`__ | ≥2.11.0      | `Apache License, 2.0 <https://GitHub.com/pyTooling/pyTooling/blob/master/LICENSE.txt>`__ |                                                                                                                                 |
+| `pyTooling <https://GitHub.com/pyTooling/pyTooling>`__ | ≥2.11.0     | `Apache License, 2.0 <https://GitHub.com/pyTooling/pyTooling/blob/master/LICENSE.txt>`__ | *None*                                                                                                                          |
 +--------------------------------------------------------+-------------+------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
 
 
@@ -55,7 +55,7 @@ the mandatory dependencies too.
 +-----------------------------------------------------------+-------------+----------------------------------------------------------------------------------------+----------------------+
 | `pytest-cov <https://GitHub.com/pytest-dev/pytest-cov>`__ | ≥4.0.0      | `MIT <https://GitHub.com/pytest-dev/pytest-cov/blob/master/LICENSE>`__                 | *Not yet evaluated.* |
 +-----------------------------------------------------------+-------------+----------------------------------------------------------------------------------------+----------------------+
-| `Coverage <https://GitHub.com/nedbat/coveragepy>`__       | ≥7.0        | `Apache License, 2.0 <https://GitHub.com/nedbat/coveragepy/blob/master/LICENSE.txt>`__ | *Not yet evaluated.* |
+| `Coverage <https://GitHub.com/nedbat/coveragepy>`__       | ≥7.1        | `Apache License, 2.0 <https://GitHub.com/nedbat/coveragepy/blob/master/LICENSE.txt>`__ | *Not yet evaluated.* |
 +-----------------------------------------------------------+-------------+----------------------------------------------------------------------------------------+----------------------+
 | `mypy <https://GitHub.com/python/mypy>`__                 | ≥0.990      | `MIT <https://GitHub.com/python/mypy/blob/master/LICENSE>`__                           | *Not yet evaluated.* |
 +-----------------------------------------------------------+-------------+----------------------------------------------------------------------------------------+----------------------+
@@ -123,7 +123,7 @@ install the mandatory dependencies too.
 +----------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
 | **Package**                                                                | **Version**  | **License**                                                                                              | **Dependencies**                                                                                                                                     |
 +============================================================================+==============+==========================================================================================================+======================================================================================================================================================+
-| `pyTooling <https://GitHub.com/pyTooling/pyTooling>`__                     | ≥2.11.0       | `Apache License, 2.0 <https://GitHub.com/pyTooling/pyTooling/blob/main/LICENSE.md>`__                    | *None*                                                                                                                                               |
+| `pyTooling <https://GitHub.com/pyTooling/pyTooling>`__                     | ≥2.11.0      | `Apache License, 2.0 <https://GitHub.com/pyTooling/pyTooling/blob/main/LICENSE.md>`__                    | *None*                                                                                                                                               |
 +----------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
 | `wheel <https://GitHub.com/pypa/wheel>`__                                  | ≥0.38.1      | `MIT <https://github.com/pypa/wheel/blob/main/LICENSE.txt>`__                                            | *Not yet evaluated.*                                                                                                                                 |
 +----------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+