Metadata-Version: 2.4
Name: routertl
Version: 5.1.0
Summary: The FPGA CLI ecosystem. IP registry with license detection, cross-language dependency resolution, smart linting, multi-vendor synthesis — one pip install.
Author-email: "Daniel J. Mazure" <dasjimaz@gmail.com>
License: MIT AND LicenseRef-RouteRTL-Proprietary
Project-URL: Homepage, https://www.routertl.dev
Project-URL: Documentation, https://www.routertl.dev/docs
Project-URL: Issues, https://github.com/routertl/issues
Project-URL: Discord, https://discord.gg/HZgrsyZE
Keywords: fpga,vhdl,verilog,simulation,synthesis,cocotb,eda,rtl
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE-ACADEMIC
License-File: LICENSE-MIT
License-File: LICENSE-PROPRIETARY
License-File: NOTICE
Requires-Dist: click>=8.0.0
Requires-Dist: rich>=13.0
Requires-Dist: rich-click>=1.7.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: pathspec>=0.11.0
Requires-Dist: tomli>=1.1.0; python_version < "3.11"
Requires-Dist: cocotb>=2.1
Requires-Dist: cocotb-test>=0.3
Requires-Dist: msgpack>=1.0
Requires-Dist: jsonschema>=4.18
Requires-Dist: pyelftools>=0.31
Requires-Dist: packaging>=21.0
Provides-Extra: mcp
Requires-Dist: mcp<2.0.0,>=1.0.0; extra == "mcp"
Provides-Extra: docker
Requires-Dist: docker>=7.0.0; extra == "docker"
Provides-Extra: web
Requires-Dist: fastapi>=0.110; extra == "web"
Requires-Dist: uvicorn[standard]>=0.29; extra == "web"
Requires-Dist: bcrypt>=4.1; extra == "web"
Requires-Dist: pyjwt>=2.8; extra == "web"
Requires-Dist: pydantic[email]>=2.7; extra == "web"
Requires-Dist: cryptography>=3.4; extra == "web"
Provides-Extra: pdf
Requires-Dist: reportlab>=4.0; extra == "pdf"
Provides-Extra: structural
Requires-Dist: pyslang>=11.0; extra == "structural"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pyslang>=11.0; extra == "test"
Requires-Dist: cryptography>=3.4; extra == "test"
Provides-Extra: docs
Requires-Dist: mkdocs<2.0,>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings>=1.0; extra == "docs"
Requires-Dist: mkdocstrings-python>=2.0; extra == "docs"
Dynamic: license-file

<p align="center">
  <h1 align="center">RouteRTL</h1>
  <p align="center">Command-line SDK for FPGA projects: simulation, linting, IP packages and vendor builds from one <code>project.yml</code>.</p>
</p>

<p align="center">
  <a href="https://www.routertl.dev"><img src="https://img.shields.io/badge/web-routertl.dev-orange.svg" alt="Website"></a>
  <a href="https://pypi.org/project/routertl/"><img src="https://img.shields.io/pypi/v/routertl.svg" alt="PyPI"></a>
  <a href="https://registry.routertl.dev/health/dashboard"><img src="https://img.shields.io/badge/registry-live-brightgreen.svg" alt="Registry"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT%20%2B%20RouteRTL%20Core-blue.svg" alt="License"></a>
  <img src="https://img.shields.io/badge/python-3.10--3.14-blue.svg" alt="Python 3.10-3.14">
  <img src="https://img.shields.io/badge/sim-cocotb%202.1-green.svg" alt="cocotb 2.1">
</p>

---

RouteRTL is a command-line SDK for FPGA development. A project is described in
`project.yml`. RouteRTL reads the HDL sources, works out the compile order
from the code, and drives the simulators, linters and vendor tools. The CLI
command is `rr`.

Main functions:

- Source discovery and dependency resolution for VHDL, Verilog and SystemVerilog.
  File lists and compile order are derived from the sources.
- An IP package manager (`rr pkg`) backed by a public registry. Package
  dependencies are resolved across languages, and each package carries a
  license classification.
- cocotb 2.1+ simulation (`rr sim run`) with shipped bus-functional models.
- Linting (`rr lint`) with configurable profiles.
- Synthesis, implementation and bitstream generation for AMD/Xilinx, Altera,
  Lattice and Microchip devices, plus an open-source Yosys/nextpnr flow.
- An MCP server and agent skills for use with AI coding agents.

## Installation

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

Release wheels are built for Python 3.10 to 3.14.

On Ubuntu 24.04+, Debian 12+ and other systems with an externally managed
Python, a plain `pip install routertl` outside a virtual environment fails
with `error: externally-managed-environment`. Use the virtual environment
above, or `pipx install routertl` for a global CLI. Not recommended:
`--break-system-packages`. It installs into the system Python and can
break system packages.

Optional extras: `routertl[mcp]` (MCP server), `routertl[docker]` (Docker
tool images) and `routertl[web]` (web services). The base install does not
include them.

Platform notes for Linux, WSL2 and macOS are in the
[Installation Guide](docs/guides/INSTALLATION.md).

## Quick start

This example uses the `uart_loopback` template. It installs the
`open-logic/olo_intf_uart` package from the registry, lints the design and
runs two cocotb tests on NVC.

```bash
mkdir my_uart && cd my_uart
rr init --template uart_loopback --name my_uart
rr lint
rr sim run
```

`rr init --template` creates the project in the current directory. The
template declares the UART package, so `rr init` installs it. To add a
package to any project, run `rr pkg add <vendor>/<package>`.

`rr init --list-templates` lists the other templates. `first_success` uses
only open-source tools (Icarus Verilog and Yosys) and needs no vendor license.

To create an empty project for a specific device:

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

To import an existing Vivado (`.xpr`) or Quartus (`.qpf` / `.qsf`) project, use
`rr migrate run <project>`.

## IP packages

```bash
rr pkg search ethernet
rr pkg add open-logic/olo_base_fifo_async
rr pkg add fpganinja/taxi::taxi_eth_mac_1g
rr hierarchy --forest
```

`rr pkg add` resolves the package's HDL dependencies, including dependencies
between VHDL and Verilog sources. `rr hierarchy --forest` prints the resolved
design hierarchy. The registry is at
[registry.routertl.dev](https://registry.routertl.dev/health/dashboard).

## Commands

| Area | Commands |
|:-----|:---------|
| Project | `rr init`, `rr migrate run`, `rr status`, `rr doctor`, `rr hierarchy` |
| Packages | `rr pkg search`, `rr pkg add`, `rr pkg update`, `rr deps graph` |
| Lint | `rr lint` |
| Simulation | `rr sim run`, `rr sim list`, `rr sim scaffold`, `rr testgen`, `rr watch` |
| Build | `rr synth run`, `rr implementation run`, `rr bitstream run`, `rr report` |
| Hardware | `rr program run` |
| Tools | `rr eda install <tool>`, `rr docker install <env>` |
| Waveforms | `rr routewave` |
| AI agents | `rr mcp install`, `rr skills install`, `rr skills search` |

`rr --help --all` lists every command. `rr help <command>` shows the manual
page for one command.

## Supported tools

| Function | Tools |
|:---------|:------|
| Simulation | NVC, GHDL, Verilator, Icarus Verilog. Questa, Riviera-PRO, Active-HDL and Xcelium when installed. |
| Synthesis and implementation | Vivado, Quartus Pro and Standard, Lattice Radiant and Diamond, Microchip Libero, Yosys with nextpnr |
| Waveforms | [RouteWave](https://routewave.dev) (`rr routewave`), GTKWave |

`rr eda install` builds NVC, GHDL, Verilator, Icarus Verilog and Yosys from
pinned sources. `rr docker install` provides container images for vendor
tools.

## Simulation API

```python
import cocotb
from routertl.sim import Tb

@cocotb.test()
async def test_my_module(dut):
    tb = Tb(dut)
    await tb.start_clock()
    await tb.reset()
```

Each test file ends with a call to `run_simulation(...)` and runs with
`rr sim run <test>`. `rr sim bfms` lists the shipped bus-functional models.
They include AXI4, AXI4-Lite, AXI4-Stream, APB, Avalon-MM, Avalon-ST,
Wishbone, UART, SPI, I2C and GMII.

## Use with AI agents

RouteRTL includes an MCP server (`rr_*` tools for schema lookup, lint,
simulation and diagnosis) and a set of agent skills. In the project
directory:

<!-- rr-docs-step -->
```bash
pip install 'routertl[mcp]'   # MCP server dependencies (not in the base install)
rr mcp install                # registers the routertl server in ./.mcp.json
rr skills install             # copies the agent skills into ./.claude/skills
```

`rr skills install --scope user` installs the skills for all projects.
`rr skills search <words>` finds a skill. Details are in
[MCP Server](docs/guides/MCP_SERVER.md).

## Documentation

| Topic | Link |
|:------|:-----|
| First project | [First Steps Tutorial](docs/guides/FIRST_STEPS_TUTORIAL.md) |
| Writing simulations | [Cocotb Quickstart](docs/guides/COCOTB_QUICKSTART.md) |
| Protocol drivers | [Driver Cookbook](docs/guides/DRIVER_COOKBOOK.md) |
| `project.yml` fields | [project.yml Reference](docs/reference/PROJECT_YML_REFERENCE.md) |
| Existing projects | [Existing Project Migration](docs/guides/EXISTING_PROJECT_MIGRATION.md) |
| Errors | [Troubleshooting](docs/reference/TROUBLESHOOTING.md) |
| All documents | [Documentation Index](docs/README.md) |

## Requirements

| Tool | Required | Notes |
|:-----|:---------|:------|
| Python 3.10 to 3.14 | Yes | CLI and simulation framework |
| Git | Yes | Version control and dependency tracking |
| NVC | Recommended | Default VHDL simulator. `rr eda install nvc` builds the pinned release. Ubuntu 24.04 has no `nvc` apt package. The release [`.deb`](https://github.com/nickg/nvc/releases/latest) also works. |
| GHDL >= 6.0 | Recommended | VHDL analysis for `rr lint`. `rr eda install ghdl` builds the pinned release. Ubuntu 24.04 apt provides 4.1.0, which `rr lint` does not accept. |
| Vendor tools | Optional | Vivado, Quartus, Radiant, Diamond or Libero, installed locally or with `rr docker install` |

## Acknowledgments

RouteRTL uses the following open-source projects:

| Project | Use in RouteRTL |
|:--------|:----------------|
| [NVC](https://github.com/nickg/nvc) | Default VHDL simulator |
| [GHDL](https://github.com/ghdl/ghdl) | VHDL analysis, linting and simulation |
| [cocotb](https://github.com/cocotb/cocotb) | Python verification framework used by `rr sim` |
| [Verilator](https://github.com/verilator/verilator) | Verilog/SystemVerilog simulation and linting |
| [Icarus Verilog](https://github.com/steveicarus/iverilog) | Verilog simulation |
| [xpm_vhdl](https://github.com/fransschreuder/xpm_vhdl) | VHDL models of Xilinx XPM macros |
| [Rich](https://github.com/Textualize/rich) | Terminal output |
| [Jinja2](https://github.com/pallets/jinja2) | Code generation templates |

## Support

Bug reports and feature requests: support@routertl.dev. Please include the
output of `rr doctor`. See [CONTRIBUTING.md](CONTRIBUTING.md) for
contributions.

RouteRTL is developed and maintained by Daniel J. Mazure
([routertl.dev](https://www.routertl.dev)).

## Licensing

RouteRTL is distributed under two licenses:

| Component | License | Terms |
|:----------|:--------|:------|
| CLI, build system, cocotb drivers, hooks, documentation, examples | [MIT](LICENSE-MIT) | Use, modification and redistribution with attribution |
| Compiled core (`routertl_core/*.so`) | [RouteRTL Core License 1.0](LICENSE-PROPRIETARY) | 30-day evaluation; then free for registered individuals; a commercial license for organizations of any size; no competing product |
| Compiled core, academic use | [RouteRTL Academic License 1.0](LICENSE-ACADEMIC) | Teaching and published non-commercial research at accredited institutions and non-profit public research institutes |

The RouteRTL Core License 1.0 applies from release 5.1.0. Releases before
5.1.0 remain under the PolyForm Shield License 1.0.0 they were published with.

<details>
<summary><strong>Licensing questions</strong></summary>

| Question | Answer |
|:---------|:-------|
| Evaluation? | Anyone may use RouteRTL, including its paid features, for 30 days. |
| Individual use after the evaluation? | Free of charge for an individual's own benefit, after free registration. Paid features need a seat. |
| Use in a company? | After the 30-day evaluation, an organization of any size needs a commercial license: a named seat per engineer or a company-wide Enterprise license. See [routertl.dev/pricing](https://routertl.dev/pricing). |
| Open-hardware project? | Free for a hardware design whose sources are published under an open license. This covers the project, not other use by the organization that runs it. |
| Commercial products? | Permitted under a commercial license. RouteRTL places no claim on the designs built with it. |
| Modification of the CLI or build system? | Permitted under the MIT license. |
| Working around the licence key check? | Not permitted under the RouteRTL Core License. |
| Redistribution of the PyPI wheel? | Permitted, unmodified. |
| What counts as competing? | Distributing an FPGA SDK that replaces RouteRTL. Using RouteRTL to build an FPGA product is not competing. |

</details>

Copyright 2024-2026 Daniel J. Mazure
