# 阶段 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. 安装的包

```bash
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）

```bash
# 编译
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. 常用命令速查

```bash
# 激活环境
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**（只读、浅克隆、不拉子模块）：

```bash
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 后端时再构建。