Docker Workflow Guide

Run EDA tools (Vivado, Quartus, Questa, etc.) inside Docker containers without installing them on your host machine. RouteRTL manages the container lifecycle — build, shell, run, and uninstall.

Prerequisites

• Docker Desktop (Windows/macOS) or Docker Engine (Linux)
• WSL2 (Windows only) — Docker Desktop must have WSL integration enabled: Docker Desktop → Settings → Resources → WSL Integration → enable your distro
• RouteRTL installed: pip install routertl
• EDA installer downloaded from the vendor website (Vivado, Quartus, etc.)

Important: RouteRTL does NOT download EDA tools for you. You must provide your own installer (.tar.gz, .bin, or extracted directory). These are proprietary tools that require vendor licenses.

Quick Start

1. Configure your environment

rr docker setup --target vivado

The wizard prompts for:

• Installer path — directory containing your Vivado .tar.gz
• Install directory — where to install (optional, uses Docker volume by default)

This writes a .env file that Docker Compose reads automatically.

2. Build the Docker image

rr docker install vivado

This builds two images:

1. sim (base) — GHDL, NVC, Verilator, cocotb, Python tools (~15 min)
2. vivado — adds Vivado installation on first shell (~30-60 min)

First time? The base image pull may fail on WSL2 with SSL errors. If so, run docker pull ubuntu:22.04 first to warm the connection.

3. Enter the container

rr docker shell vivado

On first launch, Vivado installs from your mounted installer into a persistent Docker volume. Subsequent launches are instant.

You land in /home/vivado/work/ — your project directory, mounted from the host. All changes are reflected on both sides.

4. Work inside the container

# Everything works as on the host
rr doctor              # Check tools
rr lint                # Lint your design
rr synth run           # Synthesize with Vivado
rr sim test_my_module  # Simulate with NVC

5. Exit

exit

Your project files persist (host-mounted). The Vivado installation persists in the Docker volume.

Available Environments

Managing Images and Volumes

# Check what's installed
rr docker status

# Remove a specific environment
rr docker uninstall vivado          # Remove volume + image
rr docker uninstall vivado --image  # Image only (keep installation)

# Run a single command (no interactive shell)
rr docker run sim "rr lint"
rr docker run vivado "rr synth run"

Device Families

EDA installers let you choose which device families to install. Each family adds 5-10 GB. Edit the install config before building:

# Find the config
nano $(rr sdk-path)/sdk/infra/docker/install_config.vivado.txt

# Enable the families you need
Modules=Zynq UltraScale+ MPSoC:1,Zynq-7000:1,Artix-7:0

Then rebuild: rr docker install vivado

Troubleshooting

Docker pull fails (SSL errors on WSL2)

ERROR: failed to load metadata for docker.io/library/ubuntu:22.04

Fix: docker pull ubuntu:22.04 to warm the connection, then retry. RouteRTL 3.6.0+ does this automatically.

"Are you trying to mount a directory onto a file?"

The VIVADO_INSTALLER_PATH was not set. Run:

rr docker setup --target vivado

Vivado "not found" but it's installed

The installer may place Vivado at /tools/Xilinx instead of /opt/Xilinx. Inside the container:

source /tools/Xilinx/Vivado/2024.1/settings64.sh
vivado -version

RouteRTL 3.6.0+ auto-detects both paths.

Container starts Vivado install every time

The install check looks at /opt/Xilinx but Vivado is at /tools/Xilinx. Fixed in 3.6.0. On 3.5.0, use docker exec -it routertl-dev bash to re-enter without triggering the installer.

pip install fails inside container (root warning)

Normal — the container runs as root for the EDA installer. The warning is cosmetic and doesn't affect functionality.