Integrating RouteRTL with an Existing Project
You already have a Vivado or Quartus project with RTL, constraints, and maybe some hand-written testbenches. This guide shows how to add RouteRTL without restructuring your project.
You don't have to adopt everything at once. Start with simulation and linting — they work alongside your existing vendor GUI. Add synthesis integration later when you're ready.
1. Install RouteRTL
pip install routertl
No project restructuring needed. RouteRTL installs as a CLI tool and Python library.
2. Initialize Inside Your Existing Repo
cd ~/my-existing-project
routertl init \
--name my_project \
--vendor xilinx \
--part xc7z020clg400-1 \
--language vhdl \
--src-dir hw/rtl \
--sim-dir hw/sim
Key flags for existing projects:
| Flag | Purpose |
|---|---|
--src-dir hw/rtl | Point at your existing RTL source directory |
--sim-dir hw/sim | Point at your existing testbench directory |
--language vhdl | Match your existing HDL language |
RouteRTL creates project.yml and a .venv/ in your repo root. It
does not move or rename any existing files.
3. Auto-Discover Your Source Files
source .venv/bin/activate
routertl workspace update --all
This scans your source, simulation, and constraint directories and
populates project.yml with every file it finds. No manual file-list
editing.
Verify the result:
routertl info --forest # Show all detected design hierarchies
routertl sources # List all tracked files by category
4. Start Using RouteRTL (Alongside Vivado/Quartus)
Linting (no vendor tools required)
routertl lint # Lint all hierarchies
routertl lint my_top_module # Lint a specific top-level
Simulation (requires NVC or GHDL)
If you already have cocotb testbenches:
routertl sim test_my_module # Run a specific test
routertl sim --all # Run all discovered tests
If you don't have cocotb tests yet, auto-generate stubs:
routertl testgen # Generate test skeletons for all entities
routertl sim test_my_entity # Run the generated test
Environment Check
routertl doctor # What tools are installed and working?
5. Keeping Vivado/Quartus as Your Synthesis Tool
RouteRTL doesn't replace your vendor GUI — it enhances your workflow. A typical hybrid workflow looks like:
| Task | Tool |
|---|---|
| Edit RTL | Your editor of choice |
| Lint check | routertl lint |
| Run simulation | routertl sim |
| Open schematic | routertl schematic my_module |
| Synthesize | Vivado GUI or routertl synthesis |
| Timing analysis | Vivado GUI |
| Program FPGA | Vivado GUI |
When you're ready to move synthesis to the CLI:
routertl synthesis # Build bitstream from project.yml
6. Common Questions
Do I need to reorganize my directories?
No. Use --src-dir and --sim-dir during routertl init to point at
your existing layout. RouteRTL adapts to you, not the other way around.
Will RouteRTL modify my Vivado .xpr project?
No. RouteRTL creates its own project.yml and generates fresh TCL
scripts for synthesis. Your existing .xpr file is untouched.
Can I use both the Vivado GUI and RouteRTL CLI?
Yes. They operate on the same source files but maintain separate project metadata. Use the GUI for interactive tasks (timing analysis, floorplan) and the CLI for automation (linting, simulation, CI/CD).
My project uses Xilinx IP cores (.xci files). Will RouteRTL find them?
Yes. Run routertl workspace update --all and XCI files are detected
automatically and listed under sources.xci in project.yml.
Next Steps
- First Steps Tutorial — Guided walkthrough of the full RouteRTL workflow
- project.yml Reference — All configuration options
- Cocotb Quickstart — Writing testbenches with the SDK's simulation API