Metadata-Version: 2.4
Name: lfpga
Version: 0.3.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 |
| `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 |

## 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 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](https://libfpga.com).
