hwbuild.yml

Place a hwbuild.yml in your project root to define default synthesis parameters. The CLI reads it automatically when you ssynth job submit a directory.

All CLI flags override hwbuild.yml values.

Example

top_module: top
target:
  family: ice40
  device: hx8k
  package: ct256
sources:
  - "src/*.v"
  - "lib/**/*.sv"
constraints:
  - pins.pcf
  - timing.pcf
seeds: 4
pick: best_timing
priority: standard
parallelism: 2
steps:
  - synth
  - pnr
  - bitstream
max_runtime: "2h"
max_memory: "8GB"
profile: <PROFILE_ID>
tool_args:
  yosys_args:
    extra_passes:
      - abc9
      - opt
  nextpnr_args:
    extra_flags:
      - --tmg-ripup
  bitstream_args:
    extra_flags:
      - --compress
synth_script: synth.ys

Fields

Field	Type	Description
`top_module`	string	Top-level module name. Alias: `top`
`target.family`	string	`ice40` or `ecp5`
`target.device`	string	Device code (e.g., `hx8k`, `85k`)
`target.package`	string	Package code (e.g., `ct256`, `CABGA554`)
`target.board`	string	Optional board name
`sources`	list	File paths or globs for HDL sources. If omitted, all `.v`, `.sv`, `.vhd`, `.vhdl` files are discovered recursively.
`constraints`	list	Constraint files relative to project root. Multiple files supported (e.g., separate pin and timing constraints).
`seeds`	integer	Number of seeds (1-128, plan-limited)
`pick`	string	`best_timing` or `best_area`
`priority`	string	`interactive`, `standard`, or `batch`
`parallelism`	integer	Concurrent seed count (1-16, plan-limited)
`steps`	list	Subset of: `synth`, `pnr`, `bitstream`. Omit steps for quick validation (e.g., `synth` only).
`max_runtime`	string	Duration: `"2h"`, `"30m"`, `"1h30m"` (max 7 days)
`max_memory`	string	Memory: `"8GB"`, `"4096MB"` (512 MB to 128 GB)
`profile`	string	Build profile ID. Inherits target and tool args from the profile.
`tool_args`	object	Per-tool arguments. Merged on top of profile args (see below).
`synth_script`	string	Path to a custom Yosys `.ys` script. Replaces auto-generated synthesis commands.

Tool arguments

The tool_args object lets you pass extra arguments to each pipeline tool:

tool_args:
  yosys_args:
    extra_passes:     # Yosys passes run after synthesis
      - abc9
      - opt
      - flatten
  nextpnr_args:
    extra_flags:      # Flags appended to the nextpnr command
      - --tmg-ripup
      - --placer-heap-timingweight
      - "50"
  bitstream_args:
    extra_flags:      # Flags appended to icepack/ecppack
      - --compress

All arguments are validated against an allowlist. Shell metacharacters are rejected.

When both a profile and tool_args are specified, per-tool merge applies: if the job provides a non-empty list for a tool, it replaces the profile’s list for that tool. Empty lists inherit from the profile.

Source file discovery

If sources is omitted, SuperSynth discovers HDL files recursively:

Verilog: .v
SystemVerilog: .sv
VHDL: .vhd, .vhdl

Include directories are automatically collected from the parent directories of discovered source files and passed to Yosys as -I flags.

VHDL files are compiled with GHDL (--std=08) before Yosys synthesis. Mixed Verilog/VHDL projects are supported — VHDL is processed first, then Verilog sources are read.

Target resolution order

CLI --target flag
hwbuild.yml target section
Build profile’s target (if profile specified)
Project’s default target
Error if none specified