lfpga 0.4.0

A package manager for FPGA/HDL development: resolve, fetch and assemble IP cores from the LibFPGA registry.

lfpga

A package manager for FPGA/HDL development. Resolve, fetch and assemble open IP cores from the LibFPGA registry 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).

$ 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:

$ 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 for the full rationale (name collisions, fuzzy versioning, filesets, vendor primitives).

Install

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
lfpga sim [--tool iverilog|verilator]	Run a simulation (deps + your testbench)
lfpga synth [--top M]	Synthesize with Yosys and report area
lfpga import <.core|Bender.yml>	Import a FuseSoC or Bender project
lfpga publish [repo]	List your core in the registry and queue verification

Publish your core

If you maintain an open FPGA core, one command lists it in the LibFPGA registry and queues it for the verification toolchain (Verilator lint, Yosys synth, an Icarus testbench):

$ lfpga publish
Publishing https://github.com/you/your-core to the LibFPGA registry...
✓ Listed as 'your-core'  →  https://libfpga.com/cores/your-core
  Queued for verification: lint, synth, testbench.
  Claim it to prove ownership: https://libfpga.com/cores/your-core/claim

Add the badge to your README:
  [![lfpga](https://libfpga.com/cores/your-core/badge.svg)](https://libfpga.com/cores/your-core)

It reads the libfpga.yaml committed on your default branch, so make sure it is pushed. Badges are always earned by the toolchain, never self-declared.

Keep it fresh in CI

Drop this into .github/workflows/lfpga.yml and every push re-lists your core and refreshes its badge (no secrets needed):

name: LibFPGA
on:
  push:
    branches: [main]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: libfpga/lfpga@v0.4.0

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.

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 2: everything in Phase 1 plus lfpga sim (Icarus/Verilator) and lfpga synth (Yosys) that actually build from the resolved sources, sim/synth filesets, and import from FuseSoC .core and Bender.yml. On the roadmap: Edalize backends for vendor flows, and lfpga publish gated by the verification toolchain.

MIT licensed. Part of LibFPGA.