lfpga 0.1.0__tar.gz

lfpga-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antonio Roldao, Ph.D.
+
+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.

lfpga-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: lfpga
+Version: 0.1.0
+Summary: A package manager for FPGA/HDL development: resolve, fetch and assemble IP cores from the LibFPGA registry.
+Author: Antonio Roldao
+License: MIT
+Project-URL: Homepage, https://libfpga.com/cores/
+Project-URL: Registry, https://libfpga.com/cores/
+Project-URL: Source, https://github.com/libfpga/lfpga
+Keywords: fpga,hdl,verilog,vhdl,package-manager,ip-cores
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Dynamic: license-file
+
+# lfpga
+
+A package manager for FPGA/HDL development. Resolve, fetch and assemble
+open IP cores from the [LibFPGA registry](https://libfpga.com/cores/) into a
+source list your simulator or synthesis tool can consume.
+
+The registry is the `pypi.org` of FPGA IP: curated, ownership-claimed, and
+toolchain-verified. **`lfpga` is the `pip`**, and its superpower is that
+every package can carry an *earned* verification badge (lints clean,
+synthesizes, testbench passes).
+
+```console
+$ lfpga init my-soc
+$ lfpga add libfpga
+Found libfpga: https://github.com/libfpga/libfpga
+  license MIT · verilog · ✓ lint, synth, testbench, formal
+$ lfpga add picorv32
+$ lfpga install
+  libfpga        a4ef4a3fa4ac  1 files  ✓ lint, synth, testbench, formal
+  picorv32       e9c4c5b8...   1 files  unverified
+
+Wrote lfpga.lock and build/sources.f (2 source files).
+```
+
+Then point your tool at the generated filelist:
+
+```console
+$ verilator --lint-only -f build/sources.f
+$ iverilog -o sim.vvp -f build/sources.f
+# Vivado: read_verilog -f build/sources.f (via -f)
+```
+
+## Why a package manager for FPGA is different
+
+FPGA IP is *source*, not binaries: there is no ABI and no linking, so
+`lfpga` vendors declared HDL files and hands them to the tool of your
+choice. It does not replace your simulator or synthesizer; it produces the
+inputs they expect. See the
+[design notes](https://github.com/libfpga/lfpga/blob/main/docs/DESIGN.md)
+for the full rationale (name collisions, fuzzy versioning, filesets,
+vendor primitives).
+
+## Install
+
+```console
+pip install lfpga        # Python 3.11+
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `lfpga init [name]` | Create a `libfpga.yaml` here |
+| `lfpga add <pkg>` | Add a dependency (`name`, `name@rev`, or a git URL) |
+| `lfpga install` | Resolve, pin (`lfpga.lock`), fetch, and write `build/sources.f` |
+| `lfpga list` | Show the locked dependencies and their badges |
+| `lfpga sources [--format verilator]` | Emit the assembled source list |
+
+## The manifest (`libfpga.yaml`)
+
+One file, like `Cargo.toml`: it both declares your dependencies and (if you
+publish) describes this repo as a package for the registry.
+
+```yaml
+name: my-soc
+dependencies:
+  libfpga: "*"                       # latest default branch
+  picorv32: { rev: v1.0.3 }          # pin a tag, branch or commit
+  libfpga-myhdl: { modules: [lfpga_mac] }   # sub-select from a repo
+  private-mac: { git: "https://github.com/acme/mac.git" }
+```
+
+## The lockfile (`lfpga.lock`)
+
+Commit it. Because HDL builds are source-and-elaborate, reproducibility is
+lockfile-first: it pins the exact commit and the exact build sources, so a
+build is identical across machines and over time.
+
+## Status
+
+Phase 0 (MVP): manifest, lockfile, git fetch, and a filelist emitter, all
+against the live registry. On the roadmap: SemVer range resolution over
+registry tags, sim/synth/formal filesets, Edalize/FuseSoC integration
+(`lfpga sim` / `lfpga synth`), and `lfpga publish` gated by the verification
+toolchain.
+
+MIT licensed. Part of [LibFPGA](https://libfpga.com).

lfpga-0.1.0/README.md

@@ -0,0 +1,87 @@
+# lfpga
+
+A package manager for FPGA/HDL development. Resolve, fetch and assemble
+open IP cores from the [LibFPGA registry](https://libfpga.com/cores/) into a
+source list your simulator or synthesis tool can consume.
+
+The registry is the `pypi.org` of FPGA IP: curated, ownership-claimed, and
+toolchain-verified. **`lfpga` is the `pip`**, and its superpower is that
+every package can carry an *earned* verification badge (lints clean,
+synthesizes, testbench passes).
+
+```console
+$ lfpga init my-soc
+$ lfpga add libfpga
+Found libfpga: https://github.com/libfpga/libfpga
+  license MIT · verilog · ✓ lint, synth, testbench, formal
+$ lfpga add picorv32
+$ lfpga install
+  libfpga        a4ef4a3fa4ac  1 files  ✓ lint, synth, testbench, formal
+  picorv32       e9c4c5b8...   1 files  unverified
+
+Wrote lfpga.lock and build/sources.f (2 source files).
+```
+
+Then point your tool at the generated filelist:
+
+```console
+$ verilator --lint-only -f build/sources.f
+$ iverilog -o sim.vvp -f build/sources.f
+# Vivado: read_verilog -f build/sources.f (via -f)
+```
+
+## Why a package manager for FPGA is different
+
+FPGA IP is *source*, not binaries: there is no ABI and no linking, so
+`lfpga` vendors declared HDL files and hands them to the tool of your
+choice. It does not replace your simulator or synthesizer; it produces the
+inputs they expect. See the
+[design notes](https://github.com/libfpga/lfpga/blob/main/docs/DESIGN.md)
+for the full rationale (name collisions, fuzzy versioning, filesets,
+vendor primitives).
+
+## Install
+
+```console
+pip install lfpga        # Python 3.11+
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `lfpga init [name]` | Create a `libfpga.yaml` here |
+| `lfpga add <pkg>` | Add a dependency (`name`, `name@rev`, or a git URL) |
+| `lfpga install` | Resolve, pin (`lfpga.lock`), fetch, and write `build/sources.f` |
+| `lfpga list` | Show the locked dependencies and their badges |
+| `lfpga sources [--format verilator]` | Emit the assembled source list |
+
+## The manifest (`libfpga.yaml`)
+
+One file, like `Cargo.toml`: it both declares your dependencies and (if you
+publish) describes this repo as a package for the registry.
+
+```yaml
+name: my-soc
+dependencies:
+  libfpga: "*"                       # latest default branch
+  picorv32: { rev: v1.0.3 }          # pin a tag, branch or commit
+  libfpga-myhdl: { modules: [lfpga_mac] }   # sub-select from a repo
+  private-mac: { git: "https://github.com/acme/mac.git" }
+```
+
+## The lockfile (`lfpga.lock`)
+
+Commit it. Because HDL builds are source-and-elaborate, reproducibility is
+lockfile-first: it pins the exact commit and the exact build sources, so a
+build is identical across machines and over time.
+
+## Status
+
+Phase 0 (MVP): manifest, lockfile, git fetch, and a filelist emitter, all
+against the live registry. On the roadmap: SemVer range resolution over
+registry tags, sim/synth/formal filesets, Edalize/FuseSoC integration
+(`lfpga sim` / `lfpga synth`), and `lfpga publish` gated by the verification
+toolchain.
+
+MIT licensed. Part of [LibFPGA](https://libfpga.com).

lfpga-0.1.0/lfpga/__init__.py

@@ -0,0 +1,8 @@
+"""lfpga: a package manager for FPGA/HDL development.
+
+Resolve, fetch and assemble open FPGA IP cores from the LibFPGA registry
+(https://libfpga.com/cores/) into a source list your simulator or synthesis
+tool can consume. The registry is the pypi; this is the pip.
+"""
+
+__version__ = "0.1.0"

lfpga-0.1.0/lfpga/cli.py

@@ -0,0 +1,194 @@
+"""The `lfpga` command-line interface."""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from . import __version__, emit, lockfile
+from .fetch import fetch
+from .manifest import (MANIFEST_NAME, Dependency, Manifest,
+                       ManifestError)
+from .registry import RegistryClient, RegistryError
+from .resolve import LockedPackage, resolve
+
+
+def _say(msg=""):
+    print(msg)
+
+
+def _err(msg):
+    print(f"lfpga: {msg}", file=sys.stderr)
+
+
+def _badges(verified):
+    earned = [k for k in ("lint", "synth", "testbench", "formal")
+              if verified.get(k)]
+    return "✓ " + ", ".join(earned) if earned else "unverified"
+
+
+# --- commands ---------------------------------------------------------------
+
+def cmd_init(args):
+    if os.path.exists(MANIFEST_NAME) and not args.force:
+        _err("libfpga.yaml already exists (use --force to overwrite)")
+        return 1
+    name = args.name or os.path.basename(os.getcwd())
+    m = Manifest(Manifest.scaffold(name))
+    m.save()
+    _say(f"Created libfpga.yaml for '{name}'.")
+    _say("Add cores with:  lfpga add <name>   (e.g. lfpga add picorv32)")
+    return 0
+
+
+def _parse_pkg_arg(spec):
+    """'name', 'name@rev', or a git URL -> (name, Dependency)."""
+    if spec.startswith(("http://", "https://", "git@")):
+        name = spec.rstrip("/").split("/")[-1].removesuffix(".git")
+        return name, Dependency(name, git=spec)
+    if "@" in spec:
+        name, rev = spec.split("@", 1)
+        return name, Dependency(name, rev=rev)
+    return spec, Dependency(spec)
+
+
+def cmd_add(args):
+    try:
+        m = Manifest.load()
+    except ManifestError:
+        m = Manifest(Manifest.scaffold(os.path.basename(os.getcwd())))
+    reg = RegistryClient(args.registry)
+    name, dep = _parse_pkg_arg(args.package)
+    if not dep.git:
+        try:
+            info = reg.package(name)
+        except RegistryError as e:
+            _err(str(e))
+            return 1
+        _say(f"Found {info['name']}: {info.get('source_url','')}")
+        _say(f"  license {info.get('license','?')} · "
+             f"{', '.join(info.get('languages', []))} · "
+             f"{_badges(info.get('verification', {}))}")
+        if info.get("unverified"):
+            _say("  note: not verified by the LibFPGA toolchain yet.")
+    m.add_dependency(dep)
+    m.save()
+    _say(f"Added '{name}' to libfpga.yaml. Run `lfpga install`.")
+    return 0
+
+
+def cmd_install(args):
+    try:
+        m = Manifest.load()
+    except ManifestError as e:
+        _err(str(e))
+        return 1
+    if not m.dependencies:
+        _say("No dependencies to install. Add some with `lfpga add`.")
+        return 0
+    reg = RegistryClient(args.registry)
+    _say(f"Resolving {len(m.dependencies)} dependencies...")
+    try:
+        locked = resolve(m, reg)
+    except (RegistryError, RuntimeError, OSError) as e:
+        _err(str(e))
+        return 1
+    lockfile.dump(locked)
+    out = emit.write_filelist(locked)
+    _say("")
+    unverified = 0
+    for pkg in locked:
+        mark = _badges(pkg.verified)
+        if not any(pkg.verified.values()):
+            unverified += 1
+        _say(f"  {pkg.name:22} {pkg.rev[:12]}  {len(pkg.files)} files  {mark}")
+        if pkg.note:
+            _say(f"  {'':22} ({pkg.note})")
+    _say("")
+    _say(f"Wrote lfpga.lock and {out} "
+         f"({sum(len(p.files) for p in locked)} source files).")
+    if unverified:
+        _say(f"Note: {unverified} package(s) carry no earned verification "
+             f"badge. See https://libfpga.com/cores/")
+    return 0
+
+
+def cmd_list(args):
+    if not os.path.exists(lockfile.LOCK_NAME):
+        _err("no lfpga.lock. Run `lfpga install` first.")
+        return 1
+    for pkg in lockfile.load():
+        _say(f"  {pkg.name:22} {pkg.rev[:12]}  "
+             f"{len(pkg.files)} files  {_badges(pkg.verified)}")
+        _say(f"  {'':22} {pkg.source}")
+    return 0
+
+
+def cmd_sources(args):
+    if not os.path.exists(lockfile.LOCK_NAME):
+        _err("no lfpga.lock. Run `lfpga install` first.")
+        return 1
+    locked = lockfile.load()
+    # ensure the pinned sources are in the cache, then emit
+    for pkg in locked:
+        pkg.path, _ = fetch(pkg.name, pkg.source, pkg.rev)
+    if args.format == "verilator":
+        _say(" ".join(emit.verilator_args(locked)))
+    else:
+        text = emit.filelist(locked)
+        if args.output:
+            with open(args.output, "w") as f:
+                f.write(text)
+            _say(f"Wrote {args.output}")
+        else:
+            sys.stdout.write(text)
+    return 0
+
+
+# --- entry point ------------------------------------------------------------
+
+def build_parser():
+    p = argparse.ArgumentParser(
+        prog="lfpga",
+        description="A package manager for FPGA/HDL development. "
+                    "Resolve, fetch and assemble IP cores from the LibFPGA "
+                    "registry (https://libfpga.com/cores/).")
+    p.add_argument("--version", action="version",
+                   version=f"lfpga {__version__}")
+    p.add_argument("--registry", default=None,
+                   help="registry base URL (default: https://libfpga.com)")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    q = sub.add_parser("init", help="create a libfpga.yaml here")
+    q.add_argument("name", nargs="?", help="project name")
+    q.add_argument("--force", action="store_true")
+    q.set_defaults(func=cmd_init)
+
+    q = sub.add_parser("add", help="add a dependency")
+    q.add_argument("package", help="name, name@rev, or a git URL")
+    q.set_defaults(func=cmd_add)
+
+    q = sub.add_parser("install", help="resolve, lock, fetch and assemble")
+    q.set_defaults(func=cmd_install)
+
+    q = sub.add_parser("list", help="show locked dependencies")
+    q.set_defaults(func=cmd_list)
+
+    q = sub.add_parser("sources", help="emit the assembled source list")
+    q.add_argument("--format", choices=["filelist", "verilator"],
+                   default="filelist")
+    q.add_argument("-o", "--output", help="write to a file instead of stdout")
+    q.set_defaults(func=cmd_sources)
+    return p
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

lfpga-0.1.0/lfpga/emit.py

@@ -0,0 +1,46 @@
+"""Assemble resolved packages into inputs real EDA tools consume.
+
+Phase 0 emits a plain filelist (`build/sources.f`): `+incdir+` lines and
+absolute paths to the cached sources, in dependency order. Verilator,
+Icarus, Vivado (`-f`), Quartus and most tools read this format. Richer
+emitters (FuseSoC .core, Edalize targets) are Phase 2.
+"""
+from __future__ import annotations
+
+import os
+
+
+def _abs(pkg, rel):
+    return os.path.normpath(os.path.join(pkg.path, rel))
+
+
+def filelist(locked):
+    """Return the text of a `-f` filelist for the resolved packages."""
+    lines = []
+    for pkg in locked:
+        lines.append(f"// --- {pkg.name} @ {pkg.rev[:12]} ---")
+        for d in pkg.include_dirs:
+            lines.append("+incdir+" + _abs(pkg, d))
+        for f in pkg.files:
+            lines.append(_abs(pkg, f))
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def verilator_args(locked):
+    """Return Verilator/Icarus-style argument tokens for the sources."""
+    args = []
+    for pkg in locked:
+        for d in pkg.include_dirs:
+            args.append("+incdir+" + _abs(pkg, d))
+    for pkg in locked:
+        for f in pkg.files:
+            args.append(_abs(pkg, f))
+    return args
+
+
+def write_filelist(locked, out_path="build/sources.f"):
+    os.makedirs(os.path.dirname(out_path) or ".", exist_ok=True)
+    with open(out_path, "w") as f:
+        f.write(filelist(locked))
+    return out_path

lfpga-0.1.0/lfpga/fetch.py

@@ -0,0 +1,77 @@
+"""Fetch package sources with git, into a content cache.
+
+FPGA "packages" are source, not binaries: we clone the repo (at a tag,
+branch or commit) and vendor the declared files. Everything is cached
+under ~/.lfpga/cache so repeated installs are fast and offline-friendly.
+"""
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+
+CACHE_ROOT = os.environ.get(
+    "LFPGA_CACHE", os.path.join(os.path.expanduser("~"), ".lfpga", "cache"))
+
+_SHA = re.compile(r"^[0-9a-f]{7,40}$")
+
+
+class FetchError(Exception):
+    pass
+
+
+def _run(args, **kw):
+    return subprocess.run(args, capture_output=True, text=True, **kw)
+
+
+def _git(path, *args):
+    return _run(["git", "-C", path, *args])
+
+
+def fetch(name, url, rev=None):
+    """Clone `url` (at `rev`, or the default branch HEAD) into the cache.
+
+    Returns (path, commit_sha). `rev` may be a tag, branch or commit sha.
+    """
+    os.makedirs(CACHE_ROOT, exist_ok=True)
+    dest = os.path.join(CACHE_ROOT, name)
+
+    if os.path.isdir(os.path.join(dest, ".git")):
+        # refresh an existing checkout
+        _git(dest, "fetch", "--quiet", "--tags", "origin")
+        if rev:
+            co = _git(dest, "checkout", "--quiet", rev)
+            if co.returncode != 0:
+                _reclone(dest, url, rev)
+    else:
+        _clone(dest, url, rev)
+
+    head = _git(dest, "rev-parse", "HEAD")
+    if head.returncode != 0:
+        raise FetchError(f"{name}: could not resolve HEAD after fetch")
+    return dest, head.stdout.strip()
+
+
+def _clone(dest, url, rev):
+    # Fast path: shallow clone of a tag/branch (or default HEAD).
+    args = ["git", "clone", "--quiet", "--depth", "1"]
+    if rev and not _SHA.match(rev):
+        args += ["--branch", rev]
+    args += [url, dest]
+    r = _run(args)
+    if r.returncode == 0:
+        return
+    # rev is a commit sha (or the shallow branch clone failed): full clone.
+    _reclone(dest, url, rev)
+
+
+def _reclone(dest, url, rev):
+    import shutil
+    shutil.rmtree(dest, ignore_errors=True)
+    r = _run(["git", "clone", "--quiet", url, dest])
+    if r.returncode != 0:
+        raise FetchError(f"clone failed for {url}: {r.stderr.strip()[:200]}")
+    if rev:
+        co = _git(dest, "checkout", "--quiet", rev)
+        if co.returncode != 0:
+            raise FetchError(f"rev '{rev}' not found in {url}")

lfpga-0.1.0/lfpga/lockfile.py

@@ -0,0 +1,57 @@
+"""Read and write lfpga.lock (TOML).
+
+Because HDL builds are source-and-elaborate with no ABI, reproducibility is
+lockfile-first: the lock pins the exact commit and the exact build sources
+for every package, so a build is identical across machines and over time.
+Commit it to your repo. Reading uses the stdlib tomllib (Python 3.11+); the
+writer is a small, purpose-built emitter for this fixed schema.
+"""
+from __future__ import annotations
+
+import tomllib
+
+from .resolve import LockedPackage
+
+LOCK_NAME = "lfpga.lock"
+LOCK_VERSION = 1
+
+
+def _toml_str(s):
+    return '"' + str(s).replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def _toml_list(items):
+    return "[" + ", ".join(_toml_str(i) for i in items) + "]"
+
+
+def dump(locked, path=LOCK_NAME):
+    lines = ["# Auto-generated by lfpga. Commit this file.",
+             f"version = {LOCK_VERSION}", ""]
+    for pkg in sorted(locked, key=lambda p: p.name):
+        lines.append("[[package]]")
+        lines.append(f"name = {_toml_str(pkg.name)}")
+        lines.append(f"source = {_toml_str(pkg.source)}")
+        lines.append(f"rev = {_toml_str(pkg.rev)}")
+        lines.append(f"files = {_toml_list(pkg.files)}")
+        lines.append(f"include_dirs = {_toml_list(pkg.include_dirs)}")
+        if pkg.verified:
+            earned = sorted(k for k, v in pkg.verified.items() if v)
+            lines.append(f"verified = {_toml_list(earned)}")
+        if pkg.note:
+            lines.append(f"note = {_toml_str(pkg.note)}")
+        lines.append("")
+    with open(path, "w") as f:
+        f.write("\n".join(lines))
+
+
+def load(path=LOCK_NAME):
+    with open(path, "rb") as f:
+        data = tomllib.load(f)
+    out = []
+    for p in data.get("package", []):
+        pkg = LockedPackage(
+            p["name"], p["source"], p["rev"],
+            p.get("files", []), p.get("include_dirs", []),
+            {k: True for k in p.get("verified", [])}, p.get("note", ""))
+        out.append(pkg)
+    return out

lfpga-0.1.0/lfpga/manifest.py

@@ -0,0 +1,106 @@
+"""The project manifest: libfpga.yaml.
+
+Like Cargo.toml, one file both publishes this repo as a package (the fields
+the LibFPGA registry already understands) and declares its dependencies. A
+leaf design that publishes nothing just uses the `dependencies` section.
+
+    name: my-soc
+    top_module: soc_top
+    dependencies:
+      libfpga: "*"                 # latest default branch
+      picorv32: { rev: v1.0.3 }    # pin a tag/branch/commit
+      libfpga-myhdl: { modules: [lfpga_mac] }   # sub-select from a repo
+"""
+from __future__ import annotations
+
+import os
+
+import yaml
+
+MANIFEST_NAME = "libfpga.yaml"
+
+
+class ManifestError(Exception):
+    pass
+
+
+class Dependency:
+    """One dependency line. `spec` is a version string or a table."""
+
+    def __init__(self, name, version="*", rev=None, git=None, modules=None):
+        self.name = name
+        self.version = version or "*"
+        self.rev = rev
+        self.git = git
+        self.modules = list(modules or [])
+
+    @classmethod
+    def from_spec(cls, name, spec):
+        if spec is None or isinstance(spec, str):
+            return cls(name, version=spec or "*")
+        if not isinstance(spec, dict):
+            raise ManifestError(f"bad dependency spec for '{name}': {spec!r}")
+        return cls(name, version=spec.get("version", "*"),
+                   rev=spec.get("rev"), git=spec.get("git"),
+                   modules=spec.get("modules"))
+
+    def to_spec(self):
+        """Round-trip back to the compact YAML form."""
+        if not self.rev and not self.git and not self.modules \
+                and self.version in ("*", None):
+            return "*"
+        out = {}
+        if self.version and self.version != "*":
+            out["version"] = self.version
+        if self.rev:
+            out["rev"] = self.rev
+        if self.git:
+            out["git"] = self.git
+        if self.modules:
+            out["modules"] = self.modules
+        return out or "*"
+
+    def __repr__(self):
+        ref = self.rev or self.version
+        return f"<Dependency {self.name}@{ref}>"
+
+
+class Manifest:
+    def __init__(self, data, path=MANIFEST_NAME):
+        self.data = data or {}
+        self.path = path
+        self.name = self.data.get("name", "project")
+        self.dependencies = {
+            n: Dependency.from_spec(n, s)
+            for n, s in (self.data.get("dependencies") or {}).items()
+        }
+
+    @classmethod
+    def load(cls, path=MANIFEST_NAME):
+        if not os.path.exists(path):
+            raise ManifestError(
+                f"no {path} here. Run `lfpga init` to create one.")
+        with open(path) as f:
+            return cls(yaml.safe_load(f) or {}, path)
+
+    def add_dependency(self, dep: Dependency):
+        self.dependencies[dep.name] = dep
+        self.data.setdefault("dependencies", {})[dep.name] = dep.to_spec()
+
+    def remove_dependency(self, name):
+        self.dependencies.pop(name, None)
+        (self.data.get("dependencies") or {}).pop(name, None)
+
+    def save(self):
+        with open(self.path, "w") as f:
+            yaml.safe_dump(self.data, f, sort_keys=False,
+                           default_flow_style=False)
+
+    @staticmethod
+    def scaffold(name):
+        return {
+            "name": name,
+            "top_module": "",
+            "filesets": {"rtl": {"files": [], "include_dirs": []}},
+            "dependencies": {},
+        }

lfpga-0.1.0/lfpga/registry.py

@@ -0,0 +1,43 @@
+"""Talk to the LibFPGA registry (https://libfpga.com/cores/).
+
+The registry resolves a package name to its source repo, license and
+earned verification badges. This is a thin HTTP client; the registry does
+the curation, ownership and verification.
+"""
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+
+DEFAULT_REGISTRY = os.environ.get("LFPGA_REGISTRY", "https://libfpga.com")
+
+
+class RegistryError(Exception):
+    pass
+
+
+class RegistryClient:
+    def __init__(self, base=None):
+        self.base = (base or DEFAULT_REGISTRY).rstrip("/")
+
+    def package(self, slug):
+        """Return the package metadata dict, or raise RegistryError."""
+        url = f"{self.base}/cores/{slug}.json"
+        req = urllib.request.Request(url, headers={"User-Agent": "lfpga"})
+        try:
+            with urllib.request.urlopen(req, timeout=20) as r:
+                data = json.loads(r.read().decode())
+        except urllib.error.HTTPError as e:
+            if e.code == 404:
+                raise RegistryError(
+                    f"package '{slug}' is not in the registry "
+                    f"({self.base}/cores/). Check the name, or add it with "
+                    f"a git: URL.")
+            raise RegistryError(f"registry HTTP {e.code} for '{slug}'")
+        except urllib.error.URLError as e:
+            raise RegistryError(f"cannot reach the registry: {e.reason}")
+        if data.get("error"):
+            raise RegistryError(f"package '{slug}' not found")
+        return data

lfpga-0.1.0/lfpga/resolve.py

@@ -0,0 +1,104 @@
+"""Resolve manifest dependencies into a concrete, pinned set of packages.
+
+Phase 0: each dependency is fetched and pinned to an exact commit; its
+build sources are read from the repo's own libfpga.yaml (the same manifest
+the registry verifies). SemVer range solving over registry tags is Phase 1;
+today, ranges resolve to the default branch and the lockfile pins the sha.
+"""
+from __future__ import annotations
+
+import glob
+import os
+
+import yaml
+
+from .fetch import fetch
+from .manifest import MANIFEST_NAME
+from .registry import RegistryClient
+
+# filesets that are NOT build inputs (testbenches, sim-only)
+_SIM_FILESETS = {"sim", "tb", "test", "testbench", "formal"}
+
+
+class LockedPackage:
+    def __init__(self, name, source, rev, files, include_dirs,
+                 verified=None, note=""):
+        self.name = name
+        self.source = source
+        self.rev = rev
+        self.files = files
+        self.include_dirs = include_dirs
+        self.verified = verified or {}
+        self.note = note          # e.g. "globbed (no libfpga.yaml)"
+        self.path = None          # cache path, set at fetch time
+
+
+def _read_repo_sources(path, modules):
+    """Return (files, include_dirs, note) for the build (synth) sources of a
+    fetched repo, read from its libfpga.yaml or globbed as a fallback."""
+    mpath = os.path.join(path, MANIFEST_NAME)
+    files, incs, note = [], [], ""
+    if os.path.exists(mpath):
+        with open(mpath) as f:
+            m = yaml.safe_load(f) or {}
+        filesets = m.get("filesets")
+        if isinstance(filesets, dict):
+            for key, fs in filesets.items():
+                if key.lower() in _SIM_FILESETS or not isinstance(fs, dict):
+                    continue
+                files += fs.get("files", [])
+                incs += fs.get("include_dirs", [])
+        if not files:                       # flat registry-style manifest
+            files += m.get("files", [])
+            if m.get("top") and m["top"] not in files:
+                files.append(m["top"])
+            incs += m.get("include_dirs", [])
+    if not files:
+        files = _glob_sources(path)
+        note = "no libfpga.yaml: globbed HDL sources"
+    if modules:
+        picked = [f for f in files
+                  if os.path.splitext(os.path.basename(f))[0] in modules]
+        if picked:
+            files = picked
+        else:
+            note = (note + "; " if note else "") + \
+                f"modules {modules} not matched, kept all"
+    # de-dup, preserve order
+    files = list(dict.fromkeys(files))
+    incs = list(dict.fromkeys(incs))
+    return files, incs, note
+
+
+def _glob_sources(path):
+    for pat in ("rtl/**/*.sv", "rtl/**/*.v", "src/**/*.sv", "src/**/*.v",
+                "*.sv", "*.v"):
+        hits = sorted(glob.glob(os.path.join(path, pat), recursive=True))
+        hits = [os.path.relpath(h, path) for h in hits
+                if "/tb" not in h and "/test" not in h]
+        if hits:
+            return hits
+    return []
+
+
+def resolve(manifest, registry=None):
+    """Resolve every dependency to a LockedPackage. Returns the list."""
+    registry = registry or RegistryClient()
+    locked = []
+    for name, dep in manifest.dependencies.items():
+        verified = {}
+        if dep.git:
+            url = dep.git
+        else:
+            info = registry.package(name)
+            url = info.get("source_url")
+            if not url:
+                raise RuntimeError(
+                    f"'{name}' has no source_url in the registry")
+            verified = info.get("verification", {})
+        path, commit = fetch(name, url, dep.rev)
+        files, incs, note = _read_repo_sources(path, dep.modules)
+        pkg = LockedPackage(name, url, commit, files, incs, verified, note)
+        pkg.path = path
+        locked.append(pkg)
+    return locked

lfpga-0.1.0/lfpga.egg-info/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: lfpga
+Version: 0.1.0
+Summary: A package manager for FPGA/HDL development: resolve, fetch and assemble IP cores from the LibFPGA registry.
+Author: Antonio Roldao
+License: MIT
+Project-URL: Homepage, https://libfpga.com/cores/
+Project-URL: Registry, https://libfpga.com/cores/
+Project-URL: Source, https://github.com/libfpga/lfpga
+Keywords: fpga,hdl,verilog,vhdl,package-manager,ip-cores
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Dynamic: license-file
+
+# lfpga
+
+A package manager for FPGA/HDL development. Resolve, fetch and assemble
+open IP cores from the [LibFPGA registry](https://libfpga.com/cores/) into a
+source list your simulator or synthesis tool can consume.
+
+The registry is the `pypi.org` of FPGA IP: curated, ownership-claimed, and
+toolchain-verified. **`lfpga` is the `pip`**, and its superpower is that
+every package can carry an *earned* verification badge (lints clean,
+synthesizes, testbench passes).
+
+```console
+$ lfpga init my-soc
+$ lfpga add libfpga
+Found libfpga: https://github.com/libfpga/libfpga
+  license MIT · verilog · ✓ lint, synth, testbench, formal
+$ lfpga add picorv32
+$ lfpga install
+  libfpga        a4ef4a3fa4ac  1 files  ✓ lint, synth, testbench, formal
+  picorv32       e9c4c5b8...   1 files  unverified
+
+Wrote lfpga.lock and build/sources.f (2 source files).
+```
+
+Then point your tool at the generated filelist:
+
+```console
+$ verilator --lint-only -f build/sources.f
+$ iverilog -o sim.vvp -f build/sources.f
+# Vivado: read_verilog -f build/sources.f (via -f)
+```
+
+## Why a package manager for FPGA is different
+
+FPGA IP is *source*, not binaries: there is no ABI and no linking, so
+`lfpga` vendors declared HDL files and hands them to the tool of your
+choice. It does not replace your simulator or synthesizer; it produces the
+inputs they expect. See the
+[design notes](https://github.com/libfpga/lfpga/blob/main/docs/DESIGN.md)
+for the full rationale (name collisions, fuzzy versioning, filesets,
+vendor primitives).
+
+## Install
+
+```console
+pip install lfpga        # Python 3.11+
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `lfpga init [name]` | Create a `libfpga.yaml` here |
+| `lfpga add <pkg>` | Add a dependency (`name`, `name@rev`, or a git URL) |
+| `lfpga install` | Resolve, pin (`lfpga.lock`), fetch, and write `build/sources.f` |
+| `lfpga list` | Show the locked dependencies and their badges |
+| `lfpga sources [--format verilator]` | Emit the assembled source list |
+
+## The manifest (`libfpga.yaml`)
+
+One file, like `Cargo.toml`: it both declares your dependencies and (if you
+publish) describes this repo as a package for the registry.
+
+```yaml
+name: my-soc
+dependencies:
+  libfpga: "*"                       # latest default branch
+  picorv32: { rev: v1.0.3 }          # pin a tag, branch or commit
+  libfpga-myhdl: { modules: [lfpga_mac] }   # sub-select from a repo
+  private-mac: { git: "https://github.com/acme/mac.git" }
+```
+
+## The lockfile (`lfpga.lock`)
+
+Commit it. Because HDL builds are source-and-elaborate, reproducibility is
+lockfile-first: it pins the exact commit and the exact build sources, so a
+build is identical across machines and over time.
+
+## Status
+
+Phase 0 (MVP): manifest, lockfile, git fetch, and a filelist emitter, all
+against the live registry. On the roadmap: SemVer range resolution over
+registry tags, sim/synth/formal filesets, Edalize/FuseSoC integration
+(`lfpga sim` / `lfpga synth`), and `lfpga publish` gated by the verification
+toolchain.
+
+MIT licensed. Part of [LibFPGA](https://libfpga.com).

lfpga-0.1.0/lfpga.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+lfpga/__init__.py
+lfpga/cli.py
+lfpga/emit.py
+lfpga/fetch.py
+lfpga/lockfile.py
+lfpga/manifest.py
+lfpga/registry.py
+lfpga/resolve.py
+lfpga.egg-info/PKG-INFO
+lfpga.egg-info/SOURCES.txt
+lfpga.egg-info/dependency_links.txt
+lfpga.egg-info/entry_points.txt
+lfpga.egg-info/requires.txt
+lfpga.egg-info/top_level.txt
+tests/test_lfpga.py

lfpga-0.1.0/lfpga.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

lfpga-0.1.0/lfpga.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lfpga = lfpga.cli:main

lfpga-0.1.0/lfpga.egg-info/requires.txt

@@ -0,0 +1 @@
+PyYAML>=6.0

lfpga-0.1.0/lfpga.egg-info/top_level.txt

@@ -0,0 +1 @@
+lfpga

lfpga-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lfpga"
+version = "0.1.0"
+description = "A package manager for FPGA/HDL development: resolve, fetch and assemble IP cores from the LibFPGA registry."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Antonio Roldao" }]
+keywords = ["fpga", "hdl", "verilog", "vhdl", "package-manager", "ip-cores"]
+dependencies = ["PyYAML>=6.0"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Build Tools",
+  "Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)",
+]
+
+[project.urls]
+Homepage = "https://libfpga.com/cores/"
+Registry = "https://libfpga.com/cores/"
+Source = "https://github.com/libfpga/lfpga"
+
+[project.scripts]
+lfpga = "lfpga.cli:main"
+
+[tool.setuptools]
+packages = ["lfpga"]

lfpga-0.1.0/setup.cfg

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

lfpga-0.1.0/tests/test_lfpga.py

@@ -0,0 +1,105 @@
+"""Offline tests for lfpga (no network / git needed)."""
+import os
+import tempfile
+import unittest
+
+import yaml
+
+from lfpga import emit, lockfile
+from lfpga.manifest import Dependency, Manifest
+from lfpga.resolve import LockedPackage, _read_repo_sources
+
+
+class TestManifest(unittest.TestCase):
+    def test_scaffold_and_add_roundtrip(self):
+        m = Manifest(Manifest.scaffold("demo"))
+        m.add_dependency(Dependency("picorv32", rev="v1.0.3"))
+        m.add_dependency(Dependency("libfpga"))
+        with tempfile.TemporaryDirectory() as d:
+            m.path = os.path.join(d, "libfpga.yaml")
+            m.save()
+            back = Manifest.load(m.path)
+        self.assertEqual(back.name, "demo")
+        self.assertEqual(back.dependencies["picorv32"].rev, "v1.0.3")
+        self.assertEqual(back.dependencies["libfpga"].version, "*")
+
+    def test_dep_spec_forms(self):
+        self.assertEqual(Dependency.from_spec("a", None).version, "*")
+        self.assertEqual(Dependency.from_spec("a", "^1.0").version, "^1.0")
+        d = Dependency.from_spec("a", {"rev": "abc", "modules": ["m"]})
+        self.assertEqual(d.rev, "abc")
+        self.assertEqual(d.modules, ["m"])
+
+    def test_git_dep_roundtrips(self):
+        d = Dependency("x", git="https://example.com/x.git")
+        self.assertEqual(d.to_spec(), {"git": "https://example.com/x.git"})
+
+
+class TestLockfile(unittest.TestCase):
+    def test_dump_load_roundtrip(self):
+        pkgs = [LockedPackage("libfpga", "https://h/libfpga",
+                              "a" * 40, ["rtl/crc.v"], ["rtl"],
+                              {"lint": True, "synth": True}, "")]
+        with tempfile.TemporaryDirectory() as d:
+            p = os.path.join(d, "lfpga.lock")
+            lockfile.dump(pkgs, p)
+            back = lockfile.load(p)
+        self.assertEqual(len(back), 1)
+        self.assertEqual(back[0].name, "libfpga")
+        self.assertEqual(back[0].rev, "a" * 40)
+        self.assertEqual(back[0].files, ["rtl/crc.v"])
+        self.assertTrue(back[0].verified.get("lint"))
+
+
+class TestEmit(unittest.TestCase):
+    def test_filelist(self):
+        pkg = LockedPackage("libfpga", "u", "abc123def456",
+                            ["rtl/crc.v"], ["rtl"])
+        pkg.path = "/cache/libfpga"
+        text = emit.filelist([pkg])
+        self.assertIn("+incdir+/cache/libfpga/rtl", text)
+        self.assertIn("/cache/libfpga/rtl/crc.v", text)
+        self.assertIn("libfpga @ abc123def456", text)
+
+
+class TestReadRepoSources(unittest.TestCase):
+    def _repo(self, d, manifest):
+        os.makedirs(os.path.join(d, "rtl"))
+        for name in ("a.v", "b.v"):
+            open(os.path.join(d, "rtl", name), "w").close()
+        if manifest is not None:
+            with open(os.path.join(d, "libfpga.yaml"), "w") as f:
+                yaml.safe_dump(manifest, f)
+
+    def test_flat_manifest(self):
+        with tempfile.TemporaryDirectory() as d:
+            self._repo(d, {"files": ["rtl/a.v"], "include_dirs": ["rtl"]})
+            files, incs, note = _read_repo_sources(d, [])
+            self.assertEqual(files, ["rtl/a.v"])
+            self.assertEqual(incs, ["rtl"])
+            self.assertEqual(note, "")
+
+    def test_filesets_excludes_sim(self):
+        with tempfile.TemporaryDirectory() as d:
+            self._repo(d, {"filesets": {
+                "rtl": {"files": ["rtl/a.v"], "include_dirs": ["rtl"]},
+                "sim": {"files": ["rtl/b.v"]}}})
+            files, incs, note = _read_repo_sources(d, [])
+            self.assertEqual(files, ["rtl/a.v"])         # sim fileset dropped
+
+    def test_glob_fallback_when_no_manifest(self):
+        with tempfile.TemporaryDirectory() as d:
+            self._repo(d, None)
+            files, incs, note = _read_repo_sources(d, [])
+            self.assertIn("rtl/a.v", files)
+            self.assertIn("globbed", note)
+
+    def test_module_subselect(self):
+        with tempfile.TemporaryDirectory() as d:
+            self._repo(d, {"files": ["rtl/a.v", "rtl/b.v"]})
+            files, _, _ = _read_repo_sources(d, ["a"])
+            self.assertEqual(files, ["rtl/a.v"])
+
+
+if __name__ == "__main__":
+    unittest.main()