A build system for gateware projects targeting FPGAs.

GBS provides a flexible, extensible build infrastructure for hardware description language (HDL) projects. It supports:

• Configuration System: User- and tree-level configs describing tools, toolchains, and repositories
• Multiple repositories and libraries: Organize code into logical units
• Dependency management: Topological sorting ensures correct build order
• Conditional source filtering: Target-specific code selection
• Pluggable backend architecture: Support for different toolchains, can add support for custom backends as plugins
• Tool management: Multiple installations with variant support
• Asyncio-based execution: Parallel builds when possible

pip install .

For development:

pip install -e ".[dev]"

Commands auto-discover a single *.gbs.yaml in the current directory:

# Build every output group declared in the project
gbs project build

# Build only the named output group(s)
gbs project build simulation

# Clean build artifacts
gbs project clean

# Show project configuration and planned build graph
gbs project show

To point at a specific project file when several coexist, use -f: gbs project -f other.gbs.yaml build. To run from elsewhere in the tree, use -C: gbs -C path/to/project project build.

Create ~/.config/gbs.yaml and register the tools you have installed. Each entry pins one binary (or install root, for IDE-style tools) under a name that backends resolve at plan time:

tools:
  - name: ghdl
    variant: system
    config:
      executable: /usr/local/bin/ghdl
  - name: yosys
    variant: system
    config:
      executable: /opt/oss-cad-suite/bin/yosys
      ghdl_plugin: /opt/oss-cad-suite/share/yosys/plugins/ghdl.so

The toolchains: key can bulk-register groups of related tools — apio distributions of oss-cad-suite and openxc7 have a provider built in. See doc/design/configuration.rst for the full config reference, and example/dot_config_gbs.yaml for a fuller sample.

A minimal project declares its top-level partition (root:), its dependencies, and one or more output groups:

name: hello

root:
  name: top
  deps:
    - nsl_data.text
    - nsl_simulation.assertions
  sources:
    - file_type: vhdl
      files:
        - top.vhd

output:
  - name: simulation
    topcell: top
    outputs:
      - type: simulator
        path: build/top

Terminal output types are the canonical shared names — bitstream, simulator, synthesis-report, pnr-report. The planner picks whichever installed backend can produce them, so a single type: bitstream project can build with Vivado, openxc7, Gowin IDE, ISE, Quartus or Diamond depending on what's on the machine.

Working projects for every builtin backend live under example/: example/ghdl/hello/ for a minimal simulation, example/openxc7/ and example/vivado/ for Xilinx synthesis flows, example/gowin/, example/diamond/, example/ise/, example/altera/, example/yosys/ for other backends.

See the doc/ directory for detailed documentation:

• Overview — Project goals and architecture
• Getting started — Walkthrough for a new project
• Command-line reference — Every subcommand and its options
• Project file reference — project.gbs.yaml schema
• Configuration system — ~/.config/gbs.yaml and .gbs.yaml
• Filter variables — Canonical vocabulary for source selection
• Build system design — Backends, passes, dispatchers, and the alias registry
• Repository system — Libraries, partitions, and conditional groups

• Python 3.13+

YMMV

MIT