vunit-yavs 0.10.0__tar.gz

vunit_yavs-0.10.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: vunit-yavs
+Version: 0.10.0
+Summary: The yavs VHDL simulator for VUnit, as a VUnit package
+License-Expression: MPL-2.0
+Project-URL: Source, https://github.com/ru551n/yavs/tree/main/python/vunit-yavs
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: vunit_hdl>=5.0.0.dev16
+
+# vunit-yavs
+
+The yavs simulator for VUnit, as a VUnit package. Add it in the run script before anything else,
+then select yavs with `VUNIT_SIMULATOR=yavs`:
+
+```python
+from vunit import VUnit
+
+vu = VUnit.from_argv()
+vu.add_package("vunit-yavs", allow_setup=True)  # first: it provides the simulator
+vu.add_vhdl_builtins()
+vu.add_library("lib").add_source_files("*.vhd")
+vu.main()
+```
+
+```sh
+pip install vunit-yavs
+VUNIT_SIMULATOR=yavs python run.py
+```
+
+`yavs` is found on `PATH`, or in the directory named by `VUNIT_YAVS_PATH`. It needs VUnit 5.0.0.dev16
+or later (`pip install vunit-yavs` installs it, a pre-release) and yavs 0.10.0 or later.
+
+## Options
+
+| Sim or compile option | Passed to |
+|---|---|
+| `yavs.global_flags` | `yavs analyze`, `run` and `elab` |
+| `yavs.a_flags` | `yavs analyze` |
+| `yavs.elab_flags` | `yavs run` and `elab` |
+| `yavs.sim_flags` | `yavs run` |
+| `yavs.max_threads` (integer, at least 1) | `yavs run --threads=N`, the most threads of one simulation |
+
+| Command line | What it does |
+|---|---|
+| `-g/--gui` | Opens the run in the graphical debugger (`yavs run --gui`) |
+| `--yavs-debug[=PORT]` | Runs the selected test under `yavs run --dap=PORT` (default 4711, `0` picks a free port) and prints where to attach; write the port as `--yavs-debug=PORT` |
+| `--yavs-max-threads N` | `yavs.max_threads` for every test that does not set it |
+| `--yavs-jobserver` | Lends the CPU slots of `-p N` that no test uses to the running simulations (below) |
+
+Without `yavs.max_threads` or `--yavs-max-threads` no thread count is passed, and yavs runs with
+its default. An explicit `--threads` in `yavs.sim_flags` comes after the cap and wins.
+
+## Debugging one test
+
+```sh
+VUNIT_SIMULATOR=yavs python run.py lib.tb.test_name --yavs-debug
+```
+
+yavs waits for a Debug Adapter Protocol client on `127.0.0.1:4711` before the simulation starts;
+attach the editor (the yavs extension's "Attach to yavs" configuration uses that port). When the
+session ends, the test is reported as usual.
+
+`--yavs-debug` runs one simulation. A second simulation of the run (a second test, or the same
+test in another configuration) is an error before yavs starts, naming both tests. `--yavs-debug`
+together with `--gui`, `--elaborate` or `-p` above 1 is an error at the start. A bare
+`--yavs-debug` reads a following test name as its port: put test names first, or write
+`--yavs-debug=4711`.
+
+## Jobserver
+
+With `-p N --yavs-jobserver` (POSIX only; on Windows it is an error) every running test gets a
+private GNU make jobserver, a named pipe in `MAKEFLAGS=-jN --jobserver-auth=fifo:PATH`, and a
+thread of the run script lends tokens into the pipes: one CPU slot per running test is free, the
+other `N - k` slots (for `k` running tests) are lent, breadth first (every test gets one extra
+before any gets a second) and newest test first within a round, capped per test by
+`yavs.max_threads - 1`. Tokens a simulation leaves unread are taken back and lent again every
+50 ms, and a test that leaves tokens unread gets at most one more than it uses. A test that
+starts while every token is in use runs at once, so the total is `N` in the steady state, not at
+every instant. A simulation that exits holding tokens, or a run that ends with tokens out, is
+reported with a warning.
+
+`MAKEFLAGS` from an outer `make -j` is replaced, not passed on: joining an outer jobserver is not
+supported. The pipes live in a temporary directory of their own, since `MAKEFLAGS` cannot hold a
+path with spaces.
+
+## Licence
+
+Mozilla Public License 2.0 (https://mozilla.org/MPL/2.0/), see the header of each file.

vunit_yavs-0.10.0/README.md

@@ -0,0 +1,79 @@
+# vunit-yavs
+
+The yavs simulator for VUnit, as a VUnit package. Add it in the run script before anything else,
+then select yavs with `VUNIT_SIMULATOR=yavs`:
+
+```python
+from vunit import VUnit
+
+vu = VUnit.from_argv()
+vu.add_package("vunit-yavs", allow_setup=True)  # first: it provides the simulator
+vu.add_vhdl_builtins()
+vu.add_library("lib").add_source_files("*.vhd")
+vu.main()
+```
+
+```sh
+pip install vunit-yavs
+VUNIT_SIMULATOR=yavs python run.py
+```
+
+`yavs` is found on `PATH`, or in the directory named by `VUNIT_YAVS_PATH`. It needs VUnit 5.0.0.dev16
+or later (`pip install vunit-yavs` installs it, a pre-release) and yavs 0.10.0 or later.
+
+## Options
+
+| Sim or compile option | Passed to |
+|---|---|
+| `yavs.global_flags` | `yavs analyze`, `run` and `elab` |
+| `yavs.a_flags` | `yavs analyze` |
+| `yavs.elab_flags` | `yavs run` and `elab` |
+| `yavs.sim_flags` | `yavs run` |
+| `yavs.max_threads` (integer, at least 1) | `yavs run --threads=N`, the most threads of one simulation |
+
+| Command line | What it does |
+|---|---|
+| `-g/--gui` | Opens the run in the graphical debugger (`yavs run --gui`) |
+| `--yavs-debug[=PORT]` | Runs the selected test under `yavs run --dap=PORT` (default 4711, `0` picks a free port) and prints where to attach; write the port as `--yavs-debug=PORT` |
+| `--yavs-max-threads N` | `yavs.max_threads` for every test that does not set it |
+| `--yavs-jobserver` | Lends the CPU slots of `-p N` that no test uses to the running simulations (below) |
+
+Without `yavs.max_threads` or `--yavs-max-threads` no thread count is passed, and yavs runs with
+its default. An explicit `--threads` in `yavs.sim_flags` comes after the cap and wins.
+
+## Debugging one test
+
+```sh
+VUNIT_SIMULATOR=yavs python run.py lib.tb.test_name --yavs-debug
+```
+
+yavs waits for a Debug Adapter Protocol client on `127.0.0.1:4711` before the simulation starts;
+attach the editor (the yavs extension's "Attach to yavs" configuration uses that port). When the
+session ends, the test is reported as usual.
+
+`--yavs-debug` runs one simulation. A second simulation of the run (a second test, or the same
+test in another configuration) is an error before yavs starts, naming both tests. `--yavs-debug`
+together with `--gui`, `--elaborate` or `-p` above 1 is an error at the start. A bare
+`--yavs-debug` reads a following test name as its port: put test names first, or write
+`--yavs-debug=4711`.
+
+## Jobserver
+
+With `-p N --yavs-jobserver` (POSIX only; on Windows it is an error) every running test gets a
+private GNU make jobserver, a named pipe in `MAKEFLAGS=-jN --jobserver-auth=fifo:PATH`, and a
+thread of the run script lends tokens into the pipes: one CPU slot per running test is free, the
+other `N - k` slots (for `k` running tests) are lent, breadth first (every test gets one extra
+before any gets a second) and newest test first within a round, capped per test by
+`yavs.max_threads - 1`. Tokens a simulation leaves unread are taken back and lent again every
+50 ms, and a test that leaves tokens unread gets at most one more than it uses. A test that
+starts while every token is in use runs at once, so the total is `N` in the steady state, not at
+every instant. A simulation that exits holding tokens, or a run that ends with tokens out, is
+reported with a warning.
+
+`MAKEFLAGS` from an outer `make -j` is replaced, not passed on: joining an outer jobserver is not
+supported. The pipes live in a temporary directory of their own, since `MAKEFLAGS` cannot hold a
+path with spaces.
+
+## Licence
+
+Mozilla Public License 2.0 (https://mozilla.org/MPL/2.0/), see the header of each file.

vunit_yavs-0.10.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vunit-yavs"
+version = "0.10.0"
+description = "The yavs VHDL simulator for VUnit, as a VUnit package"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MPL-2.0"
+# The first VUnit release with simulator packages (the vunit_pkg.toml key 'simulator')
+dependencies = ["vunit_hdl>=5.0.0.dev16"]
+
+[project.urls]
+Source = "https://github.com/ru551n/yavs/tree/main/python/vunit-yavs"
+
+[tool.setuptools]
+packages = ["vunit_yavs"]
+
+[tool.setuptools.package-data]
+vunit_yavs = ["vunit_pkg.toml"]
+
+[tool.black]
+line-length = 120

vunit_yavs-0.10.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vunit_yavs-0.10.0/tests/test_fake_e2e.py

@@ -0,0 +1,159 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this file,
+# You can obtain one at http://mozilla.org/MPL/2.0/.
+#
+# Copyright (c) 2014-2026, Lars Asplund lars.anders.asplund@gmail.com
+
+"""
+End to end: the project's run.py adds the package and runs against the fake yavs
+"""
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from xml.etree import ElementTree
+
+HERE = Path(__file__).parent
+PASS = "lib.tb_yavs.test_pass"
+COMMA = "lib.tb_yavs.test with, comma: and colon"
+FAIL = "lib.tb_yavs.test_fail"
+
+
+def report(xml_file):
+    """Return {test name: status} of a JUnit report"""
+    result = {}
+    for case in ElementTree.parse(xml_file).iter("testcase"):
+        status = (
+            "failed"
+            if case.find("failure") is not None
+            else "skipped" if case.find("skipped") is not None else "passed"
+        )
+        result[f"{case.get('classname')}.{case.get('name')}"] = status
+    return result
+
+
+@unittest.skipIf(sys.platform == "win32", "The fake yavs is a Python script without an .exe wrapper")
+class TestFakeYavs(unittest.TestCase):
+    """
+    Run a real run.py with VUNIT_SIMULATOR=yavs against the fake yavs
+    """
+
+    def _run(self, *args, fail="", version="0.10.0"):
+        """Run run.py and return the exit code, the output, the JUnit results and the logged yavs calls"""
+        with tempfile.TemporaryDirectory() as tempdir:
+            tempdir = Path(tempdir)
+            log = tempdir / "yavs.log"
+            env = dict(
+                os.environ,
+                VUNIT_SIMULATOR="yavs",
+                VUNIT_YAVS_PATH=str(HERE / "fake_bin"),
+                FAKE_YAVS_LOG=str(log),
+                FAKE_YAVS_FAIL=fail,
+                FAKE_YAVS_VERSION=version,
+            )
+            xml = tempdir / "x.xml"
+            proc = subprocess.run(
+                [sys.executable, str(HERE / "project" / "run.py"), "--clean", "-o", str(tempdir / "out with space")]
+                + ["-x", str(xml)]
+                + list(args),
+                env=env,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                text=True,
+                timeout=120,
+                check=False,
+            )
+            calls = [json.loads(line) for line in log.read_text(encoding="utf-8").splitlines()] if log.exists() else []
+            results = report(xml) if xml.exists() else {}
+        return proc.returncode, proc.stdout, results, calls
+
+    @staticmethod
+    def _runs(calls):
+        return [cmd for cmd in calls if cmd[0] == "run"]
+
+    def test_pass(self):
+        exit_code, _, results, calls = self._run(PASS, COMMA)
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(results, {PASS: "passed", COMMA: "passed"})
+        self.assertTrue(any(cmd[0] == "analyze" and cmd[-1].endswith("tb_yavs.vhd") for cmd in calls))
+        runs = self._runs(calls)
+        self.assertEqual(len(runs), 2)
+        self.assertIn("tb_yavs.tb", runs[0])
+        self.assertIn("--exit-severity=error", runs[0])
+        self.assertFalse(any(arg.startswith(("--threads", "--dap")) for arg in runs[0]))
+        for cmd in calls:
+            if cmd[0] in ("analyze", "elab", "run"):
+                flags = [arg for arg in cmd if arg.startswith("--std-cache=")]
+                self.assertEqual(len(flags), 1, cmd)
+                self.assertRegex(flags[0], r"out with space[/\\]yavs[/\\]std_cache$")
+
+    def test_fail(self):
+        exit_code, _, results, _ = self._run(fail="test_fail")
+        self.assertEqual(exit_code, 1)
+        self.assertEqual(results, {PASS: "passed", COMMA: "passed", FAIL: "failed"})
+
+    def test_elaborate_only(self):
+        exit_code, _, _, calls = self._run("--elaborate", PASS)
+        self.assertEqual(exit_code, 0)
+        self.assertTrue(any(cmd[0] == "elab" for cmd in calls))
+        self.assertFalse(self._runs(calls))
+
+    def test_too_old_yavs_fails_before_compiling(self):
+        exit_code, output, _, calls = self._run(PASS, version="0.8.2")
+        self.assertNotEqual(exit_code, 0)
+        self.assertIn("yavs 0.8.2 at ", output)
+        self.assertIn("which needs yavs 0.10.0 or later", output)
+        self.assertFalse([call for call in calls if call[0] == "analyze"])
+
+    def test_max_threads(self):
+        exit_code, _, _, calls = self._run("--yavs-max-threads=3", PASS)
+        self.assertEqual(exit_code, 0)
+        self.assertIn("--threads=3", self._runs(calls)[0])
+
+    def test_jobserver(self):
+        exit_code, output, results, calls = self._run("-p", "2", "--yavs-jobserver", "--yavs-max-threads=2")
+        self.assertEqual(exit_code, 0, output)
+        self.assertEqual(set(results.values()), {"passed"})
+        uses = [call for call in calls if call[0] == "jobserver"]
+        self.assertEqual(len(uses), 3)
+        for _, flags, _ in uses:
+            self.assertRegex(flags, r"^-j2 --jobserver-auth=fifo:\S+/fifo\d+$")
+        # A test running alone gets the one free slot of -p 2
+        self.assertIn("+", [token for _, _, token in uses])
+        self.assertNotIn("token(s) without returning them", output)
+
+    def test_no_jobserver_without_the_flag(self):
+        _, _, _, calls = self._run("-p", "2", PASS, COMMA)
+        self.assertFalse([call for call in calls if call[0] == "jobserver"])
+
+    def test_debug_one_test(self):
+        exit_code, output, results, calls = self._run("--yavs-debug=5000", "--yavs-max-threads=3", PASS)
+        self.assertEqual(exit_code, 0, output)
+        self.assertEqual(results, {PASS: "passed"})
+        (run,) = self._runs(calls)
+        self.assertEqual(run[1], "--dap=5000")
+        self.assertFalse(any(arg.startswith("--threads") for arg in run))
+        self.assertIn(f"Debugging {PASS}: attach a DAP client to 127.0.0.1:5000", output)
+
+    def test_debug_refuses_the_second_test(self):
+        exit_code, output, results, calls = self._run("--yavs-debug=5000", PASS, COMMA)
+        self.assertEqual(exit_code, 1)
+        self.assertEqual(len(self._runs(calls)), 1)
+        self.assertEqual(sorted(results.values()), ["failed", "passed"])
+        self.assertIn("--yavs-debug runs one simulation", output)
+
+    def test_debug_refuses_parallel_simulations(self):
+        exit_code, output, _, calls = self._run("--yavs-debug", "-p", "2", PASS)
+        self.assertNotEqual(exit_code, 0)
+        self.assertIn("-p 2 asks for parallel simulations", output)
+        self.assertFalse(self._runs(calls))
+
+    def test_debug_refuses_elaborate(self):
+        exit_code, output, _, calls = self._run(PASS, "--elaborate", "--yavs-debug")
+        self.assertNotEqual(exit_code, 0)
+        self.assertIn("--yavs-debug and --elaborate cannot be combined", output)
+        self.assertFalse(any(cmd[0] == "elab" for cmd in calls))