From abb71244f17277306fec4df0561cfebc3aaeb9bf Mon Sep 17 00:00:00 2001 From: Divinesoumyadip Date: Sun, 22 Mar 2026 18:10:30 +0000 Subject: [PATCH 1/3] docs: add Windows Docker installation guide addressing common issues Signed-off-by: Divinesoumyadip --- docs/user/WindowsDocker.md | 149 +++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 docs/user/WindowsDocker.md diff --git a/docs/user/WindowsDocker.md b/docs/user/WindowsDocker.md new file mode 100644 index 0000000000..e258701285 --- /dev/null +++ b/docs/user/WindowsDocker.md @@ -0,0 +1,149 @@ +# Build OpenROAD on Windows Using Docker + +## Prerequisites + +* Windows 10 (version 2004+) or Windows 11 +* Docker Desktop (WSL2 backend enabled) +* At least 16GB RAM (8GB minimum usable) +* At least 50GB free disk space + + + +## Step 1 — Install and Configure Docker Desktop + +1. Install Docker Desktop with WSL 2 backend enabled +2. Configure resources: + + * Memory: ≥ 8GB + * CPUs: ≥ 4 +3. Enable WSL Integration for Ubuntu-22.04 + +Verify installation: + +``` +docker run hello-world +``` + + +## Step 2 — Avoid Timezone Prompt + +Run before any apt-get: + +``` +export DEBIAN_FRONTEND=noninteractive +export TZ=UTC + +apt-get update +apt-get install -y tzdata +``` + + +## Step 3 — Install Correct Yosys Version + +``` +wget https://github.com/YosysHQ/oss-cad-suite-build/releases/latest/download/oss-cad-suite-linux-x64.tgz + +tar -xzf oss-cad-suite-linux-x64.tgz + +echo 'export PATH="$(pwd)/oss-cad-suite/bin:$PATH"' >> ~/.bashrc +source ~/.bashrc + +yosys --version +``` + + + +## Step 4 — Fix Line Endings (CRLF Issue) + +Run before cloning: + +``` +git config --global core.autocrlf false +git config --global core.eol lf + +git clone --recursive https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts +``` + + + +## Step 5 — Copy Files into Docker + +Option A: + +``` +docker ps +docker cp C:\path\to\file :/tmp/ +``` + +Option B (recommended): + +``` +docker run -it -v //c/Users/YourName/OpenROAD-flow-scripts:/OpenROAD-flow-scripts ubuntu:22.04 +``` + +## Step 6 — Persist Environment + +Save PATH: + +``` +echo 'export PATH="$(pwd)/oss-cad-suite/bin:$PATH"' >> ~/.bashrc +source ~/.bashrc +``` + +Save container: + +``` +docker commit openroad-windows:latest +docker run -it openroad-windows:latest +``` + +--- + +## Step 7 — Run Example Design + +``` +cd /OpenROAD-flow-scripts/flow +make DESIGN_CONFIG=./designs/nangate45/gcd/config.mk +``` + + + +## Common Issues + +Yosys too old: +Use OSS CAD Suite (Step 3) + +apt-get stuck: + +``` +export DEBIAN_FRONTEND=noninteractive +``` + +GUI not working: + +``` +docker run -it -e DISPLAY=:0.0 openroad/orfs +``` + +Slow performance: +Use WSL path: +\\wsl$\Ubuntu\ + +Disk space fix: + +``` +wsl --export Ubuntu-22.04 D:\ubuntu_backup.tar +wsl --import Ubuntu-22.04 D:\WSL\Ubuntu D:\ubuntu_backup.tar +``` + +CRLF issue: + +``` +git config --global core.autocrlf false +``` + + + +## Optional: WSL2 Native Build + +See: BuildWithWSL.md in repository From 4aac36669575c55181cbcfe1490fcf718ddb2002 Mon Sep 17 00:00:00 2001 From: Divinesoumyadip Date: Sun, 22 Mar 2026 18:20:40 +0000 Subject: [PATCH 2/3] docs: add WindowsDocker to table of contents Signed-off-by: Divinesoumyadip --- docs/toc.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/toc.yml b/docs/toc.yml index 5fb7c2205e..e30c656f33 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -15,6 +15,8 @@ entries: title: Build Locally - file: user/BuildWithWSL.md title: Build Using WSL + - file: user/WindowsDocker.md + title: Build on Windows using Docker - file: user/FlowVariables.md title: Flow Variables - file: contrib/Metrics.md From 61b5c1cdc0c7e171580e2b2afdd277d01aeda537 Mon Sep 17 00:00:00 2001 From: Divinesoumyadip Date: Wed, 25 Mar 2026 10:18:32 +0000 Subject: [PATCH 3/3] docs: address luarss review feedback on WindowsDocker.md Signed-off-by: Divinesoumyadip --- docs/user/WindowsDocker.md | 148 +++++++++++++++++++++---------------- 1 file changed, 84 insertions(+), 64 deletions(-) diff --git a/docs/user/WindowsDocker.md b/docs/user/WindowsDocker.md index e258701285..679852640a 100644 --- a/docs/user/WindowsDocker.md +++ b/docs/user/WindowsDocker.md @@ -6,144 +6,164 @@ * Docker Desktop (WSL2 backend enabled) * At least 16GB RAM (8GB minimum usable) * At least 50GB free disk space +* VS Code (optional, recommended) +## Step 1 — Install and Configure Docker Desktop +> Run in PowerShell (Administrator) -## Step 1 — Install and Configure Docker Desktop +1. Install Docker Desktop with WSL2: + [https://docs.docker.com/desktop/windows/wsl/](https://docs.docker.com/desktop/windows/wsl/) -1. Install Docker Desktop with WSL 2 backend enabled 2. Configure resources: - * Memory: ≥ 8GB * CPUs: ≥ 4 -3. Enable WSL Integration for Ubuntu-22.04 -Verify installation: +3. Enable WSL Integration: + Docker Desktop → Settings → Resources → WSL Integration → Enable Ubuntu-22.04 -``` -docker run hello-world -``` +Verify installation: +bash +docker run --rm hello-world ## Step 2 — Avoid Timezone Prompt -Run before any apt-get: +> Run inside Docker container -``` +bash export DEBIAN_FRONTEND=noninteractive export TZ=UTC - apt-get update apt-get install -y tzdata -``` - ## Step 3 — Install Correct Yosys Version -``` -wget https://github.com/YosysHQ/oss-cad-suite-build/releases/latest/download/oss-cad-suite-linux-x64.tgz +> Run inside Docker container +bash +wget https://github.com/YosysHQ/oss-cad-suite-build/releases/download/2025-03-01/oss-cad-suite-linux-x64.tgz tar -xzf oss-cad-suite-linux-x64.tgz - echo 'export PATH="$(pwd)/oss-cad-suite/bin:$PATH"' >> ~/.bashrc source ~/.bashrc - yosys --version -``` - - ## Step 4 — Fix Line Endings (CRLF Issue) -Run before cloning: +> Run in PowerShell -``` +bash git config --global core.autocrlf false git config --global core.eol lf - git clone --recursive https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts -``` - - ## Step 5 — Copy Files into Docker -Option A: +### Option A: Copy files + +> Run in PowerShell -``` +bash docker ps docker cp C:\path\to\file :/tmp/ -``` -Option B (recommended): +### Option B (Recommended): Mount volume -``` +> Run in PowerShell + +bash docker run -it -v //c/Users/YourName/OpenROAD-flow-scripts:/OpenROAD-flow-scripts ubuntu:22.04 -``` ## Step 6 — Persist Environment -Save PATH: +> Run inside Docker container -``` +bash echo 'export PATH="$(pwd)/oss-cad-suite/bin:$PATH"' >> ~/.bashrc source ~/.bashrc -``` - -Save container: - -``` docker commit openroad-windows:latest docker run -it openroad-windows:latest -``` - ---- ## Step 7 — Run Example Design -``` +> Run inside Docker container + +bash cd /OpenROAD-flow-scripts/flow make DESIGN_CONFIG=./designs/nangate45/gcd/config.mk -``` +## Step 8 — VS Code Integration + +### Beginner: Attach to Running Container + +1. Install VS Code: [https://code.visualstudio.com/](https://code.visualstudio.com/) +2. Install Dev Containers extension +3. Run container: + +bash +docker run -it -v //c/Users/YourName/OpenROAD-flow-scripts:/OpenROAD-flow-scripts openroad-windows:latest + +4. In VS Code press `Ctrl+Shift+P` → Select "Attach to Running Container" → Choose your container + +### Intermediate: Open Folder in Container + +Press `Ctrl+Shift+P` → "Dev Containers: Open Folder in Container" → Choose your project folder +### Advanced: DevContainer Setup + +Create `.devcontainer/devcontainer.json`: + +json +{ + "name": "OpenROAD Development", + "image": "openroad/orfs:latest", + "workspaceMount": "source=${localWorkspaceFolder},target=/OpenROAD-flow-scripts,type=bind", + "workspaceFolder": "/OpenROAD-flow-scripts", + "customizations": { + "vscode": { + "extensions": [ + "ms-vscode.cpptools-extension-pack", + "twxs.cmake" + ] + } + }, + "remoteUser": "root" +} + +Press `Ctrl+Shift+P` → "Dev Containers: Reopen in Container" ## Common Issues -Yosys too old: +### Yosys too old + Use OSS CAD Suite (Step 3) -apt-get stuck: +### apt-get stuck -``` +bash export DEBIAN_FRONTEND=noninteractive -``` -GUI not working: +### GUI not working -``` +bash docker run -it -e DISPLAY=:0.0 openroad/orfs -``` -Slow performance: -Use WSL path: -\\wsl$\Ubuntu\ +### Slow performance -Disk space fix: +Use WSL path: `\\wsl$\Ubuntu\` -``` +### Disk space fix + +bash wsl --export Ubuntu-22.04 D:\ubuntu_backup.tar wsl --import Ubuntu-22.04 D:\WSL\Ubuntu D:\ubuntu_backup.tar -``` - -CRLF issue: - -``` -git config --global core.autocrlf false -``` +### VS Code not connecting +* Ensure Docker Desktop is running +* Restart VS Code +* Check Dev Containers extension is installed ## Optional: WSL2 Native Build -See: BuildWithWSL.md in repository +See: [BuildWithWSL.md](BuildWithWSL.md)