120 lines
5.1 KiB
Markdown
120 lines
5.1 KiB
Markdown
# 从源码构建 IREE（写 pass 的前置）
|
||
|
||
> 2026-08-15。为了写自定义 pass，需要从源码构建 IREE 编译器（pip 包只有二进制，没有头文件和构建系统）。
|
||
> 记录完整步骤，方便复现。
|
||
|
||
## 1. 为什么要源码构建
|
||
|
||
pip 安装的 `iree-base-compiler` 是预编译二进制，**没有头文件、没有 CMake 构建系统**，无法编写和编译自定义 pass。
|
||
写 pass 需要：源码 + LLVM/MLIR 头文件 + 构建系统。
|
||
|
||
## 2. 前提（工具链）
|
||
|
||
```bash
|
||
sudo apt install clang-15 lld-15 # 编译器 + 链接器（Ubuntu 22.04 最新可用 clang）
|
||
.venv/bin/pip install ninja # ninja 也可用 pip 装（免 sudo）
|
||
```
|
||
|
||
- clang-15（不能用默认 clang=14，可能太老，IREE 3.11 用 LLVM 23）
|
||
- lld-15（快速链接，可选但推荐）
|
||
- ninja（构建生成器）
|
||
- cmake（系统已有）
|
||
|
||
## 3. 子模块
|
||
|
||
```bash
|
||
# 关键子模块：llvm-project（IREE fork，~1.5GB，最耗时）、flatcc（VM 字节码）
|
||
git submodule update --init --depth 1 third_party/llvm-project third_party/flatcc
|
||
```
|
||
|
||
> 只初始化编译所需的最小集合。写 pass 测试用 linalg 输入，不需要 stablehlo/torch-mlir 等子模块。
|
||
|
||
## 4. 配置（cmake）
|
||
|
||
```bash
|
||
cmake -G Ninja -B build/ -S . \
|
||
-DCMAKE_BUILD_TYPE=RelWithDebInfo \
|
||
-DCMAKE_C_COMPILER=clang-15 -DCMAKE_CXX_COMPILER=clang++-15 \
|
||
-DIREE_ENABLE_LLD=ON \
|
||
-DIREE_BUILD_TESTS=OFF -DIREE_BUILD_SAMPLES=OFF -DIREE_BUILD_PYTHON_BINDINGS=OFF \
|
||
-DIREE_TARGET_BACKEND_DEFAULTS=OFF -DIREE_TARGET_BACKEND_LLVM_CPU=ON \
|
||
-DIREE_HAL_DRIVER_DEFAULTS=OFF -DIREE_HAL_DRIVER_LOCAL_SYNC=ON -DIREE_HAL_DRIVER_LOCAL_TASK=ON
|
||
```
|
||
|
||
关键选项：
|
||
- `-DIREE_BUILD_TESTS/SAMPLES/PYTHON_BINDINGS=OFF` —— 大幅缩减构建（只建编译器）
|
||
- `-DIREE_TARGET_BACKEND_DEFAULTS=OFF + LLVM_CPU=ON` —— 只保留 CPU 后端
|
||
- `-DIREE_HAL_DRIVER_DEFAULTS=OFF + LOCAL_SYNC/TASK=ON` —— 只保留 CPU 运行时驱动
|
||
- `-DCMAKE_BUILD_TYPE=RelWithDebInfo` —— 有调试信息 + 优化（写 pass 推荐）
|
||
|
||
## 5. 构建
|
||
|
||
```bash
|
||
# 只构建编译器工具（iree-compile + iree-opt），比全量快很多
|
||
cmake --build build/ --target iree-compile iree-opt -j 16
|
||
```
|
||
|
||
- 结果在 `build/tools/iree-compile`、`build/tools/iree-opt`
|
||
- `iree-opt` 是测试 pass 的关键工具（单 pass 运行，无需完整编译管线）
|
||
- 首次全量构建 ~30-60 分钟（16 核）
|
||
|
||
## 6. 验证
|
||
|
||
```bash
|
||
build/tools/iree-compile --version
|
||
build/tools/iree-opt --help
|
||
```
|
||
|
||
## 7. 写 pass 的流程（后续）
|
||
|
||
1. 在某个 dialect 的 `Transforms/` 下写 pass 的 `.cpp`
|
||
2. 在对应 `Passes.td` 里注册 pass（TableGen）
|
||
3. 在 `CMakeLists.txt` 里加入源文件
|
||
4. 重新构建（增量构建，快）
|
||
5. 用 `iree-opt --pass-name` 单测 pass
|
||
|
||
## 8. 备选：gcc 构建（不用 sudo）
|
||
|
||
如果没有 sudo 装 clang，可以用系统 gcc 11.4（支持 C++17）：
|
||
```bash
|
||
cmake -G Ninja -B build/ -S . -DCMAKE_BUILD_TYPE=RelWithDebInfo \
|
||
-DIREE_BUILD_TESTS=OFF -DIREE_BUILD_SAMPLES=OFF -DIREE_BUILD_PYTHON_BINDINGS=OFF \
|
||
-DIREE_TARGET_BACKEND_DEFAULTS=OFF -DIREE_TARGET_BACKEND_LLVM_CPU=ON \
|
||
-DIREE_HAL_DRIVER_DEFAULTS=OFF -DIREE_HAL_DRIVER_LOCAL_SYNC=ON -DIREE_HAL_DRIVER_LOCAL_TASK=ON
|
||
```
|
||
（gcc 是 IREE 官方"best effort"支持，能用但稍慢。）
|
||
|
||
## 9. 实际踩坑记录（本次构建的关键修复）
|
||
|
||
### 9.1 工具链版本
|
||
- **cmake 3.22 太旧**（需 3.26+）→ `pip install cmake`（4.4.2）
|
||
- **clang-15 需要 g++-12**：系统只有 `gcc-12`（无 `g++-12`）和 `libstdc++-11-dev`，导致
|
||
clang-15 自动选 GCC 12 却找不到 C++ 头文件/`libstdc++.so`。
|
||
修复：`sudo apt install g++-12`（带 `libstdc++-12-dev`）
|
||
- **lld**：装了 `lld-15` 但没有无版本号 `ld.lld`。修复：软链接
|
||
`ln -sf /usr/bin/ld.lld-15 .venv/bin/ld.lld`，并把 `.venv/bin` 加入 PATH
|
||
|
||
### 9.2 llvm-project 子模块用 tarball 而非 git
|
||
git 方式下载 llvm-project（1.5GB）在 VPN 下被 GitHub 限速（~30KB/s），改用 **codeload tarball**（280MB 压缩）+ 断点续传，快很多。但 git 不认 tarball 解压出的目录为子模块，导致 IREE 的子模块检查失败。
|
||
|
||
修复：把 `build_tools/scripts/git/check_submodule_init.py` 改成 no-op（本地构建，手动提供源码）。
|
||
|
||
### 9.3 只保留必要组件（大幅缩减构建）
|
||
|
||
最终配置命令：
|
||
```bash
|
||
cmake -G Ninja -B build/ -S . \
|
||
-DCMAKE_BUILD_TYPE=RelWithDebInfo \
|
||
-DCMAKE_C_COMPILER=clang-15 -DCMAKE_CXX_COMPILER=clang++-15 \
|
||
-DIREE_ENABLE_LLD=ON \
|
||
-DIREE_BUILD_TESTS=OFF -DIREE_BUILD_SAMPLES=OFF -DIREE_BUILD_PYTHON_BINDINGS=OFF -DIREE_BUILD_BENCHMARKS=OFF \
|
||
-DIREE_TARGET_BACKEND_DEFAULTS=OFF -DIREE_TARGET_BACKEND_LLVM_CPU=ON \
|
||
-DIREE_HAL_DRIVER_DEFAULTS=OFF -DIREE_HAL_DRIVER_LOCAL_SYNC=ON -DIREE_HAL_DRIVER_LOCAL_TASK=ON \
|
||
-DIREE_INPUT_STABLEHLO=OFF -DIREE_INPUT_TORCH=OFF -DIREE_INPUT_TOSA=OFF
|
||
```
|
||
关键：`-DIREE_BUILD_BENCHMARKS=OFF`（否则要 benchmark 子模块）、
|
||
`-DIREE_INPUT_*=OFF`（否则要 stablehlo/torch-mlir 子模块）。
|
||
|
||
### 9.4 写 pass 最小依赖子模块
|
||
只用 **llvm-project + flatcc** 两个子模块（linalg 输入 + VM 字节码输出），其余全关。
|