Metadata-Version: 2.4
Name: routertl
Version: 3.8.1
Summary: FPGA build system with 2,000+ IP package manager. 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: Changelog, https://github.com/djmazure/routertl/blob/main/CHANGELOG.md
Project-URL: Source, https://github.com/djmazure/routertl
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: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE-MIT
License-File: LICENSE-PROPRIETARY
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: docker>=7.0.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.0
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">
  <strong>RouteRTL</strong><br>
  <em>The FPGA build system that reads your HDL and figures it out.</em>
</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-2000%2B%20IPs-brightgreen.svg" alt="Registry"></a>
  <a href="LICENSE-MIT"><img src="https://img.shields.io/badge/shell-MIT-green.svg" alt="MIT License"></a>
  <a href="LICENSE-PROPRIETARY"><img src="https://img.shields.io/badge/core-PolyForm%20Shield-blue.svg" alt="PolyForm Shield"></a>
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+"></a>
  <a href="https://github.com/cocotb/cocotb"><img src="https://img.shields.io/badge/sim-cocotb%202.0-blueviolet.svg" alt="Cocotb 2.0"></a>
</p>

---

```bash
pip install routertl
```

**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. No manual file lists. No compilation order. No "works on my machine."

## Install an IP, See It Work

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

## 2,000+ IP Blocks. Cross-Language Dependency Resolution.

```bash
rr pkg search ethernet                    # browse the catalog
rr pkg add alexforencich/eth_arb_mux      # Verilog — deps auto-expanded
rr pkg add grlib/greth                    # VHDL — library deps auto-resolved
rr pkg add openhwgroup/cva6              # SystemVerilog — full SoC
```

The registry knows what every package **provides** and what it **needs** — both VHDL libraries and Verilog modules. 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**, **GRLIB** (LEON/NOEL-V), **alexforencich** (verilog-ethernet, verilog-axi), **OpenHW Group** (CVA6/CORE-V), **VUnit**, **Enclustra**, and more. Pinned by commit SHA in a lock file.

## What You Get

| | |
|:--|:--|
| **IP Package Manager** | 2,000+ blocks, cross-language dependency graphs, lock files, `rr pkg search/add/update` |
| **Auto-Discovery** | Point at a source tree — VHDL, Verilog, SystemVerilog hierarchy resolved automatically |
| **Multi-Vendor Synthesis** | Vivado, Quartus (Pro/Standard), Radiant, Libero — change one word in `project.yml` |
| **Cocotb 2.0+ Simulation** | `rr sim`, `rr testgen`, `rr watch` — NVC, GHDL, Verilator, Icarus, QuestaSim |
| **Protocol Drivers** | UART, SPI, I2C, QSPI, AXI4-Lite, AXI4, Avalon-MM — included, zero extra deps |
| **Smart Linting** | Hierarchy-aware, incremental, multi-pass — `rr lint` just works |
| **Code Generation** | Bus bridges (AXI/Avalon/Native), register banks (VHDL + C headers + HTML docs) |
| **Pre-Commit Gates** | Lint + simulate + YAML check on every commit |
| **Docker EDA Provisioning** | `rr docker install vivado` — headless vendor tool setup, same environment everywhere |

## Battle-Tested

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

- **[open-logic](https://github.com/open-logic/open-logic)** — 77 entities, 4 IP areas, flat multi-root library. 77/77 files resolved, 0 violations.
- **[NEORV32](https://github.com/stnolting/neorv32)** — 56 entities, deep monolithic SoC, complex generics. 0 violations.

## The CLI

```bash
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 migrate                    # import existing Vivado/Quartus 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

```bash
pip install routertl
```

> For platform-specific instructions (Linux, WSL2, macOS), see the **[Installation Guide](docs/guides/INSTALLATION.md)**.

### 2. Initialize

```bash
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 and Quartus projects. Or run `rr init` inside an existing repo and adjust the `paths:` block.

### 3. Add IP and Build

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

```python
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](docs/guides/FIRST_STEPS_TUTORIAL.md) |
> | Write a simulation | [Cocotb Quickstart](docs/guides/COCOTB_QUICKSTART.md) |
> | Use a protocol driver | [Driver Cookbook](docs/guides/DRIVER_COOKBOOK.md) |
> | Understand project.yml | [project.yml Reference](docs/reference/PROJECT_YML_REFERENCE.md) |
> | Migrate an existing project | [Existing Project Migration](docs/guides/EXISTING_PROJECT_MIGRATION.md) |
> | Fix an error | [Troubleshooting](docs/reference/TROUBLESHOOTING.md) |
> | Browse all docs | [Documentation Index](docs/README.md) |

## Prerequisites

| Tool | Required | Notes |
|:-----|:---------|:------|
| Python 3.10+ | Yes | CLI and simulation framework |
| Git | Yes | Version control and dependency tracking |
| NVC | Recommended | VHDL simulator for Cocotb 2.0+ ([`.deb`](https://github.com/nickg/nvc/releases/latest)) |
| GHDL | Recommended | VHDL analyzer (fast linting) |
| Vendor tools | Optional | Vivado / Quartus / Radiant / Libero — or `rr docker install` |

## Acknowledgments

RouteRTL stands on the shoulders of outstanding open-source projects:
[NVC](https://github.com/nickg/nvc) · [GHDL](https://github.com/ghdl/ghdl) · [Cocotb](https://github.com/cocotb/cocotb) · [xpm_vhdl](https://github.com/fransschreuder/xpm_vhdl) · [Verilator](https://github.com/verilator/verilator) · [Icarus Verilog](https://github.com/steveicarus/iverilog) · [Rich](https://github.com/Textualize/rich) · [Jinja2](https://github.com/pallets/jinja2)

## Contributing

The best way to contribute is to **use RouteRTL and tell us what breaks** — open an issue, suggest a feature, or share how you're using it. Run `rr doctor` and include the output if reporting a bug.

See [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## Contact

Built and maintained by **Daniel J. Mazure** — [routertl.dev](https://www.routertl.dev)

## Licensing

RouteRTL uses a **dual-license** model:

| Component | License | You can... |
|:----------|:--------|:-----------|
| CLI, build system, cocotb drivers, hooks, docs | [MIT](LICENSE-MIT) | Use, modify, redistribute — no restrictions |
| Compiled core (`routertl_core/*.so`) | [PolyForm Shield 1.0.0](LICENSE-PROPRIETARY) | Use for any purpose **except** building a competing product |

<details>
<summary><strong>Licensing FAQ</strong></summary>

| Question | Answer |
|:---------|:-------|
| Can I use RouteRTL commercially? | **Yes** — use it to build, simulate, and ship your FPGA products without restriction. |
| Can I modify the CLI or build system? | **Yes** — they're MIT-licensed. Fork, extend, contribute PRs — all welcome. |
| Can I decompile the `.so` modules? | **No** — that violates the PolyForm Shield license. |
| Can I redistribute the PyPI wheel? | **Yes** — as-is, per standard PyPI terms. |
| What counts as "competing"? | Building and distributing an FPGA SDK that substitutes for RouteRTL. Using RouteRTL to build *your own product* is **not** competing. |

</details>

Copyright 2026 Daniel J. Mazure
