From e3aba0cb3d58cdd61ec5f5c5ecc18e0dfb52e29d Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Thu, 12 Jan 2023 00:50:06 +0100 Subject: [PATCH 1/9] Documenting newly added algorithms. --- doc/Analyze/index.rst | 61 ++++++++++++++++++++++++ doc/DataStructure/CompileOrderGraph.rst | 0 doc/DataStructure/DependencyGraph.rst | 0 doc/DataStructure/HierarchyGraph.rst | 0 doc/DataStructure/index.rst | 62 +++++++++++++++++++++++++ doc/conf.py | 2 + doc/index.rst | 2 + pyVHDLModel/__init__.py | 2 +- 8 files changed, 128 insertions(+), 1 deletion(-) create mode 100644 doc/Analyze/index.rst create mode 100644 doc/DataStructure/CompileOrderGraph.rst create mode 100644 doc/DataStructure/DependencyGraph.rst create mode 100644 doc/DataStructure/HierarchyGraph.rst create mode 100644 doc/DataStructure/index.rst diff --git a/doc/Analyze/index.rst b/doc/Analyze/index.rst new file mode 100644 index 000000000..961b2b42b --- /dev/null +++ b/doc/Analyze/index.rst @@ -0,0 +1,61 @@ +.. _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 diff --git a/doc/DataStructure/CompileOrderGraph.rst b/doc/DataStructure/CompileOrderGraph.rst new file mode 100644 index 000000000..e69de29bb diff --git a/doc/DataStructure/DependencyGraph.rst b/doc/DataStructure/DependencyGraph.rst new file mode 100644 index 000000000..e69de29bb diff --git a/doc/DataStructure/HierarchyGraph.rst b/doc/DataStructure/HierarchyGraph.rst new file mode 100644 index 000000000..e69de29bb diff --git a/doc/DataStructure/index.rst b/doc/DataStructure/index.rst new file mode 100644 index 000000000..e7a62f32e --- /dev/null +++ b/doc/DataStructure/index.rst @@ -0,0 +1,62 @@ +.. _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 diff --git a/doc/conf.py b/doc/conf.py index e52ad5975..ad6271774 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -198,6 +198,8 @@ intersphinx_mapping = { 'python': ('https://docs.python.org/3', None), 'vasg': ('https://IEEE-P1076.gitlab.io/', None), + 'pyTool': ('https://pyTooling.github.io/pyTooling/', None), + 'ghdl': ('https://GHDL.github.io/ghdl/', None), } diff --git a/doc/index.rst b/doc/index.rst index 2b41446a9..05f359b1c 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -224,6 +224,8 @@ License :hidden: LanguageModel/index + Analyze/index + DataStructure/index .. raw:: latex diff --git a/pyVHDLModel/__init__.py b/pyVHDLModel/__init__.py index 6a7fad0ed..4a98b67ef 100644 --- a/pyVHDLModel/__init__.py +++ b/pyVHDLModel/__init__.py @@ -48,7 +48,7 @@ __email__ = "Paebbels@gmail.com" __copyright__ = "2016-2023, Patrick Lehmann" __license__ = "Apache License, Version 2.0" -__version__ = "0.22.1" +__version__ = "0.23.0" from enum import unique, Enum, Flag, auto From a1b50dd4059775f0b27b97f3c7e763316e65a170 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Thu, 12 Jan 2023 14:06:34 +0100 Subject: [PATCH 2/9] Added getting started documentation page. --- doc/GettingStarted.rst | 260 +++++++++++++++++++++++++++++++++++++++++ doc/index.rst | 1 + 2 files changed, 261 insertions(+) create mode 100644 doc/GettingStarted.rst diff --git a/doc/GettingStarted.rst b/doc/GettingStarted.rst new file mode 100644 index 000000000..b6a03e710 --- /dev/null +++ b/doc/GettingStarted.rst @@ -0,0 +1,260 @@ +.. _GettingStarted: + +Getting Started +############### + +*pyVHDLModel* is a VHDL language model without any parser. There are currently two parsers available that can serve as a +frontend to pyVHDLModel. These parsers can generate a VHDL language model instance from VHDL source files: + +* pyVHDLParser (currently broken) +* GHDL + + +pyVHDLParser +************ + +The pyVHDLParser is a token-stream based parser creating a code document object model (CodeDOM) derived from +pyVHDLModel. Actually, pyVHDlModel was originally part of that parser, until it got refactored into this standalone +package so multiple frontends (parsers) and backends (analysis tools) can use this VHDL language model as a common API. + +.. warning:: Currently, pyVHDLParser is not aligned with latest updates in pyVHDLModel. + + +GHDL as Parser +************** + +The free and open-source VHDL-2008 simulator **GHDL** offers a Python binding, so Python code can access ``libghdl``. +This binding layer is exposed in the ``pyGHDL.libghdl`` package. In addition, GHDL offers a ``pyGHDL.dom`` package +implementing derived classes of pyVHDLModel. Each derived class adds translation methods (``.parse(iirNode)``) from +GHDL's internal data structure IIR to the code document object model (CodeDOM) of pyVHDLModel. + + +Installation and Setup +====================== + +To use pyVHDLModel a tool offering a parser like GHDL is required. GHDL itself offers multiple options for installation. +In addition it has multiple backends. For the usage with pyVHDLModel, an ``mcode`` backend is preferred, as it's faster +and doesn't write ``*.o`` files to the disk. As most Python installation are nowadays 64-bit, an ``mcode 64-bit`` +variant of GHDL would be best. + +On Windows - Native +""""""""""""""""""" + +Assuming a 64-bit Windows installation and a 64-bit CPython (`python.org `__) +installation, it's suggested to install: + +* `GHDL 3.0.0-dev - MinGW64 - mcode - standalone `__ +* `GHDL 3.0.0-dev - UCRT64 - mcode - standalone `__ + +As development of Python packages ``pyGHDL.dom`` and ``pyVHDLModel`` are under quick development cycles, a GHDL +``nightly`` build is suggested compared to the stable releases (once a year). These nightly builds are provided as ZIP +files on GitHub: https://github.com/ghdl/ghdl/releases/tag/nightly (or use links from above). + +At next, unpack the ZIP files content to e.g. :file:`C:\\Tools\\GHDL\\3.0.0-dev` (GHDL installation directory). This ZIP +file brings the GHDL synthesis and simulation tool as well as :file:`libghdl-3_0_0_dev.dll` needed as a parser frontend. + + +On Windows - MSYS2 +"""""""""""""""""" + +Assuming a 64-bit Windows installation and an `MSYS2 `__ installation in :file:`C:\msys64`. + + +.. rubric:: MSYS2 Prepartions and GHDL/libghdl Installation + +Start either the MinGW64 or UCRT64 environment and then use :command:`pacman` to install GHDL. The following steps are +explained for UCRT64, but can be applied to MinGW64 similarly. + +.. admonition:: Bash + + .. code-block:: bash + + # Update MSYS2 to latest package releases + pacman -Suyy + + # If the core system was updated, a second run might be required. + pacman -Suyy + + # Search for available GHDL packages + pacman -Ss ghdl + # mingw32/mingw-w64-i686-ghdl-mcode 2.0.0.r870.g1cc85c578-1 (mingw-w64-i686-eda) [Installiert] + # GHDL: the open-source analyzer, compiler, simulator and (experimental) synthesizer for VHDL (mcode backend) (mingw-w64) + # mingw64/mingw-w64-x86_64-ghdl-llvm 2.0.0.r870.g1cc85c578-1 (mingw-w64-x86_64-eda) [Installiert] + # GHDL: the open-source analyzer, compiler, simulator and (experimental) synthesizer for VHDL (LLVM backend) (mingw-w64) + # ucrt64/mingw-w64-ucrt-x86_64-ghdl-llvm 2.0.0.r870.g1cc85c578-1 (mingw-w64-ucrt-x86_64-eda) [Installiert] + # GHDL: the open-source analyzer, compiler, simulator and (experimental) synthesizer for VHDL (LLVM backend) (mingw-w64) + + # Note: The GHDL version is 870 commits after 2.0.0 release and has Git hash "1cc85c578" (without prefix 'g') + + # Install GHDL for UCRT64 + pacman -S ucrt64/mingw-w64-ucrt-x86_64-ghdl-llvm + +.. rubric:: Installing pyGHDL + +At next, pyGHDL matching the currently installed GHDL version must be installed. At best, pyGHDL matches the exact Git +hash of GHDL, so there is no discrepancy between the libghdl binary and the DLL binding layer in ``pyGHDL.libghdl``. + +Assuming *Git for Windows* is installed and available in PowerShell, the following command will install pyGHDL via PIP: + +.. admonition:: PowerShell + + .. code-block:: powershell + + # Install pyGHDL + pip install git+https://github.com/ghdl/ghdl.git@$(ghdl version hash). + + +On Windows from Sources +""""""""""""""""""""""" + +Assuming a 64-bit Windows installation, a 64-bit CPython (`python.org `__) +installation as well as an `MSYS2 `__ installation in :file:`C:\msys64`. + +.. rubric:: MSYS2 Prepartions + +Start either the MinGW64 or UCRT64 environment and then use :command:`pacman` to install build dependencies. The +following steps are explained for UCRT64, but can be applied to MinGW64 similarly. + +.. admonition:: Bash + + .. code-block:: bash + + # Update MSYS2 to latest package releases + pacman -Suyy + + # If the core system was updated, a second run might be required. + pacman -Suyy + + # Install system dependencies + pacman -S git + pacman -S make + + # Install GHDL build dependencies (GCC with Ada support) + pacman -S ucrt64/mingw-w64-ucrt-x86_64-gcc-ada + +.. rubric:: Building GHDL and libghdl + +The next steps will clone GHDL from GitHub, configure the software, build the binaries, run the testsuite and install +all needed result files into the installation directory. + +.. admonition:: Bash + + .. code-block:: bash + + # Clone GHDL repository + mkdir -p /c/Tools/GHDL + cd /c/Tools/GHDL + git clone https://github.com/ghdl/ghdl.git sources + + # Create build directory and configure GHDL + mkdir -p source/build + cd sources/build + ../configure PREFIX=/c/Tools/GHDL/3.0.0-dev + + # Build GHDL, run testsuite and install to PREFIX + make + make install + +The directory structure will look like this: + +.. code-block:: + + ├── Tools + │ ├── GHDL + │ │ ├── 3.0.0-dev + │ │ │ ├── bin + │ │ │ ├── include + │ │ │ ├── lib + │ │ │ │ ├── ghdl + │ │ ├── sources + │ │ │ ├── ... + │ │ │ ├── pyGHDL + │ │ │ ├── src + │ │ │ ├── ... + +In the next steps, some files from MSYS2/UCRT64 need to be copied into the installation directory, so +:file:`libghdl-3_0_0_dev.dll` can be used independently from MSYS2 environments. + +.. rubric:: Installing pyGHDL + +As a final setup step, pyGHDL needs to be installed via PIP by executing some commands in PowerShell. The dependencies +of pyGHDL will take care of installing all necessary requirements like pyVHDLModel. + +.. admonition:: PowerShell + + .. code-block:: powershell + + cd C:\Tools\GHDL\sources + pip install . + + +.. rubric:: Updating GHDL and libghdl + +If GHDL gets updated through new commits, start the UCRT64 console and execute these instructions to build a latest +:file:`libghdl-3_0_0_dev.dll`: + +.. admonition:: Bash + + .. code-block:: bash + + # Update Git reository + cd /c/Tools/GHDL/sources/build + git pull + + # Recompile GHDL + make + + # Overwrite file in installation directory + make install + +.. rubric:: Updating pyGHDL + +TBD + +On Linux +"""""""" + +.. todo:: Write how to get started on Linux with libghdl. + + +On Mac +"""""" + +.. todo:: Write how to get started on Mac with libghdl. + + +Using libghdl with Python +========================= + +An environment variable :envvar:`GHDL_PREFIX=C:\\Tools\\GHDL\\3.0.0-dev\\lib\\ghdl` is needed for libghdl. The path is +constructed from installation path plus ``lib\\ghdl``. + +.. admonition:: GettingStarted.py + + .. code-block:: Python + + from pathlib import Path + from pyGHDL.dom.NonStandard import Design, Document + + fileList = ( + ("libStopWatch", Path("Counter.vhdl")), # a list of 2-element tuples; library name and pat to the VHDL file + ... # just for this example to simply loop all files + ) + + design = Design() + design.LoadDefaultLibraries() # loads std.* and ieee.* (dummies for now to calculate dependencies) + for libName, file in fileList: + library = design.GetLibrary(libName) + document = Document(file) + design.AddDocument(document, library) + + # Analyzing dependencies and computing graphs + design.Analyze() + + # Accessing the TopLevel + design.TopLevel + + # Accessing graphs + design.DependencyGraph + design.HierarchyGraph + design.CompileOrderGraph diff --git a/doc/index.rst b/doc/index.rst index 05f359b1c..c6364fb39 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -211,6 +211,7 @@ License :caption: Introduction :hidden: + GettingStarted Installation Dependency From f410117d86e67ef218517cf23fe7626296df76e2 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Thu, 12 Jan 2023 14:13:05 +0100 Subject: [PATCH 3/9] Limit Sphinx version. --- doc/requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/requirements.txt b/doc/requirements.txt index ae21bbd42..38f285069 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -3,7 +3,7 @@ pyTooling>=2.11.0 # Enforce latest version on ReadTheDocs -sphinx>=5.3.0 +sphinx>=5.3.0, <6.0 # Sphinx Extenstions #sphinx.ext.coverage From 9724776281662966f2dffd1f0b3154c3d4feaf6f Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Fri, 13 Jan 2023 15:03:46 +0100 Subject: [PATCH 4/9] Add a "toplevel" attribute to the hierarchy graph. --- pyVHDLModel/__init__.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/pyVHDLModel/__init__.py b/pyVHDLModel/__init__.py index 4a98b67ef..db127134e 100644 --- a/pyVHDLModel/__init__.py +++ b/pyVHDLModel/__init__.py @@ -423,8 +423,10 @@ def TopLevel(self) -> 'Entity': roots = tuple(self._hierarchyGraph.IterateRoots()) if len(roots) == 1: - self._toplevel = roots[0] - return roots[0] + toplevel = roots[0] + self._hierarchyGraph["toplevel"] = toplevel + self._toplevel = toplevel.Value + return toplevel.Value else: raise VHDLModelException(f"Found more than one toplevel: {', '.join(roots)}") From 57efed870ddf16ba2704ae7e39a93e23a7a1e7a6 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Fri, 13 Jan 2023 15:04:40 +0100 Subject: [PATCH 5/9] Fixed missing reference to the hierarchy vertex on entities and architectures. --- pyVHDLModel/__init__.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/pyVHDLModel/__init__.py b/pyVHDLModel/__init__.py index db127134e..29fc009c5 100644 --- a/pyVHDLModel/__init__.py +++ b/pyVHDLModel/__init__.py @@ -974,7 +974,8 @@ def CreateHierarchyGraph(self) -> None: # Copy all entity and architecture vertices from dependency graph to hierarchy graph and double-link them entityArchitectureFilter = lambda v: v["kind"] in DependencyGraphVertexKind.Entity | DependencyGraphVertexKind.Architecture for vertex in self._dependencyGraph.IterateVertices(predicate=entityArchitectureFilter): - newVertex = vertex.Copy(self._hierarchyGraph, linkingKeyToOriginalVertex="dependencyVertex", linkingKeyFromOriginalVertex="hierarchyVertex") + hierarchyVertex = vertex.Copy(self._hierarchyGraph, linkingKeyToOriginalVertex="dependencyVertex", linkingKeyFromOriginalVertex="hierarchyVertex") + vertex.Value._hierarchyVertex = hierarchyVertex # Copy implementation edges from for hierarchyArchitectureVertex in self._hierarchyGraph.IterateVertices(predicate=lambda v: v["kind"] is DependencyGraphVertexKind.Architecture): From 4961cb3648e23321441452392955dae1d8269933 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Fri, 13 Jan 2023 15:05:11 +0100 Subject: [PATCH 6/9] Avoid parallel edges in hierarchy graph (for now), so hierarchy can be converted to a tree. --- pyVHDLModel/__init__.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/pyVHDLModel/__init__.py b/pyVHDLModel/__init__.py index 29fc009c5..ea0e50ec7 100644 --- a/pyVHDLModel/__init__.py +++ b/pyVHDLModel/__init__.py @@ -986,6 +986,11 @@ def CreateHierarchyGraph(self) -> None: newEdge = hierarchyArchitectureVertex.LinkFromVertex(hierarchyDestinationVertex) elif DependencyGraphEdgeKind.Instantiation in kind: hierarchyDestinationVertex = dependencyEdge.Destination["hierarchyVertex"] + + # FIXME: avoid parallel edges, to graph can be converted to a tree until "real" hierarchy is computed (unrole generics and blocks) + if hierarchyArchitectureVertex.HasLinkToDestination(hierarchyDestinationVertex): + continue + newEdge = hierarchyArchitectureVertex.LinkToVertex(hierarchyDestinationVertex) else: continue From def0744080aca667f809d63eed72dcbe57e49863 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Sun, 5 Feb 2023 17:55:28 +0100 Subject: [PATCH 7/9] Bumped dependencies. --- doc/Dependency.rst | 6 +++--- doc/GettingStarted.rst | 7 ++++--- tests/requirements.txt | 2 +- 3 files changed, 8 insertions(+), 7 deletions(-) diff --git a/doc/Dependency.rst b/doc/Dependency.rst index 6b1e0824a..42f3a5698 100644 --- a/doc/Dependency.rst +++ b/doc/Dependency.rst @@ -23,7 +23,7 @@ pyVHDLModel Package +--------------------------------------------------------+-------------+------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+ | **Package** | **Version** | **License** | **Dependencies** | +========================================================+=============+==========================================================================================+=================================================================================================================================+ -| `pyTooling `__ | ≥2.11.0 | `Apache License, 2.0 `__ | | +| `pyTooling `__ | ≥2.11.0 | `Apache License, 2.0 `__ | *None* | +--------------------------------------------------------+-------------+------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+ @@ -55,7 +55,7 @@ the mandatory dependencies too. +-----------------------------------------------------------+-------------+----------------------------------------------------------------------------------------+----------------------+ | `pytest-cov `__ | ≥4.0.0 | `MIT `__ | *Not yet evaluated.* | +-----------------------------------------------------------+-------------+----------------------------------------------------------------------------------------+----------------------+ -| `Coverage `__ | ≥7.0 | `Apache License, 2.0 `__ | *Not yet evaluated.* | +| `Coverage `__ | ≥7.1 | `Apache License, 2.0 `__ | *Not yet evaluated.* | +-----------------------------------------------------------+-------------+----------------------------------------------------------------------------------------+----------------------+ | `mypy `__ | ≥0.990 | `MIT `__ | *Not yet evaluated.* | +-----------------------------------------------------------+-------------+----------------------------------------------------------------------------------------+----------------------+ @@ -123,7 +123,7 @@ install the mandatory dependencies too. +----------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Package** | **Version** | **License** | **Dependencies** | +============================================================================+==============+==========================================================================================================+======================================================================================================================================================+ -| `pyTooling `__ | ≥2.11.0 | `Apache License, 2.0 `__ | *None* | +| `pyTooling `__ | ≥2.11.0 | `Apache License, 2.0 `__ | *None* | +----------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ | `wheel `__ | ≥0.38.1 | `MIT `__ | *Not yet evaluated.* | +----------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ diff --git a/doc/GettingStarted.rst b/doc/GettingStarted.rst index b6a03e710..ab14c1ade 100644 --- a/doc/GettingStarted.rst +++ b/doc/GettingStarted.rst @@ -128,6 +128,7 @@ following steps are explained for UCRT64, but can be applied to MinGW64 similarl # Install system dependencies pacman -S git pacman -S make + pacman -S diffutils # Install GHDL build dependencies (GCC with Ada support) pacman -S ucrt64/mingw-w64-ucrt-x86_64-gcc-ada @@ -147,11 +148,11 @@ all needed result files into the installation directory. git clone https://github.com/ghdl/ghdl.git sources # Create build directory and configure GHDL - mkdir -p source/build + mkdir -p sources/build cd sources/build - ../configure PREFIX=/c/Tools/GHDL/3.0.0-dev + ../configure --prefix=/c/Tools/GHDL/3.0.0-dev - # Build GHDL, run testsuite and install to PREFIX + # Build GHDL, run testsuite and install to ``prefix`` make make install diff --git a/tests/requirements.txt b/tests/requirements.txt index 7719481f9..3b3b79a5a 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -1,7 +1,7 @@ -r ../requirements.txt # Coverage collection -Coverage>=7.0 +Coverage>=7.1 # Test Runner pytest>=7.2.0 From cb6bb59ec76294c31f5c850021c5bb8d5f1314fc Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Sun, 5 Feb 2023 17:56:15 +0100 Subject: [PATCH 8/9] Added design name. --- pyVHDLModel/__init__.py | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/pyVHDLModel/__init__.py b/pyVHDLModel/__init__.py index ea0e50ec7..3b7909683 100644 --- a/pyVHDLModel/__init__.py +++ b/pyVHDLModel/__init__.py @@ -54,7 +54,7 @@ from enum import unique, Enum, Flag, auto from pathlib import Path -from typing import Union, Dict, cast, List, Generator +from typing import Union, Dict, cast, List, Generator, Optional as Nullable from pyTooling.Decorators import export from pyTooling.Graph import Graph, Vertex, Edge @@ -371,17 +371,23 @@ class Design(ModelEntity): A ``Design`` represents all loaded and analysed files (see :class:`~pyVHDLModel.Document`). It's the root of this document-object-model (DOM). It contains at least one VHDL library (see :class:`~pyVHDLModel.Library`). """ - _libraries: Dict[str, 'Library'] #: List of all libraries defined for a design. - _documents: List['Document'] #: List of all documents loaded for a design. - - _compileOrderGraph: Graph[None, None, None, None, None, 'Document', None, None, None, None, None, None, None] - _dependencyGraph: Graph[None, None, None, None, str, DesignUnit, None, None, None, None, None, None, None] - _hierarchyGraph: Graph[None, None, None, None, str, DesignUnit, None, None, None, None, None, None, None] - _toplevel: Union[Entity, Configuration] + name: Nullable[str] #: Name of the design + _libraries: Dict[str, 'Library'] #: List of all libraries defined for a design. + _documents: List['Document'] #: List of all documents loaded for a design. + _dependencyGraph: Graph[None, None, None, None, str, DesignUnit, None, None, None, None, None, None, None] #: The graph of all dependencies in the designs. + _compileOrderGraph: Graph[None, None, None, None, None, 'Document', None, None, None, None, None, None, None] #: A graph derived from dependency graph containing the order of documents for compilation. + _hierarchyGraph: Graph[None, None, None, None, str, DesignUnit, None, None, None, None, None, None, None] #: A graph derived from dependency graph containing the design hierarchy. + _toplevel: Union[Entity, Configuration] #: When computed, the toplevel design unit is cached in this field. + + def __init__(self, name: str = None): + """ + Initializes a VHDL design. - def __init__(self): + :param name: Name of the design. + """ super().__init__() + self.name = name self._libraries = {} self._documents = [] From cb46f1ea43fb839859b266787ae73ea1e8fbb75d Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Sun, 5 Feb 2023 23:13:49 +0100 Subject: [PATCH 9/9] More documentation. --- doc/Analyze/index.rst | 42 +++++++++++++++++++++++++ doc/DataStructure/CompileOrderGraph.rst | 4 +++ doc/DataStructure/DependencyGraph.rst | 4 +++ doc/DataStructure/HierarchyGraph.rst | 4 +++ doc/DataStructure/index.rst | 8 +++++ doc/conf.py | 2 +- 6 files changed, 63 insertions(+), 1 deletion(-) diff --git a/doc/Analyze/index.rst b/doc/Analyze/index.rst index 961b2b42b..1ee2a845f 100644 --- a/doc/Analyze/index.rst +++ b/doc/Analyze/index.rst @@ -59,3 +59,45 @@ there is a double reference from graph's vertex via ``Value`` to the DOM object 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 index e69de29bb..01e29142e 100644 --- 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 index e69de29bb..b974ff0c9 100644 --- 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 index e69de29bb..0d8a7d1f8 100644 --- 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 index e7a62f32e..fc5d67b3f 100644 --- a/doc/DataStructure/index.rst +++ b/doc/DataStructure/index.rst @@ -60,3 +60,11 @@ The compile order can be derived from dependency graph by: 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/conf.py b/doc/conf.py index ad6271774..a491b0b5c 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -213,7 +213,7 @@ # "inherited-members": True, # "exclude-members": "__weakref__" #} -#autodoc_class_signature = "separated" +autodoc_class_signature = "separated" autodoc_member_order = "bysource" # alphabetical, groupwise, bysource autodoc_typehints = "both" #autoclass_content = "both"