Metadata-Version: 2.4
Name: lfpga
Version: 0.6.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 search <text>` | Search the registry for cores |
| `lfpga info <name>` | Show a core's registry metadata |
| `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](https://libfpga.com/cores/) and queues it for the
verification toolchain (Verilator lint, Yosys synth, an Icarus testbench):

```console
$ 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):

```yaml
name: LibFPGA
on:
  push:
    branches: [main]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: libfpga/lfpga@v0.5.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.

```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

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.
On the roadmap: Edalize backends for the vendor flows.

MIT licensed. Part of [LibFPGA](https://libfpga.com).
