devlab-fpga 0.1.0__py3-none-any.whl

devlab/__init__.py

@@ -0,0 +1,6 @@
+"""Python helpers for the devlab FPGA command line tools."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"
+

devlab/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

devlab/cli.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import argparse
+import platform
+from pathlib import Path
+
+from . import __version__
+from .errors import DevlabError
+from .platforms import current_platform
+from .project import build_project, create_project, detect_flash, doctor, flash_project
+from .toolchain import (
+    OSS_CAD_SUITE_RELEASE_URL,
+    archive_path,
+    devlab_home,
+    install_oss_cad_suite,
+    install_path,
+    select_asset,
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="devlab",
+        description="Install FPGA toolchains and run local FPGA build flows.",
+    )
+    parser.add_argument("--version", action="version", version=f"devlab {__version__}")
+
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    doctor_parser = commands.add_parser("doctor", help="Check local FPGA tools.")
+    doctor_parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Exit 1 when a tool is missing.",
+    )
+    doctor_parser.set_defaults(func=_doctor)
+
+    install_parser = commands.add_parser("install", help="Install OSS CAD Suite.")
+    install_parser.add_argument("--force", action="store_true", help="Re-download and reinstall.")
+    install_parser.add_argument(
+        "--run-installer",
+        action="store_true",
+        help="On Windows, execute the downloaded OSS CAD Suite installer.",
+    )
+    install_parser.set_defaults(func=_install)
+
+    new_parser = commands.add_parser("new", help="Create a new FPGA project.")
+    new_parser.add_argument("name", help="Project directory name.")
+    new_parser.add_argument("--dir", type=Path, help="Target directory. Defaults to NAME.")
+    new_parser.add_argument("--force", action="store_true", help="Overwrite template files.")
+    new_parser.add_argument(
+        "--hdl",
+        choices=("verilog", "vhdl"),
+        default="verilog",
+        help="Source template language. Defaults to verilog.",
+    )
+    new_parser.set_defaults(func=_new)
+
+    build = commands.add_parser("build", help="Build the current FPGA project.")
+    build.add_argument("-c", "--config", type=Path, help="Path to devlab.toml.")
+    build.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print commands without running them.",
+    )
+    build.set_defaults(func=_build)
+
+    flash = commands.add_parser("flash", help="Flash the built FPGA bitstream.")
+    flash.add_argument("-c", "--config", type=Path, help="Path to devlab.toml.")
+    flash.add_argument("--board", help="openFPGALoader board name.")
+    flash.add_argument("--artifact", type=Path, help="Bitstream path.")
+    flash.add_argument(
+        "--mode",
+        choices=("sram", "flash"),
+        help="Write target. sram is temporary; flash is persistent after reboot.",
+    )
+    flash.add_argument(
+        "--detect",
+        action="store_true",
+        help="Detect FPGA and flash support without writing a bitstream.",
+    )
+    flash.add_argument(
+        "--verify",
+        action="store_true",
+        help="Verify flash write when supported by the board/programming path.",
+    )
+    flash.add_argument(
+        "--no-verify",
+        action="store_true",
+        help="Skip flash verification when using --mode flash.",
+    )
+    flash.add_argument(
+        "--external-flash",
+        action="store_true",
+        help="Use external flash when the device has internal and external storage.",
+    )
+    flash.add_argument("--offset", help="Flash offset in bytes.")
+    flash.add_argument("--dry-run", action="store_true", help="Print command without running it.")
+    flash.set_defaults(func=_flash)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except DevlabError as exc:
+        parser.exit(2, f"devlab: error: {exc}\n")
+
+
+def _doctor(args: argparse.Namespace) -> int:
+    platform_id = current_platform()
+    asset = select_asset(platform_id)
+    print(f"devlab: {__version__}")
+    print(f"python: {platform.python_version()} ({platform.python_implementation()})")
+    print(f"platform: {platform_id.key}")
+    print(f"home: {devlab_home()}")
+    print(f"release: {OSS_CAD_SUITE_RELEASE_URL}")
+    print(f"asset: {asset.name}")
+    print(f"archive: {archive_path(asset)}")
+    print(f"toolchain: {install_path(asset)}")
+    return doctor(strict=args.strict)
+
+
+def _install(args: argparse.Namespace) -> int:
+    destination = install_oss_cad_suite(
+        force=args.force,
+        run_windows_installer=args.run_installer,
+    )
+    print(f"OSS CAD Suite installed at {destination}")
+    return 0
+
+
+def _new(args: argparse.Namespace) -> int:
+    root = create_project(args.name, directory=args.dir, force=args.force, hdl=args.hdl)
+    print(f"Created FPGA project at {root}")
+    return 0
+
+
+def _build(args: argparse.Namespace) -> int:
+    artifact = build_project(config_path=args.config, dry_run=args.dry_run)
+    print(f"Build artifact: {artifact}")
+    return 0
+
+
+def _flash(args: argparse.Namespace) -> int:
+    if args.verify and args.no_verify:
+        raise DevlabError("--verify and --no-verify cannot be used together.")
+
+    if args.detect:
+        detect_flash(
+            config_path=args.config,
+            board=args.board,
+            dry_run=args.dry_run,
+        )
+        return 0
+
+    flash_project(
+        config_path=args.config,
+        board=args.board,
+        artifact=args.artifact,
+        mode=args.mode,
+        verify=True if args.verify else False if args.no_verify else None,
+        external_flash=True if args.external_flash else None,
+        offset=args.offset,
+        dry_run=args.dry_run,
+    )
+    return 0

devlab/errors.py

@@ -0,0 +1,3 @@
+class DevlabError(RuntimeError):
+    """User-facing error raised by devlab commands."""
+

devlab/platforms.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import platform
+from dataclasses import dataclass
+
+from .errors import DevlabError
+
+
+@dataclass(frozen=True)
+class PlatformId:
+    os_name: str
+    arch: str
+
+    @property
+    def key(self) -> str:
+        return f"{self.os_name}-{self.arch}"
+
+
+def current_platform() -> PlatformId:
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+
+    if system == "linux":
+        os_name = "linux"
+    elif system == "darwin":
+        os_name = "darwin"
+    elif system in {"windows", "msys", "cygwin"}:
+        os_name = "windows"
+    else:
+        raise DevlabError(f"Unsupported operating system: {platform.system()}")
+
+    if machine in {"x86_64", "amd64"}:
+        arch = "x64"
+    elif machine in {"aarch64", "arm64"}:
+        arch = "arm64"
+    else:
+        raise DevlabError(f"Unsupported CPU architecture: {platform.machine()}")
+
+    return PlatformId(os_name=os_name, arch=arch)
+

devlab/project.py

@@ -0,0 +1,430 @@
+from __future__ import annotations
+
+import shlex
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .errors import DevlabError
+from .toolchain import env_with_toolchain, find_executable, install_path
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - Python < 3.11
+    import tomli as tomllib  # type: ignore
+
+
+DEFAULT_CONFIG = "devlab.toml"
+
+
+@dataclass
+class BuildConfig:
+    family: str = "GW1N-9C"
+    device: str = "GW1NR-LV9QN88PC6/I5"
+    package: str = "sg48"
+    top: str = "top"
+    sources: list[str] = field(default_factory=lambda: ["src/top.v"])
+    constraints: str = "pins.cst"
+    build_dir: str = "build"
+    board: str | None = None
+    flash_mode: str = "sram"
+    flash_verify: bool = False
+    external_flash: bool = False
+    flash_offset: str | None = None
+    series: str | None = None
+
+    @property
+    def artifact(self) -> str:
+        if self.flow == "ecp5":
+            return f"{self.build_dir}/{self.top}.bit"
+        if self.flow == "gowin":
+            return f"{self.build_dir}/{self.top}.fs"
+        return f"{self.build_dir}/{self.top}.bin"
+
+    @property
+    def flow(self) -> str:
+        family = self.family.lower()
+        if family in {"gowin", "apicula"} or family.startswith("gw"):
+            return "gowin"
+        return family
+
+    @property
+    def gowin_family(self) -> str:
+        if self.series:
+            return self.series
+        if self.family.lower() in {"gowin", "apicula"}:
+            raise DevlabError(
+                "Gowin builds need [fpga] family = \"GW1N-9C\" "
+                "or [fpga] series = \"GW1N-9C\"."
+            )
+        return self.family
+
+
+def load_config(path: Path | None = None) -> BuildConfig:
+    config_path = path or Path(DEFAULT_CONFIG)
+    if not config_path.exists():
+        raise DevlabError(f"Project config not found: {config_path}")
+
+    with config_path.open("rb") as handle:
+        data = tomllib.load(handle)
+
+    fpga = _section(data, "fpga")
+    build = _section(data, "build")
+    flash = _section(data, "flash")
+
+    return BuildConfig(
+        family=str(fpga.get("family", "GW1N-9C")),
+        device=str(fpga.get("device", "GW1NR-LV9QN88PC6/I5")),
+        package=str(fpga.get("package", "sg48")),
+        top=str(build.get("top", "top")),
+        sources=[str(item) for item in build.get("sources", ["src/top.v"])],
+        constraints=str(build.get("constraints", fpga.get("cst", "pins.cst"))),
+        build_dir=str(build.get("build_dir", "build")),
+        board=flash.get("board"),
+        flash_mode=str(flash.get("mode", "sram")).lower(),
+        flash_verify=bool(flash.get("verify", False)),
+        external_flash=bool(flash.get("external_flash", False)),
+        flash_offset=str(flash["offset"]) if "offset" in flash else None,
+        series=fpga.get("series"),
+    )
+
+
+def create_project(
+    name: str,
+    directory: Path | None = None,
+    force: bool = False,
+    hdl: str = "verilog",
+) -> Path:
+    hdl = hdl.lower()
+    if hdl not in {"verilog", "vhdl"}:
+        raise DevlabError(f"Unsupported HDL: {hdl}")
+
+    root = directory or Path(name)
+    if root.exists() and any(root.iterdir()) and not force:
+        raise DevlabError(f"Directory is not empty: {root}")
+
+    source_name = "top.vhd" if hdl == "vhdl" else "top.v"
+    (root / "src").mkdir(parents=True, exist_ok=True)
+    _write(root / "devlab.toml", _template_config(source_name), force)
+    _write(root / "src" / source_name, _template_top(hdl), force)
+    _write(root / "pins.cst", _template_constraints(), force)
+    _write(root / ".gitignore", "build/\n", force)
+    return root
+
+
+def build_project(config_path: Path | None = None, dry_run: bool = False) -> Path:
+    config = load_config(config_path)
+    build_dir = Path(config.build_dir)
+    build_dir.mkdir(parents=True, exist_ok=True)
+
+    commands = build_commands(config)
+    for command in commands:
+        _run(command, dry_run=dry_run)
+
+    return Path(config.artifact)
+
+
+def flash_project(
+    config_path: Path | None = None,
+    board: str | None = None,
+    artifact: Path | None = None,
+    mode: str | None = None,
+    verify: bool | None = None,
+    external_flash: bool | None = None,
+    offset: str | None = None,
+    dry_run: bool = False,
+) -> None:
+    config = load_config(config_path)
+    selected_board = board or config.board
+    if not selected_board:
+        raise DevlabError(
+            "No flash board configured. Add [flash] board = \"...\" "
+            "to devlab.toml or pass --board."
+        )
+
+    bitstream = artifact or Path(config.artifact)
+    if not dry_run and not bitstream.exists():
+        raise DevlabError(f"Bitstream not found: {bitstream}")
+
+    _run(
+        flash_command(
+            config,
+            selected_board,
+            bitstream,
+            mode=mode,
+            verify=verify,
+            external_flash=external_flash,
+            offset=offset,
+        ),
+        dry_run=dry_run,
+    )
+
+
+def detect_flash(
+    config_path: Path | None = None,
+    board: str | None = None,
+    dry_run: bool = False,
+) -> None:
+    config = load_config(config_path)
+    selected_board = board or config.board
+    if not selected_board:
+        raise DevlabError(
+            "No flash board configured. Add [flash] board = \"...\" "
+            "to devlab.toml or pass --board."
+        )
+
+    _run(["openFPGALoader", "-b", selected_board, "--detect", "-f"], dry_run=dry_run)
+
+
+def flash_command(
+    config: BuildConfig,
+    board: str,
+    bitstream: Path,
+    mode: str | None = None,
+    verify: bool | None = None,
+    external_flash: bool | None = None,
+    offset: str | None = None,
+) -> list[str]:
+    selected_mode = (mode or config.flash_mode).lower()
+    if selected_mode not in {"sram", "flash"}:
+        raise DevlabError(f"Unsupported flash mode: {selected_mode}")
+
+    command = ["openFPGALoader", "-b", board]
+    if selected_mode == "flash":
+        command.append("-f")
+        selected_verify = verify if verify is not None else config.flash_verify
+        if selected_verify:
+            command.append("--verify")
+        selected_external = (
+            external_flash if external_flash is not None else config.external_flash
+        )
+        if selected_external:
+            command.append("--external-flash")
+        selected_offset = offset if offset is not None else config.flash_offset
+        if selected_offset:
+            command.extend(["--offset", selected_offset])
+    else:
+        command.append("-m")
+
+    command.append(str(bitstream))
+    return command
+
+
+def build_commands(config: BuildConfig) -> list[list[str]]:
+    if config.flow == "gowin":
+        json_file = f"{config.build_dir}/{config.top}.json"
+        pnr_json_file = f"{config.build_dir}/{config.top}_pnr.json"
+        return [
+            _yosys_command(config, f"synth_gowin -top {config.top} -json {json_file}"),
+            [
+                "nextpnr-himbaechel",
+                "--json",
+                json_file,
+                "--write",
+                pnr_json_file,
+                "--device",
+                config.device,
+                "--vopt",
+                f"family={config.gowin_family}",
+                "--vopt",
+                f"cst={config.constraints}",
+            ],
+            [
+                "gowin_pack",
+                "-d",
+                config.gowin_family,
+                "-o",
+                config.artifact,
+                pnr_json_file,
+            ],
+        ]
+
+    if config.flow == "ice40":
+        json_file = f"{config.build_dir}/{config.top}.json"
+        asc_file = f"{config.build_dir}/{config.top}.asc"
+        return [
+            _yosys_command(config, f"synth_ice40 -top {config.top} -json {json_file}"),
+            [
+                "nextpnr-ice40",
+                f"--{config.device}",
+                "--package",
+                config.package,
+                "--json",
+                json_file,
+                "--pcf",
+                config.constraints,
+                "--asc",
+                asc_file,
+            ],
+            ["icepack", asc_file, config.artifact],
+        ]
+
+    if config.flow == "ecp5":
+        json_file = f"{config.build_dir}/{config.top}.json"
+        cfg_file = f"{config.build_dir}/{config.top}.config"
+        return [
+            _yosys_command(config, f"synth_ecp5 -top {config.top} -json {json_file}"),
+            [
+                "nextpnr-ecp5",
+                "--json",
+                json_file,
+                "--lpf",
+                config.constraints,
+                "--textcfg",
+                cfg_file,
+                "--um5g-85k" if config.device == "um5g-85k" else f"--{config.device}",
+                "--package",
+                config.package,
+            ],
+            ["ecppack", cfg_file, config.artifact],
+        ]
+
+    raise DevlabError(f"Unsupported FPGA family: {config.family}")
+
+
+def doctor(strict: bool = False) -> int:
+    checks = {
+        "yosys": find_executable("yosys", install_path()),
+        "ghdl": find_executable("ghdl", install_path()),
+        "nextpnr-himbaechel": find_executable("nextpnr-himbaechel", install_path()),
+        "gowin_pack": find_executable("gowin_pack", install_path()),
+        "nextpnr-ice40": find_executable("nextpnr-ice40", install_path()),
+        "nextpnr-ecp5": find_executable("nextpnr-ecp5", install_path()),
+        "icepack": find_executable("icepack", install_path()),
+        "ecppack": find_executable("ecppack", install_path()),
+        "openFPGALoader": find_executable("openFPGALoader", install_path()),
+    }
+    failed = False
+    for name, executable in checks.items():
+        if executable:
+            print(f"ok      {name}: {executable}")
+        else:
+            failed = True
+            print(f"missing {name}")
+    if failed:
+        print("Run `devlab install` to install OSS CAD Suite.")
+    return 1 if strict and failed else 0
+
+
+def _yosys_command(config: BuildConfig, synth_script: str) -> list[str]:
+    hdl = _source_hdl(config.sources)
+    if hdl == "vhdl":
+        sources = " ".join(shlex.quote(source) for source in config.sources)
+        return [
+            "yosys",
+            "-m",
+            "ghdl",
+            "-p",
+            f"ghdl --std=08 {sources} -e {config.top}; {synth_script}",
+        ]
+    return ["yosys", "-p", synth_script, *config.sources]
+
+
+def _source_hdl(sources: list[str]) -> str:
+    has_vhdl = any(Path(source).suffix.lower() in {".vhd", ".vhdl"} for source in sources)
+    has_verilog = any(
+        Path(source).suffix.lower() in {".v", ".vh", ".sv", ".svh"} for source in sources
+    )
+    if has_vhdl and has_verilog:
+        raise DevlabError("Mixed VHDL and Verilog sources are not supported yet.")
+    if has_vhdl:
+        return "vhdl"
+    return "verilog"
+
+
+def _section(data: dict[str, Any], name: str) -> dict[str, Any]:
+    value = data.get(name, {})
+    if not isinstance(value, dict):
+        raise DevlabError(f"[{name}] must be a table in devlab.toml")
+    return value
+
+
+def _run(command: list[str], dry_run: bool) -> None:
+    resolved = find_executable(command[0], install_path())
+    if not resolved:
+        if dry_run:
+            print("+ " + " ".join(command))
+            return
+        raise DevlabError(
+            f"Required command not found: {command[0]}. Run `devlab install` first."
+        )
+
+    executable_command = [resolved, *command[1:]]
+    print("+ " + " ".join(executable_command))
+    if dry_run:
+        return
+    subprocess.check_call(executable_command, env=env_with_toolchain(install_path()))
+
+
+def _write(path: Path, content: str, force: bool) -> None:
+    if path.exists() and not force:
+        raise DevlabError(f"File already exists: {path}")
+    path.write_text(content, encoding="utf-8")
+
+
+def _template_config(source_name: str = "top.v") -> str:
+    return """[fpga]
+family = "GW1N-9C"
+device = "GW1NR-LV9QN88PC6/I5"
+cst = "pins.cst"
+
+[build]
+top = "top"
+sources = ["src/%s"]
+constraints = "pins.cst"
+build_dir = "build"
+
+[flash]
+board = "tangnano9k"
+mode = "sram"
+verify = false
+""" % source_name
+
+
+def _template_top(hdl: str = "verilog") -> str:
+    if hdl == "vhdl":
+        return """library ieee;
+use ieee.std_logic_1164.all;
+use ieee.numeric_std.all;
+
+entity top is
+    port (
+        clk : in std_logic;
+        led : out std_logic
+    );
+end entity top;
+
+architecture rtl of top is
+    signal counter : unsigned(23 downto 0) := (others => '0');
+begin
+    process (clk)
+    begin
+        if rising_edge(clk) then
+            counter <= counter + 1;
+            led <= counter(23);
+        end if;
+    end process;
+end architecture rtl;
+"""
+
+    return """module top (
+    input wire clk,
+    output reg led
+);
+    reg [23:0] counter = 0;
+
+    always @(posedge clk) begin
+        counter <= counter + 1;
+        led <= counter[23];
+    end
+endmodule
+"""
+
+
+def _template_constraints() -> str:
+    return """// Update these pins for your GW1NR-LV9QN88PC6/I5 board.
+// Example Gowin CST syntax:
+// IO_LOC "clk" 52;
+// IO_LOC "led" 10;
+"""

devlab/toolchain.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+import hashlib
+import os
+import shutil
+import stat
+import subprocess
+import sys
+import tarfile
+import tempfile
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+
+from .errors import DevlabError
+from .platforms import PlatformId, current_platform
+
+
+OSS_CAD_SUITE_TAG = "2026-07-06"
+OSS_CAD_SUITE_RELEASE_URL = (
+    "https://github.com/YosysHQ/oss-cad-suite-build/releases/tag/2026-07-06"
+)
+
+
+@dataclass(frozen=True)
+class ToolchainAsset:
+    platform: str
+    name: str
+    url: str
+    sha256: str
+
+    @property
+    def suffix(self) -> str:
+        return Path(self.name).suffix
+
+
+OSS_CAD_SUITE_ASSETS: dict[str, ToolchainAsset] = {
+    "darwin-arm64": ToolchainAsset(
+        platform="darwin-arm64",
+        name="oss-cad-suite-darwin-arm64-20260706.tgz",
+        url="https://github.com/YosysHQ/oss-cad-suite-build/releases/download/2026-07-06/oss-cad-suite-darwin-arm64-20260706.tgz",
+        sha256="8e7677c6876000c19f49582ffcefbbe6ee49ddb802170a9f86eca95dcba7ed67",
+    ),
+    "darwin-x64": ToolchainAsset(
+        platform="darwin-x64",
+        name="oss-cad-suite-darwin-x64-20260706.tgz",
+        url="https://github.com/YosysHQ/oss-cad-suite-build/releases/download/2026-07-06/oss-cad-suite-darwin-x64-20260706.tgz",
+        sha256="5adceaa550b1ce9961ce81f0ea0ef2245fcb665863fb970e068c17aab83779ad",
+    ),
+    "linux-arm64": ToolchainAsset(
+        platform="linux-arm64",
+        name="oss-cad-suite-linux-arm64-20260706.tgz",
+        url="https://github.com/YosysHQ/oss-cad-suite-build/releases/download/2026-07-06/oss-cad-suite-linux-arm64-20260706.tgz",
+        sha256="0943e9eda87ee49b5c96aacc543bbe4301332467f0b2e7a374028608bcf4c961",
+    ),
+    "linux-x64": ToolchainAsset(
+        platform="linux-x64",
+        name="oss-cad-suite-linux-x64-20260706.tgz",
+        url="https://github.com/YosysHQ/oss-cad-suite-build/releases/download/2026-07-06/oss-cad-suite-linux-x64-20260706.tgz",
+        sha256="213a50813e809637f37dd86bb03cad7a58e726f841e7685d3a3062ef2492c315",
+    ),
+    "windows-x64": ToolchainAsset(
+        platform="windows-x64",
+        name="oss-cad-suite-windows-x64-20260706.exe",
+        url="https://github.com/YosysHQ/oss-cad-suite-build/releases/download/2026-07-06/oss-cad-suite-windows-x64-20260706.exe",
+        sha256="e8ab814d490d89163e418dc634842cf086ea305dde0c32f832528194a5b93ac9",
+    ),
+}
+
+
+def devlab_home() -> Path:
+    return Path(os.environ.get("DEVLAB_HOME", Path.home() / ".devlab")).expanduser()
+
+
+def toolchains_dir(home: Path | None = None) -> Path:
+    return (home or devlab_home()) / "toolchains"
+
+
+def cache_dir(home: Path | None = None) -> Path:
+    return (home or devlab_home()) / "cache"
+
+
+def select_asset(platform_id: PlatformId | None = None) -> ToolchainAsset:
+    platform_id = platform_id or current_platform()
+    try:
+        return OSS_CAD_SUITE_ASSETS[platform_id.key]
+    except KeyError as exc:
+        supported = ", ".join(sorted(OSS_CAD_SUITE_ASSETS))
+        raise DevlabError(
+            f"Unsupported platform for OSS CAD Suite: {platform_id.key}. "
+            f"Supported: {supported}"
+        ) from exc
+
+
+def install_path(asset: ToolchainAsset | None = None, home: Path | None = None) -> Path:
+    asset = asset or select_asset()
+    return toolchains_dir(home) / f"oss-cad-suite-{OSS_CAD_SUITE_TAG}-{asset.platform}"
+
+
+def archive_path(asset: ToolchainAsset | None = None, home: Path | None = None) -> Path:
+    asset = asset or select_asset()
+    return cache_dir(home) / asset.name
+
+
+def bin_dir(path: Path | None = None) -> Path:
+    path = path or install_path()
+    return path / "bin"
+
+
+def env_with_toolchain(path: Path | None = None) -> dict[str, str]:
+    env = os.environ.copy()
+    binary_dir = str(bin_dir(path))
+    env["PATH"] = binary_dir + os.pathsep + env.get("PATH", "")
+    return env
+
+
+def find_executable(name: str, path: Path | None = None) -> str | None:
+    suffixes = [""]
+    if sys.platform.startswith("win"):
+        suffixes = [".exe", ".bat", ".cmd", ""]
+
+    candidates: list[str] = []
+    binary_dir = bin_dir(path)
+    for suffix in suffixes:
+        candidates.append(str(binary_dir / f"{name}{suffix}"))
+
+    for candidate in candidates:
+        if Path(candidate).exists():
+            return candidate
+    return shutil.which(name, path=env_with_toolchain(path).get("PATH"))
+
+
+def download_asset(asset: ToolchainAsset, destination: Path, force: bool = False) -> Path:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    if destination.exists() and not force:
+        verify_sha256(destination, asset.sha256)
+        return destination
+
+    tmp_destination = destination.with_suffix(destination.suffix + ".part")
+    if tmp_destination.exists():
+        tmp_destination.unlink()
+
+    def report(blocks: int, block_size: int, total_size: int) -> None:
+        if total_size <= 0:
+            return
+        downloaded = min(blocks * block_size, total_size)
+        percent = downloaded * 100 / total_size
+        print(f"\rDownloading {asset.name}: {percent:5.1f}%", end="", flush=True)
+
+    try:
+        urllib.request.urlretrieve(asset.url, tmp_destination, reporthook=report)
+        print()
+    except OSError as exc:
+        raise DevlabError(f"Could not download {asset.url}: {exc}") from exc
+
+    verify_sha256(tmp_destination, asset.sha256)
+    tmp_destination.replace(destination)
+    return destination
+
+
+def verify_sha256(path: Path, expected: str) -> None:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    actual = digest.hexdigest()
+    if actual != expected:
+        raise DevlabError(
+            f"SHA-256 mismatch for {path.name}: expected {expected}, got {actual}"
+        )
+
+
+def install_oss_cad_suite(
+    home: Path | None = None,
+    force: bool = False,
+    run_windows_installer: bool = False,
+) -> Path:
+    home = home or devlab_home()
+    asset = select_asset()
+    destination = install_path(asset, home)
+
+    if destination.exists() and not force:
+        return destination
+
+    archive = download_asset(asset, archive_path(asset, home), force=force)
+
+    if asset.name.endswith(".exe"):
+        if not run_windows_installer:
+            raise DevlabError(
+                "Windows uses the OSS CAD Suite .exe installer. "
+                f"The file was downloaded to {archive}. Re-run with "
+                "--run-installer to execute it."
+            )
+        subprocess.check_call([str(archive)])
+        return destination
+
+    _extract_tarball(archive, destination, force=force)
+    _mark_executables(bin_dir(destination))
+    return destination
+
+
+def _extract_tarball(archive: Path, destination: Path, force: bool) -> None:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    if destination.exists():
+        if not force:
+            raise DevlabError(f"Install destination already exists: {destination}")
+        shutil.rmtree(destination)
+
+    with tempfile.TemporaryDirectory(prefix="devlab-oss-cad-suite-") as tmp:
+        tmp_path = Path(tmp)
+        with tarfile.open(archive, "r:gz") as tar:
+            _safe_extract(tar, tmp_path)
+
+        children = [child for child in tmp_path.iterdir()]
+        if len(children) == 1 and children[0].is_dir():
+            shutil.move(str(children[0]), destination)
+        else:
+            destination.mkdir(parents=True)
+            for child in children:
+                shutil.move(str(child), destination / child.name)
+
+
+def _safe_extract(tar: tarfile.TarFile, destination: Path) -> None:
+    destination = destination.resolve()
+    for member in tar.getmembers():
+        target = (destination / member.name).resolve()
+        if destination != target and destination not in target.parents:
+            raise DevlabError(f"Unsafe path in archive: {member.name}")
+    try:
+        tar.extractall(destination, filter="data")
+    except TypeError:  # pragma: no cover - Python < 3.12
+        tar.extractall(destination)
+
+
+def _mark_executables(path: Path) -> None:
+    if not path.exists():
+        return
+    for file_path in path.iterdir():
+        if not file_path.is_file():
+            continue
+        mode = file_path.stat().st_mode
+        file_path.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)

devlab_fpga-0.1.0.dist-info/METADATA

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: devlab-fpga
+Version: 0.1.0
+Summary: FPGA development helper for installing OSS CAD Suite and running build/flash flows.
+Author-email: Mrju10 <name@email.com>
+License: MIT
+Project-URL: Homepage, https://github.com/unit-electronics/unit_devlab_lib
+Project-URL: Source, https://github.com/unit-electronics/unit_devlab_lib
+Keywords: fpga,yosys,oss-cad-suite,openfpgaloader,devlab,devlab-fpga
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli>=2.0.1; python_version < "3.11"
+Dynamic: license-file
+
+# 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
+
+```bash
+pip install devlab-fpga
+```
+
+For local development from this repository:
+
+```bash
+pip install -e .
+```
+
+## Commands
+
+```bash
+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.
+
+## OSS CAD Suite Source
+
+Default release:
+
+https://github.com/YosysHQ/oss-cad-suite-build/releases/tag/2026-07-06
+
+Example assets:
+
+```text
+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:
+
+```text
+blink/
+  devlab.toml
+  pins.cst
+  src/top.v
+```
+
+Use `--hdl vhdl` to create `src/top.vhd` instead:
+
+```bash
+devlab new blink-vhdl --hdl vhdl
+```
+
+Default `devlab.toml`:
+
+```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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+devlab flash --mode flash
+```
+
+Before writing flash on board variants where flash may or may not be populated,
+run detection:
+
+```bash
+devlab flash --detect
+```
+
+Persistent flash can also be configured in `devlab.toml`:
+
+```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` runs Yosys with the
+GHDL plugin before synthesis. OSS CAD Suite is expected to provide that plugin.
+
+Use `--dry-run` to print the commands without executing them:
+
+```bash
+devlab build --dry-run
+devlab flash --dry-run --board tangnano9k
+devlab flash --dry-run --mode flash
+```

devlab_fpga-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+devlab/__init__.py,sha256=8YbSz2Aj8SQbG_L7_RgQ-ygB4R-qq6II-Tvv4fiAcD4,112
+devlab/__main__.py,sha256=PSQ4rpL0dG6f-qH4N7H-gD9igQkdHzH4yVZDcW8lfZo,80
+devlab/cli.py,sha256=X5TyrC72x4XefcI3QgJnbBcCcrutdRKGd0z5kQwPwGM,5726
+devlab/errors.py,sha256=RFT2YqJthU2N7wdYZZ5YJXkmrFr34kYyyT2JJL1MXXo,89
+devlab/platforms.py,sha256=xOHG2f1u7G3dB4tXM-PlJgMQ_qrkjTIlPgBnhxLaXNI,946
+devlab/project.py,sha256=dZ2YuGOMV3cqMhgXin-Ny4wa7LB8IpbYGFeJHK1YiBI,13050
+devlab/toolchain.py,sha256=b-GEDbdVcNtGPNHk4zf3ZY279n5KOLGoslEQWMTkLWw,8336
+devlab_fpga-0.1.0.dist-info/licenses/LICENSE,sha256=nrbPcnyVbAcWTBTG_nJt3M2yHrL-zucDeHC02dJ09Fo,1063
+devlab_fpga-0.1.0.dist-info/METADATA,sha256=Mwqi0BP_I673k4lXJ1m9mwNUC13zqNhQp4fA_O3xZKc,4448
+devlab_fpga-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+devlab_fpga-0.1.0.dist-info/entry_points.txt,sha256=5kjH9FbXX8jasuwPZH1hTpVrGc4-jbOje92tLitLYvg,43
+devlab_fpga-0.1.0.dist-info/top_level.txt,sha256=dVqsvPXb6Uy0rMo_xDjEyvHLc-v_B28HCh0bKP3-saA,7
+devlab_fpga-0.1.0.dist-info/RECORD,,

devlab_fpga-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

devlab_fpga-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+devlab = devlab.cli:main

devlab_fpga-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mrju10
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

devlab_fpga-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+devlab