project.yml Reference

Complete field reference for the RouteRTL SDK project configuration file.

Run routertl init (or rr init) to generate a working project.yml interactively.

Quick Reference

Sections

project

Project identity. Used for Vivado/Quartus project naming and simulation top selection.

project:
  name: my_project          # Project name (Vivado project, directory names)
  top_module: my_top        # Synthesis top-level entity/module
  top_sim: tb_my_top        # Simulation top-level (for VUnit, testgen)
  path: project             # Vivado .xpr project directory (default: project/)

path behavior: Controls where the Vivado/Quartus .xpr/.qpf project is created. Build artifacts (dcp/, bitstream/, build/) remain at the project root — only the vendor project directory moves. Can also be set via makefile_overrides.project_dir. Useful for multi-target setups where each target config uses a separate project directory.

hardware

FPGA target and HDL language selection.

hardware:
  vendor: xilinx            # xilinx, lattice, or altera
  part: "xc7z020clg400-1"   # Full part number (quoted for YAML safety)
  family: artix7             # FPGA family (optional, for TCL hooks)
  language: vhdl             # vhdl, verilog, systemverilog, or mixed
  platform: default          # Board/platform identifier
  tool_path: /opt/altera_std # Absolute path to vendor tool installation

tool_path behavior:

When set, the SDK probes the following subdirectories in order and prepends the first match to PATH: quartus/bin, bin, bin/lin64, Libero/bin. For Intel/Altera, QUARTUS_ROOTDIR is also set automatically. This ensures vendor tools resolve correctly regardless of system PATH ordering.

Language behavior:

simulation

Simulation engine configuration.

simulation:
  test_dir: sim/cocotb/tests       # Test discovery directory
  simulator: nvc                   # Simulator backend
  generics:                        # VHDL generics / Verilog parameters
    G_DATA_WIDTH: 32
    G_FIFO_DEPTH: 8

  # Waveform output control
  waves:
    enabled: true                  # Generate waveforms (default: true)
    formats: [fst]                 # Formats to produce: fst, vcd, ghw
    output_dir: sim/waves          # Output directory (relative to root)

  # Log output control (NEW)
  logs:
    output_dir: sim/logs           # Output directory (relative to root)

simulation.waves

Controls waveform generation format and output location.

Supported formats per simulator:

Unsupported formats are silently skipped.

Precedence chain: run_simulation() kwarg > project.yml > env var (ROUTERTL_WAVES_DIR) > engine default.

simulation.logs

The simulator field determines which HDL compiler Cocotb uses. Use nvc for Cocotb 2.0+ (required). GHDL is incompatible with Cocotb 2.0+.

Legacy flat fields: simulation.waves_dir and simulation.logs_dir (strings) are accepted as flat aliases for simulation.waves.output_dir and simulation.logs.output_dir respectively. They are exported as SIM_WAVES_DIR and SIM_LOGS_DIR in build_env.mk. Prefer the nested form in new projects.

simulation.tags

Named test groups for batch execution via routertl sim --tag <name>.

simulation:
  tags:
    smoke: [test_edge_counter, test_lfsr]
    uart:  [test_uart_sniffer, test_uart_master]
    full:  [test_edge_counter, test_lfsr, test_uart_sniffer, test_uart_master]

Each tag maps a name to a list of test module names. When invoked with routertl sim --tag smoke, each test in the list is run sequentially and a pass/fail summary is printed at the end.

simulation.generics

Override VHDL generics or Verilog/SystemVerilog parameters at simulation time. Works with all simulator backends.

simulation:
  generics:
    G_DATA_WIDTH: 32
    G_FIFO_DEPTH: 8
    DEFAULT_BUSY_HIGH: 1

Values declared here are merged with any generics defined in the Python test file's run_simulation() call. The Python kwarg takes precedence over project.yml values — this allows project-wide defaults with per-test overrides.

Precedence chain: project.yml < run_simulation() kwarg < CLI -g flag / $RR_SIM_GENERICS env var.

CLI override (highest priority):

rr sim test_cdc_bridge -g DEFAULT_BUSY_HIGH=1
rr sim test_fifo -g G_DATA_WIDTH=64 -g G_FIFO_DEPTH=16

Use simulation.generics for project-wide defaults (bus widths, clock frequencies, feature enables). Use -g on the CLI for quick variant testing without editing files.

linux

Embedded Linux build configuration. Controls U-Boot, Kernel, FSBL, and external user-space software fetch operations.

linux:
  board: zynq-zybo-z7             # Base board config for Xilinx makefiles
  device_tree: zynq-zybo-z7       # Explit injection for U-Boot device tree
  uboot_repo: https://github.com/my-fork/u-boot-xlnx.git  # Override Xilinx upstream
  kernel_repo: https://github.com/my-fork/linux-xlnx.git  # Override Xilinx upstream
  fsbl_repo: https://github.com/my-fork/embeddedsw.git    # Override Xilinx upstream
  kernel_config: config/kernel.cfg  # Config fragments to merge before build
  kernel_patch: config/patch.sh     # Bash script to execute before kernel config
  sw_repos:                         # Space-separated list of custom UI/App repos
    - https://github.com/my-org/custom-ui.git
    - https://github.com/my-org/video-server.git

paths

Directory layout overrides. All paths are relative to the project root. These fields control where rr ws update scans for files; they do not control which files are used for synthesis (that is sources.syn).

paths:
  sources: src                     # Single directory
  sources: [hw/rtl, vendor/routertl/src/units]  # Multiple directories
  simulation: sim
  constraints: xdc
  verification: verif

Scan behavior (rr ws update / make update-src):

When sources is a list, all directories are scanned and results are unioned — files from each directory are deduplicated against existing sources.syn entries before insertion.

paths.simulation ≠ simulation.test_dir. paths.simulation scans for RTL testbench wrappers (tb_*.vhd, tb_*.v, tb_*.sv) and populates sources.sim. simulation.test_dir is the directory for Python Cocotb test scripts (test_*.py), used by rr sim and hooks.pre_commit.tests: auto. These are different file types serving different purposes.

build_options

Synthesis tool versions and build behavior.

build_options:
  tool_version: "2024.1"           # Default version for all tools
  vivado_version: "2024.2"         # Override Vivado specifically
  radiant_version: "2023.2"        # Override Lattice Radiant
  quartus_version: "23.1"          # Override Intel Quartus
  quick_impl: true                 # Fast implementation (fewer timing iterations)
  edition: pro                     # Quartus edition override (pro/std)

build_options.generics

Override top-level VHDL generics or SystemVerilog parameters at synthesis time. Applies to the entity/module defined by project.top_module.

build_options:
  generics:
    DATA_WIDTH: 32
    FIFO_DEPTH: 1024
    ENABLE_DEBUG: false

Vendor-specific behaviour:

Version precedence:

tool_version sets ?= (weak) defaults for all three tools. A vendor-specific override like vivado_version emits := (unconditional), which takes priority.

Tool auto-discovery:

On native Linux, the SDK auto-discovers synthesis tools from PATH via check_env.py:

If the required tool is not found, make synthesis will fail with a clear error and instructions. The tool_version / vivado_version fields select among multiple installed versions.

Users can override tool paths explicitly:

makefile_overrides:
  VIVADO_PATH: /opt/Xilinx/Vivado/2024.2

features

Feature flags that enable or disable SDK capabilities.

features:
  regbank: true                    # Enable register bank generation

When regbank: true, make synthesis automatically runs parse_regbank and rom_info before project generation. Set to false for projects without a register bank.

sources

Explicit file lists for synthesis, simulation, constraints, and IP. These are the files tracked by the build system.

An empty list (sources.syn: []) means zero synthesis files — there is no implicit auto-discovery from paths.sources. Auto-discovery only happens when auto_sources: true is set.

sources:
  syn:
    - hw/rtl/pkg/system_config_pkg.vhd
    - hw/rtl/sniffer/uart/uart_sniffer.vhd
  sim:
    - hw/sim/tb_uart_sniffer.vhd
  xdc:
    - xdc/system_timing.xdc
    - xdc/system_pinout.xdc
  sdc:
    - constraints/timing.sdc
  ip:
    - ip/axi_dma/axi_dma.xci
  ips:
    - ip/uart_core/ip.yml
  ip_paths:
    - ip/vendor_ips
    - ~/vivado_ip_repo
  tcl: []

Auto-derived variables:

• PKG_FILES — Auto-detected from syn entries. Any .vhd/.vhdl file containing package <name> is is classified as a package and pre-compiled before linting.

Populating source lists:

make update-src   # Scan paths.sources for *.vhd, *.vhdl, *.v, *.sv
make update-sim   # Scan paths.simulation for tb_*.vhd, tb_*.v, tb_*.sv
make update-dc    # Scan paths.constraints for vendor-specific design constraints
make update-tcl   # Scan tcl/ for *.tcl
make update-ips   # Scan RTL-mode ip.yml manifests and update their sources
make update-all   # Run all five scans (includes --ip-update)

Vendor-aware constraint scan (make update-dc):

make update-xdc is a backward-compatible alias for make update-dc.

Stale entry pruning:

Each make update-* command prunes stale entries (files that no longer exist on disk) from the sources and hooks.pre_commit.exclude.lint sections automatically.

sources.libraries (Legacy Override)

Since v3.1, library membership is fully automatic via the dependency resolver's --discover-libs scan. The section below documents the manual override mechanism for edge cases only.

Custom VHDL library assignments. Files listed here are compiled under a named GHDL library (--work=<lib>) instead of the default work library.

sources:
  libraries:
    tich:
      - hw/rtl/pkg/arbiter_pkg.vhd
      - hw/rtl/pkg/axi_pkg.vhd
      - hw/rtl/pkg/system_config_pkg.vhd
      - hw/rtl/sniffer/infra/config_control.vhd

Behavior:

1. Serialized to .routertl_cache/libraries.json by project_manager.py.
2. Files are excluded from generic PRECOMPILE (Phase 1) to avoid cannot find resource library errors.
3. Each library is compiled into its own GHDL work directory (sim/work/<lib_name>/) with correct topological ordering.
4. -P sim/work/<lib_name> is added to LINT search paths automatically.

You almost certainly do not need this section. The Smart Linter auto-discovers library memberships via --discover-libs (scans for entity lib.X instantiations and use lib.pkg.all clauses). Manual entries here act as overrides for edge cases — e.g. generated files not in the source scan path. Auto-discovered and manual entries are merged (union). See LINTER_PIPELINE.md §4 for the full data flow.

dependencies

External git libraries. Cloned automatically on first build.

dependencies:
  xpm_vhdl:                        # Logical name (your choice)
    url: https://github.com/fransschreuder/xpm_vhdl.git
    fallback_url: https://github.com/djmazure/xpm_vhdl.git
    path: libs/xpm_vhdl            # Clone destination (relative to root)
    library: xpm                   # VHDL library name

Behavior:

1. On make update-config, the SDK checks if path exists.
2. If missing, it clones from url (then fallback_url on failure).
3. VHDL files inside the cloned repo are scanned, topologically sorted, and exported as XPM_FILES for the library: xpm case.

hooks

Git hooks and code generation hooks.

hooks.pre_commit

Pre-commit hook configuration. Install with make install-hooks.

hooks:
  pre_commit:
    enabled: true                  # Master switch for the hook
    lint: true                     # Run smart linter
    check_yaml: true               # Validate project.yml syntax
    lint_python: false             # Run ruff check (requires pyproject.toml)
    check_links: false             # Run documentation link checker
    check_docs: false              # Run documentation structure checker
    run_regression: false           # Run full regression (slow!)
    # Auto-discover all test_*.py in simulation.test_dir:
    tests: auto
    # Or use an explicit list:
    # tests:
    #   - test_uart_sniffer_smoke
    #   - test_uart_precommit
    exclude:                        # Exclusion lists
      lint:
        - vendor/legacy/old_file.vhd
      tests:
        - test_slow_integration
      docs:                          # Doc directories excluded from check_links
        - vendor/
    frozen_dirs:                     # Directories that must not have uncommitted changes
      - hw/rtl/generated

Test modes:

• tests: auto — Discovers all test_*.py files under simulation.test_dir via recursive glob (rglob("test_*.py")). Only git-tracked files are included (prevents WIP scripts from leaking into the hook). exclude.tests is applied before emitting. Each file is converted to a dotted module path (e.g., sim/cocotb/tests/units/test_edge.py → tests.units.test_edge).
• tests: [list] — Explicit module list. exclude.tests is applied by the hook script at runtime.
• tests: inherit — Inherits the test list from cicd.tests. Use this when CI/CD is the source of truth.

When both hooks.pre_commit.tests and cicd.tests are explicit lists with different contents, the SDK emits a divergence warning suggesting the use of inherit to stay DRY.

Test naming rules:

• Tests are module names, not file paths: test_uart_sniffer, not hw/sim/.../test_uart_sniffer.py
• Dotted notation for namespaced tests: tests.units.test_edge_counter

hooks.pre_build

Code generation hooks that run before make project / make synthesis.

hooks:
  pre_build:
    - name: sniffer-builder               # Human-readable label
      script: tools/sniffer-builder/sniffer_gather_gen.py   # Script path
      args:                                # Arguments
        - tools/sniffer-builder/config/sniffer_config.yml
        - --pkg-dir
        - hw/rtl/pkg
      expected_outputs:                    # Files that must exist after run
        - hw/rtl/pkg/sniffer_config_pkg.vhd
        - hw/rtl/sniffer/infra/sniffer_gather.vhd
      watch:                                # Source globs — re-run if newer than outputs
        - tools/sniffer-builder/**/*.py
        - tools/sniffer-builder/config/*.yml

Auto-gitignore behavior:

rr ws update-config automatically syncs all expected_outputs entries into .gitignore using an idempotent sentinel block. This prevents generated files from being committed. If hooks are removed or outputs change, the sentinel block is replaced (not duplicated). Paths containing .. or starting with / are silently skipped for safety. See SDK_BEHAVIOR_CONTRACT.md §1.4.

clean_before_run behavior:

When true (default), the parent directory of each expected_output is deleted before the hook runs — not just the file itself. This ensures no stale artifacts survive from a previous code generation. Safety: the project root itself is never deleted, and paths outside the project root are skipped with a warning.

cicd

CI/CD pipeline configuration. Used by make update-cicd.

cicd:
  platform: github                 # github, gitlab, or bitbucket
  tests:
    - tests.units.test_edge_counter
    - tests.units.test_lfsr

Test list inheritance:

• tests: inherit — Inherits the test list from hooks.pre_commit.tests. This is the recommended DRY pattern.
• tests: [list] — Explicit module list for CI.

Declare tests once in hooks.pre_commit.tests and set cicd.tests: inherit (or vice versa) to avoid duplicate lists drifting apart. A warning is emitted when both sections have explicit, differing lists.

vendor_overrides

Vendor-specific variables injected into the TCL environment.

vendor_overrides:
  xilinx:
    enable_pblocks: true           # Exported as: set g_enable_pblocks true
  lattice:
    synthesis_tool: lse            # Exported as: set g_synthesis_tool "lse"

Each key-value pair becomes a TCL variable: set g_<key> <value>.

makefile_overrides

Arbitrary Makefile variables injected into build_env.mk.

makefile_overrides:
  CUSTOM_FLAG: fast
  PARALLEL_JOBS: 4
  USE_OOC: true                    # Booleans lowercase automatically
  VIVADO_PATH: /opt/Xilinx/Vivado/2024.2  # Custom tool path

Each entry becomes a := assignment in build_env.mk:

CUSTOM_FLAG := fast
PARALLEL_JOBS := 4
USE_OOC := true
VIVADO_PATH := /opt/Xilinx/Vivado/2024.2

system_config

Path to a system-level YAML configuration (e.g., for sniffer/gather generation).

system_config: tools/sniffer-builder/config/sniffer_config.yml

Exported as CONFIG_YAML ?= $(ROOT_DIR)/<path> in build_env.mk.

auto_sources

Enable automatic dependency resolution from the top module.

auto_sources: true

Behavior:

1. The resolver crawls from project.top_module using the DependencyResolver.
2. Resolved files are appended to sources.syn — they do not replace existing entries. Duplicates are skipped.
3. Results are cached in .routertl_cache/dependencies.json, keyed by top_module. Subsequent runs reuse the cache (no timestamp invalidation).
4. If sources.syn does not exist, it is created as an empty list first.

This is an advanced feature. For most projects, explicit source lists populated via rr ws update --src are simpler and more predictable.

The auto-sources resolver uses paths.sources for its search directories. If paths.sources is not set, it falls back to src/.

linux

Embedded Linux build configuration. All keys are optional — they are only relevant for SoC projects that target routertl linux build.

linux:
  board: zybo                          # Board identifier
  target: zynq-7000                    # CPU target (from supported_targets.yml)
  device_tree: zynq-zybo.dtb           # Device tree filename
  uboot_repo: https://...              # Custom U-Boot repository
  kernel_repo: https://...             # Custom Linux Kernel repository
  fsbl_repo: https://...               # Custom embeddedsw fork (for FSBL)
  dtg_repo: https://...                # Custom Device Tree Generator fork
  boot_script: linux/boot.txt          # U-Boot boot script source (triggers boot.scr generation)
  kernel_config: linux/kernel.cfg      # Kernel config fragment
  kernel_patch: linux/patch.sh         # Kernel patch script
  sw_repos:                            # Additional software repositories to clone
    - https://github.com/org/repo.git

environment

Machine-specific environment variables injected into .venv/bin/activate. Keeps per-machine paths (license files, tool roots) out of shell profiles.

environment:
  LM_LICENSE_FILE: ~/Downloads/LR-291374_License.dat
  QUARTUS_ROOTDIR: /opt/altera_std

Behavior:

• rr ws install, rr ws update-config, and rr ws repair-venv all call the injection helper.
• Variables are written inside a sentinel block in .venv/bin/activate:

  # --- RouteRTL project environment ---
  export LM_LICENSE_FILE="$HOME/Downloads/LR-291374_License.dat"
  export QUARTUS_ROOTDIR="/opt/altera_std"
  # --- end RouteRTL project environment ---
  

• The sentinel block is idempotent — repeated runs replace the existing block, never duplicate it.
• ~ in values is expanded to $HOME for portability.
• Removing the environment: key from project.yml cleans the sentinel block from .venv/bin/activate on the next update-config.

includes

Import other YAML fragments. Allows splitting configuration across files.

includes:
  - config/hardware.yml
  - config/sources.yml

Merge semantics:

Processing order:

1. Includes are loaded depth-first (recursive).
2. All included configs are merged into a combined dict first.
3. The parent file's own config is then merged on top, giving it final say.

Safety:

• Cycle detection: Tracks visited absolute paths; circular includes are skipped with a warning.
• Max depth: 10 levels (hardcoded). Exceeding this emits a warning and stops recursion.
• Missing file: Prints a warning and returns an empty dict (non-fatal).
• Invalid YAML: Prints a parse error and returns an empty dict.
• Both absolute and relative paths are supported. Relative paths are resolved relative to the including file's directory.

tcl_hooks

Custom TCL scripts sourced during FPGA build stages.

tcl_hooks:
  gen_project:                              # Sourced during project generation
    - tcl/custom/my_block_design.tcl
    - tcl/custom/my_ip_config.tcl
  synthesis:                                # Sourced after project_open, before synthesis
    - tcl/project_options.tcl
  implementation:                           # Sourced after project_open, before fitter
    - tcl/project_options.tcl
    - tcl/impl_settings.tcl
  bitstream:                                # Sourced after project_open, before assembler
    - tcl/project_options.tcl

Each hook list is exported as a TCL list variable in build_env.tcl. The stage scripts iterate over the list after project_open and source each file. Missing files emit a warning but do not abort the build.

Use per-stage hooks to re-apply project_options.tcl settings that may be lost from stale QSF files (e.g., after a Quartus GUI session). This prevents fitter OOM crashes caused by OPTIMIZATION_MODE reverting to defaults on large devices (Arria 10, Stratix 10).

branding

White-label the CLI with custom names. Affects binary alias, help text, version output, and shell completion.

branding:
  cli_name: myrtl             # Binary alias (symlinked in .venv/bin/)
  display_name: My RTL SDK    # Shown in --help and --version panels

Symlink behavior:

• Created by rr init during venv setup (_create_branded_symlink()).
• Existing symlinks are replaced silently.
• No-op if cli_name is routertl (the default) or unset.
• The symlink is relative within .venv/bin/ for portability.

The rr shortcut alias is always created regardless of branding. Both rr and the branded name point to the same routertl entry point.

Full Example

# RouteRTL Project Configuration

project:
  name: my_soc_project
  top_module: my_soc_top
  top_sim: tb_my_soc_top

hardware:
  vendor: xilinx
  part: "xc7z020clg400-1"
  family: zynq
  language: vhdl
  platform: default
  tool_path: /opt/Xilinx/Vivado

linux:
  board: zybo
  sw_repos:
    - https://github.com/my-org/my-app.git

simulation:
  test_dir: hw/sim/cocotb/tests
  simulator: nvc
  waves:
    formats: [fst]
    output_dir: hw/sim/waves
  logs:
    output_dir: hw/sim/logs

paths:
  sources: [hw/rtl, vendor/routertl/src/units]
  simulation: hw/sim
  constraints: hw/xdc
  verification: hw/verif

build_options:
  tool_version: "2024.1"
  edition: pro

features:
  regbank: true

branding:
  cli_name: myrtl
  display_name: My RTL SDK

sources:
  syn:
    - hw/rtl/pkg/system_config_pkg.vhd
    - hw/rtl/sniffer/uart/uart_sniffer.vhd
  sim: []
  xdc: []

environment:
  LM_LICENSE_FILE: ~/Downloads/LR-291374_License.dat
  QUARTUS_ROOTDIR: /opt/altera_std

dependencies:
  xpm_vhdl:
    url: https://github.com/fransschreuder/xpm_vhdl.git
    fallback_url: https://github.com/djmazure/xpm_vhdl.git
    path: libs/xpm_vhdl
    library: xpm

hooks:
  pre_commit:
    enabled: true
    lint: true
    check_yaml: true
    lint_python: false
    check_links: false
    tests:
      - test_uart_sniffer_smoke
      - test_uart_precommit
    exclude:
      lint:
        - hw/rtl/sniffer/infra/sniffer_gather.vhd
      tests: []
    frozen_dirs:
      - hw/rtl/generated

  pre_build:
    - name: sniffer-builder
      script: tools/sniffer-builder/sniffer_gather_gen.py
      args:
        - tools/sniffer-builder/config/sniffer_config.yml
        - --pkg-dir
        - hw/rtl/pkg
      expected_outputs:
        - hw/rtl/pkg/sniffer_config_pkg.vhd

cicd:
  platform: github
  tests:
    - tests.units.test_edge_counter
    - tests.units.test_lfsr