# 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](program-hardware.md). 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](../reference/tasks-and-steps.md)).

Field lists for each task are in the [task catalog](../reference/tasks-and-steps.md).
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:

```bash
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`:

```bash
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:

```bash
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`:

```bash
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](program-hardware.md).