Migrating Existing Projects to RouteRTL

Already have a Vivado project? rr migrate converts it to a RouteRTL project.yml in minutes — no manual rewriting, no guesswork.

Overview

The migration toolset has two commands:

Migration is Tier 1 — it parses the .xpr XML directly. No Vivado installation required (except for block design export).

Quick Start

# 1. Point at your Vivado project
rr migrate run /path/to/my_design.xpr .

# 2. Review the generated config
cat targets/my_design.yml

# 3. Build with RouteRTL
rr lint
rr synth run

# 4. Verify the migration
rr migrate verify --reference /path/to/my_design.xpr

rr migrate run

rr migrate run <project_file> [output_dir]

Arguments

Options

What It Does

1. Parses the .xpr — extracts part, top module, sources, constraints, IP cores, and TCL hooks
2. Relocates external files — copies sources outside the project into hw/src/, hw/xdc/, or scripts/
3. Resolves IP repositories — copies IP cores into hw/ip/
4. Exports block designs — if Vivado is available, exports BD files as TCL scripts
5. Generates project.yml — complete configuration with all sources, constraints, and hooks
6. Scaffolds the project — creates Makefile, .gitignore, and build environment files
7. Writes a migration report — summary of what was migrated, what needs attention

Generated Files

my_design/
├── project.yml                              # Points to target config
├── Makefile                                 # SDK integration
├── .gitignore                               # Build artifact exclusions
├── hw/
│   ├── src/                                 # Relocated RTL sources
│   ├── xdc/                                 # Relocated constraints
│   └── ip/                                  # Relocated IP cores
├── scripts/                                 # TCL hooks
└── targets/
    ├── my_design.yml                        # Full project configuration
    └── my_design.migration_report.txt       # Detailed migration report

Missing File Resolution

If source files referenced in the .xpr can't be found, the migrator:

1. Auto-searches in concentric rings around the .xpr file
2. Searches any directories passed via --src-dirs
3. Prompts interactively for additional search paths

Vivado artifact directories (.cache, .gen, .runs, etc.) are automatically skipped.

Dry Run

Preview the migration without writing anything:

rr migrate run my_design.xpr . --dry-run

This parses the project, resolves files, and prints the full migration report — but creates no files on disk.

rr migrate verify

After migrating and building, verify that the results match:

rr migrate verify --reference <original_project> [--current <migrated_root>] [--json]

Options

Compared Metrics

Verdict

# Basic verification
rr migrate verify -r /path/to/original/vivado/project

# JSON output for CI pipelines
rr migrate verify -r /path/to/original -c . --json

Supported Formats

Block Designs

If the project contains Xilinx block designs (.bd files):

• Vivado available: auto-exports as TCL scripts and adds them as gen_project hooks
• Vivado not available: generates a TODO placeholder in project.yml — you can manually export from the Vivado GUI and use rr hook adapt <exported_bd.tcl>

Tips

• Always run --dry-run first to preview the migration
• Check the migration report for flagged issues (missing files, absolute paths, unsupported features)
• After migration, run rr doctor to verify your environment
• Use rr migrate verify to confirm build equivalence before switching workflows