构建安装¶
本文说明AscendNPU IR的依赖安装、构建方式（源码/二进制）及运行测试步骤。
环境依赖准备¶
编译器与工具链要求：
CMake >= 3.28
Ninja >= 1.12.0
推荐使用工具：
Clang >= 10
LLD >= 10（使用LLVM LLD将显著提升构建速度）
源码拉取与子模块初始化：
本项目依赖LLVM、Torch-MLIR等三方库，需要拉取并更新到指定的commit id。
# 克隆主仓库并进入项目根目录
git clone https://gitcode.com/Ascend/ascendnpu-ir.git
cd ascendnpu-ir
# 初始化并更新子模块
git submodule update --init --recursive
CANN包安装：
AscendNPU IR端到端运行依赖CANN环境。
下载CANN包：需下载CANN Toolkit包及与硬件对应的
ops包，可从昇腾社区CANN下载页获取。安装CANN包：
# 以x86系统Atlas A3系列产品安装CANN包为例，其中{version}为CANN版本，如9.0.0 chmod +x Ascend-cann_{version}_linux-x86_64.run chmod +x Ascend-cann-A3-ops_{version}_linux-x86_64.run ./Ascend-cann_{version}_linux-x86_64.run --full [--install-path=${PATH-TO-CANN}] ./Ascend-cann-A3-ops_{version}_linux-x86_64.run --install [--install-path=${PATH-TO-CANN}]
设置环境变量：
# 若是8.5.0及更早期的版本，路径为${PATH-TO-CANN}/ascend-toolkit/set_env.sh source ${PATH-TO-CANN}/cann/set_env.sh
构建方式¶
一键构建脚本build.sh（推荐）¶
在项目根目录下执行./build-tools/build.sh即可完成配置、构建和安装。脚本会自动处理CMake配置、Ninja编译及安装步骤。
# 首次构建（需先初始化子模块）
./build-tools/build.sh -o ./build --build-type Release
# 已有构建目录，增量编译
./build-tools/build.sh -o ./build --build-type Release
# 清空构建目录，全量重新构建
./build-tools/build.sh -o ./build --build-type Release -r
脚本参数说明：
参数 |
说明 |
默认值 |
|---|---|---|
|
构建产物输出目录 |
|
|
构建类型 |
|
|
清空构建目录并重新配置 |
关闭 |
|
并行编译线程数 |
CPU核心数的3/4 |
|
安装路径 |
|
|
|
clang |
|
C++编译器路径 |
clang++ |
|
LLVM源码目录 |
|
|
构建并运行测试 |
关闭 |
|
构建BiShengIR文档 |
关闭 |
|
构建BiShengIR模板库，启用该选项需要安装CANN 9.0.0，运行端到端用例必须启用 |
关闭 |
|
bisheng编译器所在目录，构建模板库时需指定 |
无 |
|
同时构建torch-mlir |
关闭 |
|
启用MLIR python-binding |
关闭 |
|
启用CPU runner |
关闭 |
|
禁用ccache |
启用（若已安装） |
|
启用断言 |
关闭 |
|
跳过安装步骤 |
关闭 |
|
追加CMake选项 |
无 |
常用示例：
# Debug构建并运行测试
./build-tools/build.sh -o ./build --build-type Debug --build-test
# 指定编译器与线程数
./build-tools/build.sh -o ./build --c-compiler /usr/bin/clang-15 --cxx-compiler /usr/bin/clang++-15 -j 256
# 快速构建（不执行安装）
./build-tools/build.sh -o ./build --fast-build
# 重新构建并构建模板库（端到端用例执行依赖模板库）
./build-tools/build.sh -r -o ./build --fast-build -t --bisheng-compiler=/usr/Ascend/cann/bin
手动CMake+Ninja构建（自定义编译参数）¶
适用于需要精细化控制编译参数的场景，前置条件：已完成子模块初始化（git submodule update --init --recursive）。
# 在项目根目录下
mkdir -p build
cd build
# LLVM源码路径：third-party/llvm-project/llvm
export LLVM_SOURCE_DIR="$(realpath ../third-party/llvm-project)"
cmake ${LLVM_SOURCE_DIR}/llvm -G Ninja \
-DCMAKE_C_COMPILER=clang \
-DCMAKE_CXX_COMPILER=clang++ \
-DCMAKE_BUILD_TYPE=Release \
-DLLVM_ENABLE_PROJECTS="mlir" \
-DLLVM_EXTERNAL_PROJECTS="bishengir" \
-DLLVM_EXTERNAL_BISHENGIR_SOURCE_DIR="$(realpath ..)" \
-DBSPUB_DAVINCI_BISHENGIR=ON \
# [-DCMAKE_INSTALL_PREFIX="${PWD}/install"] \
# [-DLLVM_MAJOR_VERSION_21_COMPATIBLE=ON] \
# [-DLLVM_ENABLE_ASSERTIONS=ON] \
# [-DMLIR_ENABLE_BINDINGS_PYTHON=ON] \
# [-DLLVM_TARGETS_TO_BUILD="host;Native"] \
# [-DBISHENGIR_PUBLISH=OFF] \
# [-DBISHENGIR_BUILD_TEMPLATE=ON -DBISHENG_COMPILER_PATH=/path/to/bisheng-compiler] \
# [-D其他选项=值]
ninja -j32
说明：
[]表示可选项。使用某选项时，去掉行首#和[]，将参数加入命令。
可选扩展参数：
可选参数 |
说明 |
|---|---|
|
安装路径 |
|
LLVM版本 ≥ 21时需添加 |
|
启用断言（Debug时常用） |
|
启用MLIR python-binding |
|
启用CPU runner |
|
关闭未发布功能 |
|
构建BiShengIR模板库 |
二进制安装（免编译）¶
AscendNPU IR二进制会随CANN Toolkit包一起安装，参见环境依赖准备中的“CANN包安装”内容。
直接使用Docker镜像¶
使用Docker镜像进行开发与验证，无需配置环境。
复用CANN镜像¶
CANN Toolkit包中会包含完整的AscendNPU IR二进制，Docker镜像可以复用CANN的镜像。
可以在https://quay.io/repository/ascend/cann?tab=tags中根据硬件平台和CANN版本查找相关的标签使用。例如ascend/cann:9.0.0-a3-openeuler24.03-py3.12
构建本地镜像¶
开发者也可以独立构建本地镜像，可参考docker目录中内置的不同架构的Dockerfile。
对于不同架构，均包含CANN Toolkit包与最新编译的AscendNPU IR。可自行安装ops包与Torch相关组件体验更多内容。
不同架构下的基础镜像信息为：
x86_64镜像：基于
ubuntu:22.04aarch64镜像：基于
openeuler/openeuler:24.03
构建方式：
# 构建x86_64镜像
docker build -t ascendnpu-ir:latest -f docker/Dockerfile.x86_64 .
使用镜像¶
IMAGE_NAME="ascendnpu-ir:latest" # CANN镜像可以为ascend/cann:9.0.0-a3-openeuler24.03-py3.12
# 进入后的环境可直接使用AscendNPU IR相关工具，如bisheng-compile等
docker run -it \
--net=host --privileged \ # 主机模式开发
--security-opt seccomp=unconfined \ # 关闭安全限制
--device=/dev/davinci0 \ # 挂载NPU设备
--device=/dev/davinci1 \
--device=/dev/davinci2 \
--device=/dev/davinci3 \
--device=/dev/davinci4 \
--device=/dev/davinci5 \
--device=/dev/davinci6 \
--device=/dev/davinci7 \
--device=/dev/davinci_manager \
--device=/dev/devmm_svm \
--device=/dev/hisi_hdc \
-v /usr/local/dcmi:/usr/local/dcmi \ # 挂载dcmi等设备
-v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
-v /usr/local/sbin/npu-smi:/usr/local/sbin/npu-smi \
-v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
-v /etc/ascend_install.info:/etc/ascend_install.info \
--name ascendnpu-ir \ # 容器名称
-v $(pwd):/workspace \ # 挂载当前目录到容器
-w /workspace \
$IMAGE_NAME /bin/bash
bishengir-compile --version # 可以看到AscendNPU IR的版本信息
运行测试¶
编译测试Target：
# 在 `build` 目录下
cmake --build . --target "check-mlir;check-bishengir"
该命令会执行check-mlir与check-bishengir，通过llvm-lit运行BiShengIR测试套。
典型输出示例：
测试通过时：
-- Testing: 388 tests, 8 workers --
...
Testing Time: 45.23s
Total Discovered Tests: 388
Unsupported: 89 (22.94%)
Passed : 299 (77.06%)
测试失败时：
-- Testing: 388 tests, 8 workers --
PASS: bishengir :: bishengir-compile/commandline.mlir (1 of 388)
...
FAIL: bishengir :: test/failing-case.mlir (42 of 388)
******************** TEST 'FAIL: bishengir :: test/failing-case1.mlir' FAILED ********************
...（失败详情）...
********************
FAIL: bishengir :: test/failing-case.mlir (256 of 388)
******************** TEST 'FAIL: bishengir :: test/failing-case2.mlir' FAILED ********************
...（失败详情）...
********************
********************
Failed Tests (2):
bishengir :: test/failing-case1.mlir
bishengir :: test/failing-case2.mlir
Testing Time: 38.12s
Total Discovered Tests: 388
Unsupported: 86 (22.16%)
Passed : 300 (77.32%)
Failed : 2 (0.52%)
...
测试通过判定：
测试通过：命令退出码为0，且
Failed为0。以下结果均计入通过：PASS：测试正常通过
UNSUPPORTED：当前环境不支持（如
UNSUPPORTED: bishengir_published）XFAIL：预期失败且实际失败
测试失败：命令退出码非0，或
Failed> 0。以下结果均计入失败：FAIL：测试执行失败
XPASS：预期失败但实际通过
UNRESOLVED：无法判定结果
TIMEOUT：超时
使用LLVM-LIT执行测试套：
# 在build目录下
./bin/llvm-lit ../bishengir/test
可直接指定测试路径，例如：./bin/llvm-lit ../bishengir/test/bishengir-compile/commandline.mlir。
常见问题¶
构建安装常见问题处理方式可参见FAQ-构建与安装