阶段 0：环境准备 ✅

2026-08-13 完成。记录 IREE 环境搭建过程，方便复现。

1. 安装方式

venv（不用 conda，见下），位置：.venv/（项目根目录）
PyPI 镜像：清华源（pypi.org 实测仅 ~17-82KB/s，太慢；清华源 ~1.1MB/s）
- 配置写在 .venv/pip.conf：index-url = https://pypi.tuna.tsinghua.edu.cn/simple

2. 安装的包

python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install iree-base-compiler iree-base-runtime

包	版本	说明
`iree-base-compiler`	3.11.0	编译器（含 `iree-compile`、`iree-opt` 等）
`iree-base-runtime`	3.11.0	运行时（含 `iree-run-module`、`iree-dump-module` 等）

⚠️ 包名要点（重要，坑）

IREE 在 2024-11 前后重构了 Python 包：

老的 iree-compiler / iree-runtime（日期版本号）已停在 20241104.1068，不再更新
新的用语义化版本号，包名是 iree-base-compiler / iree-base-runtime（当前 3.11.0）
没有 iree-tools 这个包，CLI 工具直接随 base 包分发

3. 工具链

iree-compile / iree-run-module / iree-dump-module / iree-opt / iree-import-onnx / iree-benchmark-module 等，都在 .venv/bin/ 下。

编译器版本：IREE compiler 3.11.0rc20260316，LLVM 23.0.0git
注意：iree-run-module 是 C 工具，不吃 --version（报 flag not recognized），这是正常的

4. 最小端到端验证

文件：examples/matmul.mlir（linalg 矩阵乘 2x4 @ 4x2 → 2x2）

# 编译
iree-compile --iree-hal-target-backends=llvm-cpu examples/matmul.mlir -o examples/matmul.vmfb
# 运行
iree-run-module --module=examples/matmul.vmfb --function=matmul \
  --input=2x4xf32=1,2,3,4,5,6,7,8 --input=4x2xf32=1,2,3,4,5,6,7,8
# 输出
2x2xf32=[50 60][114 140]   # 与手算一致 ✓

编译时的提示

iree-compile 会提示「未指定 CPU 目标」，建议加 --iree-llvmcpu-target-cpu=host （针对本机 CPU 生成最优代码）或 =generic（通用、可移植）。学习阶段可用默认值，不影响正确性。

5. 硬件 / 后续

CPU：16 核 x86_64
GPU：NVIDIA RTX 4070 Ti SUPER（驱动 580.173.02）
- CUDA backend 尚未配置：base runtime 默认只有 CPU（local-task）。CUDA/Vulkan 后端后续需要：
  - 编译器侧：iree-compile --iree-hal-target-backends=cuda（base 包可能不含 CUDA 代码生成，需确认）
  - 运行时侧：CUDA HAL driver（可能需源码编译或插件）
- 学习阶段先用 CPU 即可，阶段 6 深入 codegen 时再按需补 GPU 后端
无 Vulkan（未装 vulkaninfo），后续要用 Vulkan 后端需先装 Vulkan 驱动/loader

6. 常用命令速查

# 激活环境
source .venv/bin/activate
# 编译（CPU）
iree-compile --iree-hal-target-backends=llvm-cpu in.mlir -o out.vmfb
# 运行
iree-run-module --module=out.vmfb --function=<fn> --input=<shape>xtype=vals
# 看编译后的模块结构 / 反汇编
iree-dump-module --module=out.vmfb
# 看完整 lowering 管线（学习核心工具）
iree-compile --mlir-print-ir-after-all in.mlir -o out.vmfb

7. 源码（读 vs 构建）

区分三件事：

目的	需要什么	状态
跑 IREE、看 pipeline	pip 二进制包	✅ 已装
读 IREE 源码	`git clone`（只读）	✅ 已 clone
改代码 + 断点调试	源码构建	⬜ 暂缓（阶段 8 / 需要 CUDA 时）

已 clone（只读、浅克隆、不拉子模块）：

cd src && git clone --depth 1 --single-branch https://github.com/iree-org/iree.git
# 位置: src/iree/（约 211MB）

关键目录：

compiler/src/iree/compiler/Dialect/ —— Flow / Stream / HAL / VM / VMVX / LinalgExt / TensorExt / Encoding / Util
compiler/src/iree/compiler/Codegen/ —— LLVMCPU / LLVMGPU / Common / Dialect
runtime/src/iree/ —— hal / vm / task / async / base

从源码构建（暂缓，先了解成本）：需 clang + ninja，几十 GB 磁盘、~1 小时编译；只 debug 编译器可只构建 iree-compile 目标。学习阶段用 --mlir-print-ir-after-all 看 pipeline 即可，不必构建。到阶段 8 实践（写自定义 pass）或要 CUDA 后端时再构建。

4.2 KiB Raw Blame History Unescape Escape