第2章 环境搭建：MLIR源码编译、安装依赖、使用Ninja和CMake构建，以及运行第一个MLIR示例

MLIR（Multi-Level Intermediate Representation）作为LLVM生态中面向编译器基础设施的多级中间表示框架，其开发环境搭建是后续学习Dialect定义、Pass编写与转换Pipeline设计的基础。本章将围绕源码获取、依赖安装、CMake与Ninja构建配置、以及首个MLIR示例的运行展开，帮助读者建立一套可复现、可调试、可扩展的MLIR开发环境。本章内容以Ubuntu 22.04 LTS（x86_64）为基准环境，但所有命令与配置思路同样适用于macOS（Apple Silicon需注意架构差异）及WSL2环境。

2.1 核心原理：MLIR构建系统的组成与依赖关系

MLIR并非一个独立仓库，而是作为LLVM项目的一部分进行维护。其源码位于llvm-project仓库的mlir子目录中，与LLVM核心库、Clang前端、LLD链接器等共享同一套构建系统。理解这一结构是避免环境搭建混乱的关键。MLIR的构建依赖关系可以概括为：CMake负责生成构建规则，Ninja负责并行执行编译任务，LLVM/MLIR的TableGen工具负责从.td文件生成C++代码。TableGen是MLIR开发中不可忽视的环节，Dialect定义、Operation定义、属性/类型定义均通过TableGen描述，再由mlir-tblgen生成对应的C++头文件与实现。

从编译依赖角度看，MLIR需要以下核心组件：

• LLVM核心库：提供IR数据结构、Pass基础设施、支持库（ADT、Support等）。
• MLIR库：包括MLIRIR、MLIRPass、MLIRTransforms、MLIRDialect等模块。
• MLIR工具：mlir-opt（优化与转换）、mlir-translate（与LLVM IR互转）、mlir-cpu-runner（JIT执行）。
• TableGen：用于从声明式定义生成C++代码，是Dialect开发的核心工具。

构建系统采用“外部项目”模式，即MLIR作为LLVM的一个project被启用。CMake变量LLVM_ENABLE_PROJECTS="mlir"告诉构建系统需要编译MLIR及其依赖的LLVM库。这种设计使得MLIR可以复用LLVM的构建缓存、编译选项和工具链检测逻辑，避免重复配置。

2.2 操作流程：从零开始构建MLIR

2.2.1 安装系统依赖

在Ubuntu 22.04上，首先需要安装基础工具链。推荐使用Clang作为编译器，因为LLVM项目本身对Clang的兼容性最好，且支持较新的C++17特性。执行以下命令：

sudo apt update
sudo apt install -y git cmake ninja-build clang lld python3-dev
# 验证版本
cmake --version   # 需要 3.20+
ninja --version   # 需要 1.10+
clang --version   # 需要 14+

如果系统自带的CMake版本过低，可以通过pip install cmake或从官网下载最新版。Ninja通常版本较新，无需额外处理。Python3-dev用于支持MLIR的Python绑定（可选）。

2.2.2 获取LLVM/MLIR源码

MLIR的源码托管在LLVM官方仓库中。建议使用浅克隆（--depth=1）以节省时间，但若需要切换分支或查看历史，则需完整克隆。推荐使用以下方式：

git clone https://github.com/llvm/llvm-project.git
cd llvm-project
# 可选：切换到稳定版本，例如 llvmorg-18.1.8
git checkout llvmorg-18.1.8

2.2.3 CMake配置与生成

在llvm-project目录下创建构建目录，并运行CMake。以下是一个经过验证的配置方案：

mkdir build
cd build
cmake -G Ninja ../llvm \
  -DLLVM_ENABLE_PROJECTS="mlir" \
  -DLLVM_BUILD_EXAMPLES=ON \
  -DLLVM_TARGETS_TO_BUILD="host" \
  -DCMAKE_BUILD_TYPE=Release \
  -DLLVM_ENABLE_ASSERTIONS=ON \
  -DLLVM_USE_LINKER=lld \
  -DCMAKE_C_COMPILER=clang \
  -DCMAKE_CXX_COMPILER=clang++

参数说明：

参数	作用	推荐值
LLVM_ENABLE_PROJECTS	启用MLIR子项目	"mlir"
LLVM_BUILD_EXAMPLES	编译MLIR示例（含Toy教程）	ON
LLVM_TARGETS_TO_BUILD	指定目标架构，host表示仅当前机器架构	"host"
CMAKE_BUILD_TYPE	Release优化编译，Debug用于调试	Release
LLVM_ENABLE_ASSERTIONS	启用断言，便于开发调试	ON
LLVM_USE_LINKER	使用lld加速链接	lld

2.2.4 使用Ninja构建

配置成功后，执行Ninja进行编译。MLIR的编译时间取决于机器性能，通常需要20-60分钟。建议使用多线程：

ninja -j$(nproc)   # 使用所有CPU核心
# 如果内存不足，可限制并行度，例如 -j4

构建完成后，可执行文件位于build/bin目录下。验证MLIR工具是否可用：

./bin/mlir-opt --version
# 输出类似：MLIR (http://mlir.llvm.org/) 18.1.8

2.3 案例拆解：运行第一个MLIR示例

为了验证环境正确性，我们编写一个最简单的MLIR模块，并使用mlir-opt进行解析和输出。该示例不涉及任何Dialect特定操作，仅包含一个空函数，用于验证基础IR解析能力。

步骤1：创建示例文件

cat > test.mlir << 'EOF'
func.func @main() {
  return
}
EOF

步骤2：运行mlir-opt

./bin/mlir-opt test.mlir

预期输出：

module {
  func.func @main() {
    return
  }
}

如果输出与输入一致，说明MLIR解析器工作正常。接下来，我们尝试一个更复杂的示例，使用toy Dialect（MLIR自带的Toy教程示例）。由于我们启用了LLVM_BUILD_EXAMPLES=ON，Toy示例已被编译。

步骤3：运行Toy示例

# 进入Toy示例目录
cd ../mlir/examples/toy/Ch1/
# 编译Toy源文件
../../../../build/bin/toyc-ch1 ../../../../mlir/test/Examples/Toy/Ch1/ast.toy -emit=mlir

该命令将Toy语言源码转换为MLIR IR。输出会展示toy.constant、toy.func等操作，证明MLIR的Dialect机制已正常工作。

2.4 常见误区与总结复盘

在环境搭建过程中，读者常遇到以下几类问题，这里逐一分析并提供解决方案。

误区/问题	现象	解决方案
使用系统gcc版本过旧	编译报错undefined reference to std::__cxx11::basic_string	安装gcc-11或使用clang
CMake版本低于3.20	报错CMake 3.20 or higher is required	通过pip升级cmake
磁盘空间不足	编译中途报No space left on device	预留至少30GB空间，或使用df -h检查
内存不足导致OOM	Ninja进程被kill	减少并行度-j2，或增加swap
链接错误	报错ld: cannot find -lz	安装zlib1g-dev
Python绑定失败	找不到mlir Python模块	安装python3-dev，并确保CMake配置中MLIR_BINDINGS_PYTHON_ENABLED=ON

复盘总结：环境搭建的核心在于“版本匹配”与“依赖完整”。建议读者在开始前记录当前系统的gcc/clang版本、CMake版本、可用磁盘空间。构建过程中，若出现错误，优先查看build/CMakeFiles/CMakeError.log或ninja -v输出，定位具体编译命令。另外，MLIR的Debug构建虽然编译时间更长（可能超过2小时），但对于后续学习Pass开发、断点调试非常有帮助，建议有条件的读者准备两套构建目录（Release与Debug），分别用于日常使用和源码学习。