routertl 4.8.1

RouteRTL
The FPGA build system that reads your HDL and figures it out.

python3 -m venv .venv
source .venv/bin/activate
pip install routertl

PEP 668 note: the venv step above is not optional on Ubuntu 24.04+, Debian 12+, or any externally-managed Python — a bare pip install routertl there fails with error: externally-managed-environment. Creating and activating the venv first sidesteps it entirely. If you want a global CLI instead of a per-project venv, pipx install routertl also works. Do not reach for pip install --break-system-packages — it installs into the OS-managed Python and can break system packages.

Python 3.14 note: routertl installs cleanly on Python 3.14, but rr sim (cocotb-backed simulation) is temporarily unavailable there — cocotb 2.0.x hardcodes a Python ≤3.13 limit in its build script. Use Python 3.10–3.13 for sim work; everything else (rr pkg, rr lint, registry, MCP server) works on 3.14. The conditional drops once cocotb 2.1 ships with 3.14 support upstream.

RouteRTL is a command-line FPGA SDK with a built-in IP package manager. Install a UART core, an AXI interconnect, or a full RISC-V SoC — dependencies are resolved automatically from the source code, so you never maintain file lists or compile order by hand, and a build that passes on one machine passes on every machine.

Viewing waveforms? RouteRTL projects open directly in RouteWave, the companion waveform viewer. Run rr routewave to inspect VCD/FST captures from rr sim without leaving the SDK workflow.

Install an IP, See It Work

rr init --non-interactive --no-venv
rr pkg add open-logic/olo_intf_uart
rr lint olo_intf_uart

  + open-logic/olo_intf_uart ^4.4.1
  Resolving 1 package(s) from https://registry.routertl.dev
    open-logic/olo_intf_uart: ^4.4.1 -> 4.4.1
  Written ip.lock (1 packages)

  Lint passed  (ghdl)

RouteRTL cloned the package, resolved 8 transitive VHDL dependencies, compiled them in the correct library order, and linted — all from one command.

rr hierarchy --forest

  olo_intf_uart  (olo_intf_uart.vhd, 8 files)
  |-- olo_base_strobe_gen
  |   +-- [1 pkgs: olo_base_pkg_math]
  |-- olo_intf_sync
  |   +-- [1 pkgs: olo_base_pkg_attribute]
  +-- [3 pkgs: olo_base_pkg_logic, olo_base_pkg_math, olo_base_pkg_string]

IP Registry. Cross-Language Dependency Resolution.

rr pkg search ethernet                           # browse the catalog
rr pkg add fpganinja/taxi::taxi_eth_mac_1g       # Verilog — single module from a repo
rr pkg add open-logic/olo_base_fifo_async        # VHDL — library deps auto-resolved
rr pkg add openhwgroup/cva6                      # SystemVerilog — full RISC-V SoC

The registry detects licenses (MIT, GPL, CERN-OHL) and classifies each package as permissive, weak, or strong copyleft. Every package is scanned with role computation — tops, components, and primitives classified automatically.

When you install a package, RouteRTL:

1. Queries the registry for dependency metadata
2. Resolves missing libraries and modules to their provider packages
3. Auto-installs transitive dependencies
4. Compiles everything in the correct order
5. Lints and reports results

Pre-packaged from open-logic, fpganinja (Corundum, Taxi Ethernet/AXI/PCIe), OpenHW Group (CVA6/CORE-V), PULP Platform (AXI, common cells), Analog Devices, VUnit, Enclustra, NEORV32, and more. Pinned by commit SHA in a lock file.

What You Get

Validated on Real Codebases

Validated against real-world codebases with zero configuration beyond rr init:

• open-logic — 69 IPs, flat multi-root VHDL library. All files resolved, 0 violations.
• NEORV32 — 56 entities, deep monolithic SoC, complex generics. 0 violations.

The CLI

rr init                       # scaffold a project
rr hierarchy --forest         # design hierarchy
rr lint                       # smart lint (GHDL + Verilator)
rr sim test_my_module         # simulate (cocotb 2.0+)
rr testgen edge_counter       # generate test boilerplate
rr watch                      # re-run on save
rr synth run my_top           # synthesize
rr implementation             # place & route
rr bitstream                  # generate bitstream
rr report                     # utilization & timing
rr deps graph                 # dependency visualization
rr pkg search / add / update  # IP package manager
rr rules check                # match design rules to current toolchain
rr ref list / install         # scaffold from a reference design
rr migrate                    # import existing Vivado projects
rr docker install vivado      # headless EDA provisioning
rr doctor                     # toolchain health check

Both routertl and rr work as entry points.

Quick Start

1. Install

python3 -m venv .venv
source .venv/bin/activate
pip install routertl

For platform-specific instructions (Linux, WSL2, macOS), see the Installation Guide.

2. Initialize

rr init --name my_project --vendor xilinx --part xc7z020clg400-1

Creates project.yml, directory structure, virtual environment, and pre-commit hooks.

Existing project? rr migrate imports Vivado projects (Quartus support coming soon). Or run rr init inside an existing repo and adjust the paths: block.

3. Add IP and Build

rr pkg add open-logic/olo_base_fifo_sync  # install with deps
rr lint                                    # verify everything compiles
rr sim test_my_module                      # run simulation
rr synth run my_top                        # synthesize

Simulation API

from routertl.sim import Tb, run_simulation, UartSource, SignalCollector

@cocotb.test()
async def test_my_module(dut):
    tb = Tb(dut)
    await tb.start_clock()
    await tb.reset()
    # Your test logic here

Native protocol drivers included: AXI4-Lite, AXI4, Avalon-MM, Native Memory, UART, SPI, I2C — with passive monitors and bridge scoreboards.

Who Is This For?

• FPGA engineers who want reproducible, scriptable builds instead of vendor GUI projects
• Teams integrating FPGA into CI/CD pipelines
• Multi-vendor shops targeting Xilinx, Intel/Altera, Lattice, and Microchip from one project.yml

Documentation

I want to...

Goal	Link
Create my first project	First Steps Tutorial
Write a simulation	Cocotb Quickstart
Use a protocol driver	Driver Cookbook
Understand project.yml	project.yml Reference
Migrate an existing project	Existing Project Migration
Fix an error	Troubleshooting
Browse all docs	Documentation Index

Prerequisites

Acknowledgments

RouteRTL builds on the work of several outstanding open-source projects. We gratefully acknowledge:

RouteRTL would not be possible without these projects and their maintainers.

Contributing

The best way to contribute is to use RouteRTL and tell us what breaks. To report a bug, suggest a feature, or share how you're using it, email support@routertl.dev. Include the output of rr doctor when reporting issues.

See CONTRIBUTING.md for details.

Contact

Built and maintained by Daniel J. Mazure — routertl.dev · support@routertl.dev

Licensing

RouteRTL uses a dual-license model:

Copyright 2026 Daniel J. Mazure