How to run a build end to end

This guide takes a design from a build spec to a validated Vivado build that is ready to run. It follows the plan-first flow: everything up to the synthesis itself is composed and checked on your development machine, and only the execute=true step needs a Vivado host.

The stages are synthesize, stage, build, validate, and then programming the board. This is the Vivado bitstream flow, so every backend-specific command below is a vivado command. For a fast open-source synthesis check that runs anywhere, select the yosys engine on the synthesize task instead (backend=backends/yosys; see the task catalog).

Field lists for each task are in the task catalog. To see the full resolved config for any command before running it, add --explain (for example dau-build --explain task=tasks/build/synthesize ...).

Synthesize the handoff

Generate the DAU top, the artifact bundle, and the vivado/<stem>.manifest backend handoff. This writes a manifest at build_status=planned and does not invoke Vivado:

dau-build task=tasks/build/synthesize \
  spec=specs/identity \
  model.module=dau_identity_top \
  model.output_root=outputs/identity

Your own spec is a spec option too: put a yaml file with _target_: dau_build.build_spec.BuildSpec and the spec’s fields under <dir>/spec/specs/<name>.yaml and run with --config-dir <dir> spec=specs/<name> (set base_dir to the directory the spec’s relative paths start from). To attach a specific board and backend to the resolved config, add board=boards/example/probe backend=backends/vivado.

Stage the Vivado work directory

Staging copies a read-only Vivado shell seed into a writable work directory and writes the overlay Tcl, the guarded build Tcl, the backend manifest and the command plan, still without running Vivado.

For a full project dry run that also records checkout roots and the stage/build/validate command contract, use stage-vivado-project:

dau-build task=tasks/stage/stage-vivado-project \
  model.source_shell_root=/path/to/vivado-shell-seed \
  model.work_root=outputs/vivado \
  model.dau_core_root=/path/to/dau-core \
  model.dau_driver_root=/path/to/dau-driver \
  model.artifact_stem=dau-vivado

If you only need the overlay artifacts, use tasks/stage/stage-vivado-overlay (it requires model.work_root and model.dau_core_root). To fold a DAU artifact bundle into the overlay, add model.dau_artifact_bundle=<bundle.yaml>. If your Vivado runs through a wrapper that only accepts a Tcl source path, add model.vivado_invocation=source-only; if that wrapper mounts the current directory in a container, also add model.vivado_mount_root=/path/to/dau.

Validate before you synthesize

Check that the staged plan agrees with itself (manifest, overlay Tcl, build Tcl, command plan and planned output paths) without Xilinx tools:

dau-build task=tasks/validate/validate-vivado-artifacts \
  model.work_root=outputs/vivado \
  model.project_manifest_path=dau-vivado.project

Do this on your development machine before moving to the Vivado host. A failure here is cheap; the same failure partway through synthesis is not.

Build on the Vivado host

On the machine with Vivado, run the generated overlay/build command and let it validate the artifact bundle. This step spends real synthesis time, so it needs execute=true:

dau-build task=tasks/build/build-vivado-artifacts \
  model.work_root=outputs/vivado \
  model.artifact_stem=dau-vivado \
  model.execute=true

Once the bitstream, resource report, timing report and Vivado log exist, this moves the backend manifest from build_status=planned to built, and records the routed worst slack as wns_ns. A run whose slack is negative or unreadable is recorded as timing-failed instead: the bitstream exists, and nothing downstream will flash it. Flashing and smoke testing require built.

Treat the Vivado machine as an ordinary Linux host: SSH in, rsync the checkouts or the generated work directory you need, pip install the DAU packages there, and run the same CLIs. dau-build does not wrap host orchestration.

Next

With a built bitstream, continue to Program a bitstream on a board.