开源 EDA 环境搭建：Docker 镜像一行起，版本固定不漂移
更新时间：2026-11-04。前面的 iverilog 第一次仿真完整流程 默认你已经把工具装进了系统，本篇解决更前置的问题：开源 EDA 工具链（iverilog、Verilator、Yosys、OpenSTA）怎么在自己机器上一次装好、版本还能长期固定。结论先行——不要在宿主机上逐个编译安装，用 Docker 镜像一行起，宿主机只留一个 Docker。
本文要回答的问题
- 仿真、综合、时序分析四五个工具，为什么推荐装进一个 Docker 镜像而不是宿主机直装？
docker run --rm -v "$PWD":/work -w /work这行命令每个参数在 EDA 场景下管什么？- 镜像 tag 和 image id 是什么关系，怎样保证三个月后跑出来的工具版本一模一样？
- 容器是一次性的，那编译产物
sim.vvp、报告文件怎么留在宿主机上？ - 挂载路径、文件权限、tag 漂移这些新手高频坑怎么自查？
整条环境搭建链路先给一张总览卡，后面逐段展开：
读这张卡抓住一个核心分工：镜像负责环境，挂载目录负责工程。工具二进制、依赖库全部封死在只读的镜像层里；你的设计文件一个都不进镜像，永远通过挂载点进出。这样镜像可以删、可以换、可以在别人机器上重新拉，工程目录毫发无损。
一、这一步在数字设计流程里的位置
环境搭建是零号步骤：它不产出任何设计结果，只给后面的仿真、综合、时序分析提供一个版本确定的执行环境。上游只有一个输入——你选定的工具版本组合；下游是所有命令行流程，它们都假设「敲 iverilog 一定能找到，且版本就是我要的那个」。
读这张图注意数据走的是一个来回：宿主机目录被挂载进容器，工具在容器里读写同一个目录，产物天然落回宿主机；容器本身随命令结束而消失，不留任何状态。这与宿主机直装形成鲜明对比：
| 对比维度 | 宿主机直装（apt/brew/源码编译） | Docker 镜像 |
|---|---|---|
| 安装成本 | 每个工具各自解决依赖，Verilator/Yosys 源码编译数十分钟 | 拉镜像一次，1.06GB 含四套工具 |
| 版本固定 | 一次系统升级可能悄悄换掉 iverilog | tag 固定后 image id 永不变 |
| 隔离性 | 污染系统库，多个项目要不同版本时互相打架 | 项目间换 tag 即可，互不影响 |
| 可复现 | 换台机器要重做一遍并祈祷依赖一致 | 任何装了 Docker 的机器拉同一镜像即可 |
| 代价 | 无额外抽象，调试原生问题直接 | 需理解挂载与容器，GUI 波形工具要绕一道 |
只有一种情况优先直装：你在开发工具本身、需要 gdb 调试工具源码。做设计、跑流程，镜像几乎总是更优解。
二、命令逐段解读：run、挂载与 Dockerfile
日常使用的完整命令形态是：
docker run --rm -v "$PWD":/work -w /work geek-eda:0.3-sta iverilog -o sim.vvp design.v tb_add2.v逐段拆开：
| 参数 | 作用 | 不写会怎样 |
|---|---|---|
docker run | 由镜像启动一个新容器并执行命令 | —— |
--rm | 命令结束后自动删除容器 | 每次跑完留一个停止态容器，docker ps -a 越积越多 |
-v "$PWD":/work | 把宿主机当前目录 bind mount 到容器内 /work | 容器里看不到你的 .v 文件，产物也写不回宿主机 |
-w /work | 设定容器内工作目录 | 默认在镜像 WORKDIR，相对路径与挂载点对不上时找不到文件 |
geek-eda:0.3-sta | 镜像名加固定 tag | 用 latest 会在重新拉取时静默漂移到新版本 |
| 末尾命令 | 容器内实际执行的工具与参数 | 不给则启动镜像默认入口 |
"$PWD" 必须带引号且先 cd 到工程目录再执行，它取的是命令发起时的宿主机路径。换工具只换最后一段：verilator --lint-only -Wall design.v、yosys -p 'read_verilog design.v; synth'、sta -no_init -exit run_sta.tcl，环境部分一字不改。
镜像本身从哪来？最小的 Dockerfile 只有几行：
FROM debian:bookworm-slim
RUN apt-get update \
&& apt-get install -y --no-install-recommends iverilog make ca-certificates \
&& rm -rf /var/lib/apt/lists/*
WORKDIR /workFROM 选 Debian bookworm 的 slim 底包；所有 apt-get install 合并在同一个 RUN 层并立刻清掉包列表，是为了不让安装缓存残留在镜像层里撑大体积；WORKDIR /work 让 docker run -w /work 有一个确定落点。执行 docker build -t flow-eda-mini:0.1 . 即得到自己的最小镜像。实测这一层只增加 18.2MB 磁盘占用，但要注意：Debian bookworm 仓库里的 iverilog 是 11.0，而本文实测用的 geek-eda:0.3-sta 里是 12.0——发行版包通常落后上游，要指定精确小版本就得在 Dockerfile 里从源码编译，这也正是维护一个版本固定镜像的价值。
三、输入输出文件：镜像、容器与挂载目录各装什么
这套玩法里有三类「文件」，新手最容易把它们混为一谈：
| 类别 | 是什么 | 生命周期 | 例子 |
|---|---|---|---|
| 镜像（image） | 只读模板，含操作系统与工具 | 长期存在，用 tag/id 引用 | geek-eda:0.3-sta，id d055b33672e0，1.06GB |
| 容器（container） | 镜像的一次运行实例 | --rm 下随命令结束删除 | 跑完一次 vvp 就消失 |
| 挂载目录 | 宿主机工程目录的映射 | 与普通目录一样持久 | design.v、tb_add2.v、生成的 sim.vvp |
输入是宿主机当前目录里的 RTL 与 testbench，比如本次的两位加法器设计：
module add2 (
input wire [1:0] a,
input wire [1:0] b,
output wire [2:0] s
);
assign s = a + b;
endmodule容器内 iverilog -o sim.vvp design.v tb_add2.v && vvp sim.vvp 执行后，sim.vvp 不是留在某个会被删掉的容器角落，而是通过挂载点直接写回宿主机目录，ls 立刻可见。镜像不绑定任何具体工程，同一个镜像今天服务加法器实验、明天服务综合流程，靠的就是工程数据全在挂载点。
版本固定的关键凭证是 image id。tag 是给人看的名字，id 是镜像内容的哈希：同一个 tag 只要不重新打 tag，底层 id 永远不变。用 docker images 镜像:tag --format 记下 id（本次为 d055b33672e0），三个月后换机器再拉，id 一致就意味着工具组合逐字节相同——这正是教学和回归环境最需要的确定性。
四、常见错与检查点
第一次用容器跑 EDA，卡点高度集中在下面四处，它们都是正常流程上的检查点，不是排错大全：
| 现象 | 先查什么 | 纠正 |
|---|---|---|
容器内 ls 看不到自己的 .v 文件 | 是否先 cd 到工程目录；-v "$PWD":/work 与 -w /work 路径是否一致 | 在工程目录内执行，两个路径对齐到同一个 /work |
| 容器里明明生成了 sim.vvp，退出后宿主机找不到 | 产物是否写在挂载点之外（如 /tmp、容器 HOME） | 所有输出显式写到 /work 下，靠挂载点落回宿主机 |
| 换台机器拉同一个 tag，工具版本变了 | tag 是否为 latest 这类浮动 tag | 改用 0.3-sta 一类固定 tag，并核对 image id，参见 OpenLANE 镜像 tag 不匹配 |
docker run 报 permission denied / 连不上 daemon | Docker Desktop 是否启动、当前用户是否在 docker 组 | 启动引擎或加用户组，参见 Docker 权限被拒 |
一个判断顺序：进了容器但看不到文件，查挂载；命令找不到，查镜像 tag；报权限错，查宿主机 Docker 引擎本身。另外在 Apple Silicon 上运行只构建了 x86 的镜像时，Docker 会走 QEMU 模拟，仿真能跑但速度明显变慢，介意的话准备多架构镜像。
五、真实跑一遍：四工具版本验证与挂载仿真
在 Docker 24.0.7 的宿主机上，用本机已有的版本固定镜像 geek-eda:0.3-sta 先核对镜像身份与四套工具版本，真实输出如下：
实录第 2 行是宿主机 Docker 版本；第 6 行明确打出 repo=geek-eda tag=0.3-sta id=d055b33672e0 size=1.06GB——这就是日后核对环境一致性的凭证；随后四个一次性容器分别打印 iverilog 12.0、Verilator 5.020、Yosys 0.33、OpenSTA 2.0.17，每个容器只跑一条 --version 就退出，互不共享状态。
接着挂载 demo 目录，在容器内完成编译与仿真：
容器内 pwd 打印 /work，ls 能看到挂载进来的 design.v 与 tb_add2.v，证明挂载点对齐；vvp 输出 sum=3 (expect 3)，自校验通过后 testbench 正常 $finish。同一份 log 后半段还完整记录了用前述 Dockerfile 本地构建 flow-eda-mini:0.1 的全过程：底包拉取 34.8 秒、apt 层 12.8 秒、最终导出镜像 sha256:fe4cd2ea…，与 run 脚本里的六步一一对应。复现时建议把两条路都走一遍：先用固定镜像跑通工程，再自己 build 一次最小镜像，对比两者 iverilog 的小版本差异（12.0 对 11.0），亲眼看到「镜像内容决定工具版本」。
实验环境
- 机器/系统：macOS（Darwin 25.5，Apple Silicon）+ Docker Desktop，容器内为 Debian bookworm（Linux amd64）
- 工具版本：宿主机 Docker 24.0.7（build afdd53b）；镜像
geek-eda:0.3-sta（idd055b33672e0，1.06GB）内 Icarus Verilog 12.0、Verilator 5.020（Debian 5.020-1）、Yosys 0.33（git sha1 2584903a060）、OpenSTA 2.0.17 - 日期：2026-11-03
- 完整命令：
bash class-run.sh（宿主机 docker 版本 → 镜像 id 核对 → 四个一次性容器打印工具版本 → 挂载 demo 目录执行iverilog -o sim.vvp design.v tb_add2.v && vvp sim.vvp）；另执行bash run.sh用 Dockerfile 本地构建flow-eda-mini:0.1最小镜像并复跑同一 demo
代码获取
Dockerfile、复现脚本与最小 demo 已同步到公开仓库：geek-doc.cn/experiments/flow-eda-env-docker-setup，克隆后进入该目录执行 bash run.sh 即可从零构建最小镜像并在容器内跑通挂载编译仿真；已有 geek-eda:0.3-sta 镜像时执行 bash class-run.sh 复现本文全部版本核对输出。
这一篇在知识体系里的位置
- 环境就绪后，跟着走完第一条仿真闭环：读 iverilog 第一次仿真完整流程；
- 想理解仿真这一步在整个数字设计流程中的位置：读 仿真是什么；
- 同一镜像还能支撑综合与仿真器对比：读 Yosys 综合流程与报告 与 Verilator 与 VCS 的主要差异；
- 容器相关报错的专项排查：Docker 权限被拒、镜像 tag 不匹配。
总结
开源 EDA 环境搭建的推荐做法是把 iverilog、Verilator、Yosys、OpenSTA 全部封进一个固定 tag 的 Docker 镜像：日常只需 docker run --rm -v "$PWD":/work -w /work 镜像 工具命令，--rm 让容器用完即删，-v 加 -w 让工程目录挂载进容器、产物原路写回宿主机，镜像 tag 与 image id（如 geek-eda:0.3-sta = d055b33672e0）共同保证任何机器上工具版本逐字节一致。记住三个检查点——看不到文件查挂载路径，产物丢失查是否写在挂载点之外，版本漂移查浮动 tag——你就拥有了一个不污染宿主机、可复现、可分享的数字设计工作台。