v0.23.0

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
+=========================
+
+

doc/DataStructure/CompileOrderGraph.rst

@@ -0,0 +1,4 @@
+.. _datastruct:compileorder:
+
+Compile Order Graph
+###################

doc/DataStructure/DependencyGraph.rst

@@ -0,0 +1,4 @@
+.. _datastruct:dependgraph:
+
+Dependency Graph
+################

doc/DataStructure/HierarchyGraph.rst

@@ -0,0 +1,4 @@
+.. _datastruct:dependgraph:
+
+Hierarchy Graph
+###############

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

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.* |
 +----------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+