devlab-fpga 0.1.11

FPGA development helper for installing OSS CAD Suite and running build/flash flows.

devlab

devlab is a Python CLI package for FPGA development. It installs the matching OSS CAD Suite build for the current operating system, creates a small FPGA project, and runs build/flash commands from devlab.toml.

Install

pip install devlab-fpga

For local development from this repository:

pip install -e .

Commands

devlab doctor
devlab install
devlab new blink
devlab new blink-vhdl --hdl vhdl
cd blink
devlab build
devlab flash

devlab install downloads OSS CAD Suite release 2026-07-06 from YosysHQ. The installer selects the correct asset for:

• Linux x64
• Linux arm64
• macOS x64
• macOS arm64
• Windows x64

The default install location is ~/.devlab. Set DEVLAB_HOME to use a different directory.

devlab build, devlab flash, and devlab flash --detect automatically run OSS CAD Suite tools with the installed suite environment, including the official bin, py3bin, VIRTUAL_ENV, VERILATOR_ROOT, and GHDL_PREFIX settings. You do not need to manually source environment for those commands. devlab doctor checks the tools required by the current platform.

On Windows, OSS CAD Suite may be distributed as a 7-Zip self-extracting .exe archive. devlab install extracts it automatically into ~/.devlab/toolchains without opening an installer:

devlab install

The installed tree keeps the official OSS CAD Suite layout:

~/.devlab/toolchains/oss-cad-suite-2026-07-06-windows-x64/
  oss-cad-suite/
    bin/
    environment.bat
    environment.ps1

The Windows OSS CAD Suite package does not include GHDL. For VHDL projects on Windows, install the standalone GHDL package separately:

devlab install-ghdl

This downloads ghdl-mcode-6.0.0-ucrt64.zip and installs it under ~/.devlab/toolchains. Windows VHDL builds use ghdl --synth --out=verilog to generate an intermediate Verilog file before running Yosys, so no yosys-ghdl plugin is required on Windows.

For a full Windows setup and troubleshooting guide, see docs/windows-ghdl-support.md.

On Windows, install 7-Zip before devlab install when possible. If 7z.exe is available, devlab extracts the OSS CAD Suite self-extracting archive without executing the downloaded .exe, which avoids common antivirus/App Control blocks.

OSS CAD Suite Source

Default release:

https://github.com/YosysHQ/oss-cad-suite-build/releases/tag/2026-07-06

Example assets:

https://github.com/YosysHQ/oss-cad-suite-build/releases/download/2026-07-06/oss-cad-suite-linux-arm64-20260706.tgz
https://github.com/YosysHQ/oss-cad-suite-build/releases/download/2026-07-06/oss-cad-suite-windows-x64-20260706.exe

Downloaded archives are verified with the SHA-256 digest published by the GitHub release API.

Project Format

devlab new blink creates:

blink/
  devlab.toml
  pins.cst
  src/top.v

Use --hdl vhdl to create src/top.vhd instead:

devlab new blink-vhdl --hdl vhdl

Default devlab.toml:

[fpga]
family = "GW1N-9C"
device = "GW1NR-LV9QN88PC6/I5"
cst = "pins.cst"

[build]
top = "top"
sources = ["src/top.v"]
constraints = "pins.cst"
build_dir = "build"

[flash]
board = "tangnano9k"
mode = "sram"
verify = false

For Gowin, family is the FPGA series used by the packer and place-and-route flow, for example GW1N-9C. device is the complete part number, for example GW1NR-LV9QN88PC6/I5. pins.cst is the Gowin constraints file.

Update pins.cst and [flash].board for the real FPGA board before building and flashing hardware.

Build Flows

For Gowin GW1N-9C / GW1NR-LV9QN88PC6/I5, devlab build runs:

yosys
nextpnr-himbaechel
gowin_pack

The iCE40 and ECP5 flows are still available by setting family = "ice40" or family = "ecp5" in devlab.toml.

For iCE40, it runs:

yosys
nextpnr-ice40
icepack

devlab flash uses openFPGALoader. By default it writes SRAM, so the FPGA loses the design after power cycling. Use flash mode to write the bitstream to non-volatile memory:

devlab flash --mode flash

Before writing flash on board variants where flash may or may not be populated, run detection:

devlab flash --detect
devlab flash --detect --board tangnano9k

Persistent flash can also be configured in devlab.toml:

[flash]
board = "tangnano9k"
mode = "flash"
verify = false
# external_flash = true
# offset = "0"

For Tang Nano 9K/Gowin, flash write verification may print writing verification not supported and fail the CRC check even when the flash write completed. Keep verify = false unless the selected board/programming path explicitly supports flash verification.

When sources end in .vhd or .vhdl, devlab build uses GHDL before FPGA synthesis. On Linux and macOS it runs Yosys with the GHDL plugin from the installed OSS CAD Suite tree. On Windows it uses the standalone GHDL package to write build/<top>_ghdl.v, then runs the normal Yosys synthesis flow on that generated Verilog file.

Use --dry-run to print the commands without executing them:

devlab build --dry-run
devlab flash --dry-run --board tangnano9k
devlab flash --dry-run --mode flash