How to extend dau-build¶

You extend dau-build without editing it. Its config tree is on the Hydra search path, so an installed package can add its own tasks, steps, boards, backends or platforms, and they compose alongside the packaged ones. This guide covers the three additions you are most likely to make: a task from your own package, a board or platform, and a synthesis backend.

For the concepts behind the search path and the config groups, see the architecture explanation. To test an overlay without packaging it, see the last section of this guide.

Register your config tree on the search path¶

The one-time setup: give your package a config directory laid out like dau-build’s (config groups as subdirectories), make it importable, and register it on the Hydra search path.

Put a Hydra config tree in your package, for example mypkg/config/, with an __init__.py so mypkg.config is an importable package. Hydra resolves the pkg: search-path entry by importing it.
Add the entry point and depend on the search-path bridge in pyproject.toml:
```
dependencies = ["dau-build", "lerna>=2.0.4"]

[project.entry-points."hydra.lernaplugins"]
mypkg = "pkg:mypkg.config"
```
lerna is what honors the hydra.lernaplugins entry point; without it the entry point does nothing.

Your groups now compose through dau-build’s Hydra CLIs. dau-build never imports your package. Extension flows one way, so your code can depend on dau-build while dau-build stays free of it.

Add a task¶

A task is a config file plus the ccflow.CallableModel it targets.

Write the model as a ccflow.CallableModel in your package (for example mypkg.tasks.MyTask).
Add mypkg/config/task/tasks/<category>/<name>.yaml:
```
# @package model

_target_: mypkg.tasks.MyTask
some_field: ???
other_field: default
```
The # @package model directive makes the selected task the model that runs. dau-build derives its name-to-class registry by globbing the config tree, so there is nothing else to register; _target_ may point at any importable module.

Run it through the dau-build CLI:

dau-build task=tasks/<category>/<name> model.some_field=value

The dau package adds task=shell this way: with dau installed, dau-build task=shell design=designs/bar-noc model.output_root=... resolves a task defined entirely in dau, with no --config-dir overlay.

Add a board or platform¶

Boards and platforms reuse dau-build’s existing models, so they are config only, with no new Python.

For a board’s build-config view, add mypkg/config/board/boards/<vendor>/<board>.yaml:

# @package board

_target_: dau_build.build_config.BoardConfig
name: myboard
platform: my-xdma
shell: my-shell

For the hardware platform definition (part, resource budget, memory, host link), add mypkg/config/platform/platforms/<vendor>/<board>.yaml targeting dau_build.platforms.PlatformDefinition. Select them with board=boards/<vendor>/<board> and platform=platforms/<vendor>/<board>.

Add a synthesis engine¶

The synthesis engine is the backend config group. Each option instantiates a polymorphic SynthesisEngine model, and SynthesizeTask delegates to engine.synthesize(...); there is no dispatch if to edit. YosysEngine is the worked example: read the backend section of the architecture explanation first, then use yosys_backend.py and YosysEngine as the template. A new engine needs:

An engine model: a SynthesisEngine subclass with a synthesize method and whatever fields it needs (like YosysEngine.frontend). Its synthesize either generates a plan (Vivado’s Tcl and manifests) or generates and runs a tool (yosys’s script and run_yosys_synthesis). Put the heavy backend logic in a module alongside yosys_backend.py.
A config option so it is selectable and configurable. Add <pkg>/config/backend/backends/<name>.yaml; this is exactly backends/yosys.yaml:
```
# @package backend

_target_: mypkg.engines.NextpnrEngine
name: nextpnr
invocation: standard
```
It composes as backend=backends/<name> and is configurable through backend.<field>=... with no change to SynthesizeTask.
Any build and validate tasks your flow needs, mirroring the Vivado ones, each targeting a new ccflow.CallableModel.

Because the engine is a composed model, an engine defined in your own package composes through the search path alone. Nothing lands in dau-build unless you extend the packaged set.

Try it without packaging¶

To test a config overlay before packaging it, point the CLI at a directory with --config-dir:

dau-build --config-dir ./my-configs task=tasks/<category>/<name> model.some_field=value

The overlay’s groups merge into the tree for that run, and its _target_ models can come from any importable package. This is the quickest way to iterate on a new task config before wiring up the entry point.