jig-dsl 0.1.0a1__tar.gz

jig_dsl-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Graham Power
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jig_dsl-0.1.0a1/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: jig-dsl
+Version: 0.1.0a1
+Summary: A test language and harness for firmware running on the Renode emulator
+Author: Graham Power
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/GNPower/Jig
+Project-URL: Documentation, https://jig-dsl.readthedocs.io
+Project-URL: Repository, https://github.com/GNPower/Jig
+Project-URL: Issues, https://github.com/GNPower/Jig/issues
+Project-URL: Changelog, https://github.com/GNPower/Jig/blob/main/CHANGELOG.md
+Keywords: renode,emulation,firmware,testing,embedded,zynq,stm32,csp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Emulators
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: textX<5,>=4
+Requires-Dist: PyYAML<7,>=6
+Requires-Dist: platformdirs<5,>=4
+Requires-Dist: packaging>=23
+Provides-Extra: test
+Requires-Dist: pytest<10,>=8; extra == "test"
+Requires-Dist: pytest-cov<8,>=6; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx<10,>=8.2; extra == "docs"
+Requires-Dist: sphinx-rtd-theme<4,>=3.0; extra == "docs"
+Requires-Dist: myst-parser<6,>=4.0; extra == "docs"
+Provides-Extra: lint
+Requires-Dist: ruff==0.17.0; extra == "lint"
+Requires-Dist: pymarkdownlnt==0.9.40; extra == "lint"
+Requires-Dist: zizmor==1.30.1; extra == "lint"
+Provides-Extra: typecheck
+Requires-Dist: jig-dsl[test]; extra == "typecheck"
+Requires-Dist: mypy==2.4.0; extra == "typecheck"
+Requires-Dist: types-PyYAML==6.0.12.20260906; extra == "typecheck"
+Requires-Dist: nox==2026.8.17; extra == "typecheck"
+Provides-Extra: release
+Requires-Dist: build==1.6.1; extra == "release"
+Requires-Dist: twine==7.0.0; extra == "release"
+Requires-Dist: bump-my-version==1.5.1; extra == "release"
+Provides-Extra: audit
+Requires-Dist: pip-audit==2.10.1; extra == "audit"
+Provides-Extra: dev
+Requires-Dist: jig-dsl[lint,release,test,typecheck]; extra == "dev"
+Dynamic: license-file
+
+# Jig
+
+[![PyPI version](https://img.shields.io/pypi/v/jig-dsl.svg)](https://pypi.org/project/jig-dsl/)
+[![Python versions](https://img.shields.io/pypi/pyversions/jig-dsl.svg)](https://pypi.org/project/jig-dsl/)
+[![Tests](https://github.com/GNPower/Jig/actions/workflows/ci.yml/badge.svg)](https://github.com/GNPower/Jig/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/GNPower/Jig/branch/main/graph/badge.svg)](https://codecov.io/gh/GNPower/Jig)
+[![Documentation](https://readthedocs.org/projects/jig-dsl/badge/?version=latest)](https://jig-dsl.readthedocs.io/en/latest/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/GNPower/Jig/blob/main/LICENSE)
+
+**A test language and harness for firmware running on the Renode
+emulator.**
+
+Full documentation: <https://jig-dsl.readthedocs.io>
+
+## Overview
+
+Jig runs test plans, written as `.jig` files, against a users firmware
+on [Renode](https://renode.io). A plan declares the boards it needs, the
+buse interfaces between them and the communication protocols the harness uses, then
+drives the system over those interfaces in simulated time:
+
+```jig
+import "zed.jig"
+
+system "two ZedBoards and a host computer" {
+    board a: "zed-a"
+    board b: "zed-b"
+    bus can0: can(bitrate: 1 Mbit/s, members: [a.can, b.can])
+    node host: csp(address: 10, link: a.kiss)
+}
+
+setup {
+    parallel {
+        task zed_a { booted(a, 1) }
+        task zed_b { booted(b, 2) }
+    }
+}
+
+test "the host computer reaches zed-b through zed-a" {
+    check host.ping(b) < 50 ms
+    check can0.traffic().routes["10->2:1"] >= 1
+}
+```
+
+This is the start of `examples/zedboard/plans/multiboard.jig`. The setup
+waits, on both boards at once, for the boot banner and the first prompt
+(`booted` comes from the example's plan library, `lib/zed.jig`). The test
+then pings zed-b from the host computer through zed-a using the lightweight
+network protocol [LibCSP](https://github.com/libcsp/libcsp).
+
+Every check's result is printed in a report with the simulated time it ran
+at. Each run gets a fingerprint, a SHA-256 digest of everything it decided
+and measured in simulated time, so `jig run --repeat 3` proves a plan gives
+the same result three times, on any host.
+
+Boards are data: a `board.yaml` names the platform (in this case the
+[ZedBoard][zedboard], running a Zynq-7020 SoC), the Renode platform
+description, the firmware and the interfaces plans use. Users must bring
+their own C# models and Python plugins for any peripherals not directly
+supported by Jig.
+
+[zedboard]: https://www.avnet.com/americas/products/avnet-boards/avnet-board-families/zedboard/
+
+## Requirements
+
+- Python 3.11 or later.
+- Renode 1.17.0. Jig finds an installed copy, or `jig renode install`
+  downloads the release from Renode's GitHub page after you agree, and
+  checks its size and SHA-256 digest.
+- For the ZedBoard example's firmware, `arm-none-eabi-gcc`.
+- For RTL co-simulation, Linux with Verilator.
+
+## Installation
+
+```bash
+python -m pip install jig-dsl
+jig renode install
+jig doctor
+```
+
+## Quick Start
+
+The repository's ZedBoard example runs two Zynq-7020 boards on one CAN
+bus, with a host computer on a serial link to the first:
+
+```bash
+git clone https://github.com/GNPower/Jig.git
+cd Jig
+python examples/zedboard/firmware/build.py
+jig run examples/zedboard/plans/multiboard.jig --html out/report.html
+```
+
+`build.py` needs `arm-none-eabi-gcc` on the `PATH`. The tutorials in the
+documentation build plans like this one step by step.
+
+## Features
+
+- **A plan language for firmware tests**: consoles, network requests, checks,
+  waits, loops, parallel tasks, timelines and recorded values, all in
+  simulated time.
+- **Several boards in one emulation**, on bus interfaces the harness carries
+  and watches, with repeatable timing between them.
+- **Zynq-7000 and STM32 drivers**: JTAG-style and Quad-SPI boots through
+  Jig's Zynq-7000 models, and ELF boots on Renode's STM32 platforms.
+- **CSP in libcsp 1.6's wire format**: KISS and CAN links, RDP
+  connections, and a bus observer that reassembles every packet.
+- **Board plugins** through `jig.plugin`, a versioned API for plan
+  functions, board members, decoders and device drivers.
+- **C# models compiled by Renode at start-up**, with interfaces that board
+  chip models implement so plans can drive them.
+- **Reports for people and CI**: an HTML page with plots, JUnit XML, a JSON
+  summary, run directories with every console transcript and packet, and
+  exit codes that differentiate failed tests from broken setups.
+- **RTL co-simulation** of programmable-logic blocks with Verilator.
+- **A localhost bridge to Renode** with a token per run, in place of
+  Renode's network-facing Robot Framework server.
+
+## License
+
+MIT: see [LICENSE](https://github.com/GNPower/Jig/blob/main/LICENSE).

jig_dsl-0.1.0a1/README.md

@@ -0,0 +1,120 @@
+# Jig
+
+[![PyPI version](https://img.shields.io/pypi/v/jig-dsl.svg)](https://pypi.org/project/jig-dsl/)
+[![Python versions](https://img.shields.io/pypi/pyversions/jig-dsl.svg)](https://pypi.org/project/jig-dsl/)
+[![Tests](https://github.com/GNPower/Jig/actions/workflows/ci.yml/badge.svg)](https://github.com/GNPower/Jig/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/GNPower/Jig/branch/main/graph/badge.svg)](https://codecov.io/gh/GNPower/Jig)
+[![Documentation](https://readthedocs.org/projects/jig-dsl/badge/?version=latest)](https://jig-dsl.readthedocs.io/en/latest/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/GNPower/Jig/blob/main/LICENSE)
+
+**A test language and harness for firmware running on the Renode
+emulator.**
+
+Full documentation: <https://jig-dsl.readthedocs.io>
+
+## Overview
+
+Jig runs test plans, written as `.jig` files, against a users firmware
+on [Renode](https://renode.io). A plan declares the boards it needs, the
+buse interfaces between them and the communication protocols the harness uses, then
+drives the system over those interfaces in simulated time:
+
+```jig
+import "zed.jig"
+
+system "two ZedBoards and a host computer" {
+    board a: "zed-a"
+    board b: "zed-b"
+    bus can0: can(bitrate: 1 Mbit/s, members: [a.can, b.can])
+    node host: csp(address: 10, link: a.kiss)
+}
+
+setup {
+    parallel {
+        task zed_a { booted(a, 1) }
+        task zed_b { booted(b, 2) }
+    }
+}
+
+test "the host computer reaches zed-b through zed-a" {
+    check host.ping(b) < 50 ms
+    check can0.traffic().routes["10->2:1"] >= 1
+}
+```
+
+This is the start of `examples/zedboard/plans/multiboard.jig`. The setup
+waits, on both boards at once, for the boot banner and the first prompt
+(`booted` comes from the example's plan library, `lib/zed.jig`). The test
+then pings zed-b from the host computer through zed-a using the lightweight
+network protocol [LibCSP](https://github.com/libcsp/libcsp).
+
+Every check's result is printed in a report with the simulated time it ran
+at. Each run gets a fingerprint, a SHA-256 digest of everything it decided
+and measured in simulated time, so `jig run --repeat 3` proves a plan gives
+the same result three times, on any host.
+
+Boards are data: a `board.yaml` names the platform (in this case the
+[ZedBoard][zedboard], running a Zynq-7020 SoC), the Renode platform
+description, the firmware and the interfaces plans use. Users must bring
+their own C# models and Python plugins for any peripherals not directly
+supported by Jig.
+
+[zedboard]: https://www.avnet.com/americas/products/avnet-boards/avnet-board-families/zedboard/
+
+## Requirements
+
+- Python 3.11 or later.
+- Renode 1.17.0. Jig finds an installed copy, or `jig renode install`
+  downloads the release from Renode's GitHub page after you agree, and
+  checks its size and SHA-256 digest.
+- For the ZedBoard example's firmware, `arm-none-eabi-gcc`.
+- For RTL co-simulation, Linux with Verilator.
+
+## Installation
+
+```bash
+python -m pip install jig-dsl
+jig renode install
+jig doctor
+```
+
+## Quick Start
+
+The repository's ZedBoard example runs two Zynq-7020 boards on one CAN
+bus, with a host computer on a serial link to the first:
+
+```bash
+git clone https://github.com/GNPower/Jig.git
+cd Jig
+python examples/zedboard/firmware/build.py
+jig run examples/zedboard/plans/multiboard.jig --html out/report.html
+```
+
+`build.py` needs `arm-none-eabi-gcc` on the `PATH`. The tutorials in the
+documentation build plans like this one step by step.
+
+## Features
+
+- **A plan language for firmware tests**: consoles, network requests, checks,
+  waits, loops, parallel tasks, timelines and recorded values, all in
+  simulated time.
+- **Several boards in one emulation**, on bus interfaces the harness carries
+  and watches, with repeatable timing between them.
+- **Zynq-7000 and STM32 drivers**: JTAG-style and Quad-SPI boots through
+  Jig's Zynq-7000 models, and ELF boots on Renode's STM32 platforms.
+- **CSP in libcsp 1.6's wire format**: KISS and CAN links, RDP
+  connections, and a bus observer that reassembles every packet.
+- **Board plugins** through `jig.plugin`, a versioned API for plan
+  functions, board members, decoders and device drivers.
+- **C# models compiled by Renode at start-up**, with interfaces that board
+  chip models implement so plans can drive them.
+- **Reports for people and CI**: an HTML page with plots, JUnit XML, a JSON
+  summary, run directories with every console transcript and packet, and
+  exit codes that differentiate failed tests from broken setups.
+- **RTL co-simulation** of programmable-logic blocks with Verilator.
+- **A localhost bridge to Renode** with a token per run, in place of
+  Renode's network-facing Robot Framework server.
+
+## License
+
+MIT: see [LICENSE](https://github.com/GNPower/Jig/blob/main/LICENSE).

jig_dsl-0.1.0a1/pyproject.toml

@@ -0,0 +1,192 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "jig-dsl"
+version = "0.1.0a1"
+description = "A test language and harness for firmware running on the Renode emulator"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Graham Power" }]
+keywords = ["renode", "emulation", "firmware", "testing", "embedded", "zynq", "stm32", "csp"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Embedded Systems",
+    "Topic :: Software Development :: Testing",
+    "Topic :: System :: Emulators",
+    "Typing :: Typed",
+]
+dependencies = [
+    "textX>=4,<5",
+    "PyYAML>=6,<7",
+    "platformdirs>=4,<5",
+    "packaging>=23",
+]
+
+[project.urls]
+Homepage = "https://github.com/GNPower/Jig"
+Documentation = "https://jig-dsl.readthedocs.io"
+Repository = "https://github.com/GNPower/Jig"
+Issues = "https://github.com/GNPower/Jig/issues"
+Changelog = "https://github.com/GNPower/Jig/blob/main/CHANGELOG.md"
+
+# The tool sets noxfile.py installs per session, CI and `dev` use the same pins.
+[project.optional-dependencies]
+test = [
+    "pytest>=8,<10",
+    "pytest-cov>=6,<8",
+]
+docs = [
+    "sphinx>=8.2,<10",
+    "sphinx-rtd-theme>=3.0,<4",
+    "myst-parser>=4.0,<6",
+]
+lint = [
+    "ruff==0.17.0",
+    "pymarkdownlnt==0.9.40",
+    "zizmor==1.30.1",
+]
+typecheck = [
+    "jig-dsl[test]",
+    "mypy==2.4.0",
+    "types-PyYAML==6.0.12.20260906",
+    "nox==2026.8.17",
+]
+release = [
+    "build==1.6.1",
+    "twine==7.0.0",
+    "bump-my-version==1.5.1",
+]
+audit = [
+    "pip-audit==2.10.1",
+]
+dev = [
+    "jig-dsl[test,lint,typecheck,release]",
+]
+
+[project.scripts]
+jig = "jig.cli:main"
+
+# SoC families: a board's `soc:` names one (board.yaml `soc_driver:` overrides).
+[project.entry-points."jig.socs"]
+zynq7000 = "jig.ext.zynq7000.driver:Zynq7000Driver"
+stm32 = "jig.system.socs.stm32:Stm32Driver"
+
+# Highlighting for .jig plans in Sphinx, Pygments and any tool built on them.
+[project.entry-points."pygments.lexers"]
+jig = "jig.lang.pygments_lexer:JigLexer"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+jig = [
+    "py.typed",
+    "lang/grammar/*.tx",
+    "lang/stdlib/*.jig",
+    "models/**/*.cs",
+    "platforms/**/*.repl",
+    "ext/cosim/templates/*",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+# Markdown keeps to 80 columns (PyMarkdown, .markdownlint.json). The Python in
+# its code blocks is wrapped by hand, so ruff leaves .md files alone.
+extend-exclude = ["*.md"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF", "PTH", "N"]
+
+[tool.ruff.lint.per-file-ignores]
+# Statement and expression handlers are named after the grammar's rules (_s_If, _e_Sum).
+"src/jig/lang/interpreter.py" = ["N802"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unreachable = true
+mypy_path = "src"
+packages = ["jig"]
+
+[[tool.mypy.overrides]]
+module = ["textx.*", "pygments.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+# The example's plugin tests need no Renode, so they run with the unit tests.
+testpaths = ["tests", "examples/zedboard/tests"]
+# The Renode tier starts Renode; run it with -m renode (JIG_RENODE set).
+addopts = "-m 'not renode and not firmware and not slow' --strict-markers"
+markers = [
+    "renode: needs Renode (JIG_RENODE or a managed install)",
+    "firmware: needs built firmware artifacts",
+    "slow: takes more than a few seconds",
+]
+
+[tool.coverage.run]
+source_pkgs = ["jig"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+exclude_also = [
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+]
+
+# PyMarkdown (`nox -s lint`) with the rules of .markdownlint.json: every rule
+# on, and a heading may repeat one outside its own section.
+[tool.pymarkdown]
+plugins.md024.siblings_only = true
+
+# One static version, here: jig.__version__ and the docs read it from the
+# installed metadata. bump-my-version neither commits nor tags. The release
+# commit and the tag vX.Y.Z are signed by hand. PEP 440 forms:
+# 0.1.0.dev0 -> (pre_l) 0.1.0a1 -> (pre_n) 0.1.0a2 -> (pre_l) 0.1.0b1 ->
+# 0.1.0rc1 -> 0.1.0 -> (patch) 0.1.1.dev1.
+[tool.bumpversion]
+current_version = "0.1.0a1"
+parse = """(?x)
+    (?P<major>0|[1-9]\\d*)\\.
+    (?P<minor>0|[1-9]\\d*)\\.
+    (?P<patch>0|[1-9]\\d*)
+    (?:(?P<pre_l>\\.dev|a|b|rc)(?P<pre_n>0|[1-9]\\d*))?
+"""
+serialize = [
+    "{major}.{minor}.{patch}{pre_l}{pre_n}",
+    "{major}.{minor}.{patch}",
+]
+commit = false
+tag = false
+allow_dirty = true
+
+[tool.bumpversion.parts.pre_l]
+values = [".dev", "a", "b", "rc", "final"]
+optional_value = "final"
+
+[tool.bumpversion.parts.pre_n]
+first_value = "1"
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+regex = true
+search = '^version = "{current_version}"'
+replace = 'version = "{new_version}"'

jig_dsl-0.1.0a1/setup.cfg

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

jig_dsl-0.1.0a1/src/jig/__init__.py

@@ -0,0 +1,13 @@
+"""Jig: a test language and harness for firmware running on Renode.
+
+The package is board-agnostic. Boards are described by data (``board.yaml``),
+peripheral models are C# sources Renode loads, and test plans are ``.jig``
+scripts.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("jig-dsl")
+except PackageNotFoundError:  # a source tree that was never installed
+    __version__ = "0+unknown"

jig_dsl-0.1.0a1/src/jig/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m jig``."""
+
+import sys
+
+from jig.cli import main
+
+sys.exit(main())

jig_dsl-0.1.0a1/src/jig/artifacts.py

@@ -0,0 +1,77 @@
+"""Content-addressed cache for generated artifacts.
+
+Register maps, register programs and flash images are derived from files in
+the repository (RTL, XSA, ELFs). Each artifact lives in
+``<cache>/artifacts/<kind>-<digest>/``, where the digest covers the contents of every
+input file and the build parameters, so a changed input produces a new entry
+and an unchanged one is reused. Entries are built in a temporary directory and
+renamed into place, so an interrupted build never leaves a half-written entry.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import shutil
+import tempfile
+from collections.abc import Callable, Iterable
+from pathlib import Path
+from typing import Any
+
+from jig import project
+from jig.errors import ConfigError
+
+log = logging.getLogger(__name__)
+
+_COMPLETE = ".complete"
+
+
+def cache_root() -> Path:
+    return project.artifacts_dir()
+
+
+def digest(inputs: Iterable[Path], params: dict[str, Any] | None = None) -> str:
+    hasher = hashlib.sha256()
+    for path in inputs:
+        if not path.is_file():
+            raise ConfigError(f"artifact input {path} does not exist")
+        hasher.update(path.name.encode())
+        with path.open("rb") as handle:
+            for block in iter(lambda: handle.read(1 << 20), b""):
+                hasher.update(block)
+    hasher.update(json.dumps(params or {}, sort_keys=True, default=str).encode())
+    return hasher.hexdigest()[:16]
+
+
+def cached(
+    kind: str,
+    inputs: Iterable[Path],
+    build: Callable[[Path], None],
+    params: dict[str, Any] | None = None,
+) -> Path:
+    """Directory holding the artifact; ``build(directory)`` fills a new one."""
+    input_list = list(inputs)
+    entry = cache_root() / f"{kind}-{digest(input_list, params)}"
+    if (entry / _COMPLETE).exists():
+        return entry
+    entry.parent.mkdir(parents=True, exist_ok=True)
+    staging = Path(tempfile.mkdtemp(prefix=f"{kind}-", dir=entry.parent))
+    try:
+        log.info("building %s", entry.name)
+        build(staging)
+        (staging / _COMPLETE).write_text(
+            json.dumps(
+                {"inputs": [str(p) for p in input_list], "params": params or {}},
+                default=str,
+                indent=2,
+            ),
+            encoding="utf-8",
+        )
+        if entry.exists():
+            shutil.rmtree(entry)
+        staging.rename(entry)
+    except BaseException:
+        shutil.rmtree(staging, ignore_errors=True)
+        raise
+    return entry