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

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.5.0

Private cores (Pro)

Keep your own IP in a private registry: add a private core at libfpga.com/account (Pro), then set an API token so lfpga can resolve and install it. Private cores never appear in the public registry, search or sitemap.

export LFPGA_TOKEN=lfpga_...      # a Pro API token from libfpga.com/account
lfpga add my-axi-dma             # resolves your private core
lfpga install

The token is sent as Authorization: Bearer and only unlocks cores you own.

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

Actively developed. Resolution is transitive: each package's own libfpga.yaml dependencies are pulled in, de-duplicated across the graph, and checked for version conflicts (cycle-safe). Plus lfpga search / lfpga info for discovery and lfpga publish to list your own core. It also generates Vivado and Quartus build scripts from the resolved graph (lfpga sources --format vivado|quartus). On the roadmap: invoking the vendor tools directly.

MIT licensed. Part of LibFPGA.