Build and Installation¶

This document describes dependency installation, build methods (source and binary), and running tests for AscendNPU IR.

Install Dependencies¶

Build Dependencies¶

Compiler and Toolchain Requirements¶

Minimum requirements:

CMake >= 3.28
Ninja >= 1.12.0

Recommended:

Clang >= 10
LLD >= 10 (LLVM LLD significantly speeds up builds)

Source Preparation¶

Clone the repository (then enter the repo directory, typically ascendnpu-ir).
```
git clone https://gitcode.com/Ascend/ascendnpu-ir.git
cd ascendnpu-ir
```
Initialize and update submodules.

The project depends on LLVM, Torch-MLIR, and other third-party libraries; submodules must be fetched and updated to the specified commit IDs.
```
# Recursively init and update all submodules
git submodule update --init --recursive
```

Runtime Dependencies¶

CANN Package Installation¶

End-to-end runs depend on the CANN environment.

Download CANN: obtain the toolkit package and the ops package for your hardware from the Ascend CANN download page.

Install CANN:

# Example: x86 A3, {version} is CANN version, e.g. 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}]

Set environment variables:

# For version 8.5.0 and earlier, use ${PATH-TO-CANN}/ascend-toolkit/set_env.sh
source ${PATH-TO-CANN}/cann/set_env.sh

Build Commands¶

Source Build¶

Using the Build Script (Recommended)¶

Run ./build-tools/build.sh from the repo root to configure, build, and install. The script handles CMake configuration, Ninja build, and installation.

First build (requires submodule init and patch application):

# From the repo root
./build-tools/build.sh -o ./build --build-type Release --apply-patches

Subsequent builds (when build directory already exists):

./build-tools/build.sh -o ./build --build-type Release

Rebuild (clean build directory and reconfigure):

./build-tools/build.sh -o ./build --build-type Release -r

Script Options¶

Option	Description	Default
`-o`, `--build PATH`	Build output directory	`./build`
`--build-type TYPE`	Build type	`Release`
`--apply-patches`	Apply patches to third-party submodules; required on first build	Off
`-r`, `--rebuild`	Clean build directory and reconfigure	Off
`-j`, `--jobs N`	Parallel build threads	3/4 of CPU cores
`--install-prefix PATH`	Install path	`BUILD_DIR/install`
`--c-compiler PATH`	C compiler path	`clang`
`--cxx-compiler PATH`	C++ compiler path	`clang++`
`--llvm-source-dir DIR`	LLVM source directory	`third-party/llvm-project`
`--build-test`	Build and run tests	Off
`--build-bishengir-doc`	Build BiShengIR documentation	Off
`-t`, `--build-bishengir-template`	Build BiShengIR template; requires CANN 9.0.0 to enable this option, required for E2E cases	Off
`--bisheng-compiler PATH`	Path to bisheng compiler; required when building template	None
`--build-torch-mlir`	Also build torch-mlir	Off
`--python-binding`	Enable MLIR python-binding	Off
`--enable-cpu-runner`	Enable CPU runner	Off
`--disable-ccache`	Disable ccache	On (if installed)
`--enable-assertion`	Enable assertions	Off
`--fast-build`	Skip installation step	Off
`--add-cmake-options OPTIONS`	Append CMake options	None

Common Examples¶

# Debug build with tests
./build-tools/build.sh -o ./build --build-type Debug --apply-patches --build-test

# Specify compiler and thread count
./build-tools/build.sh -o ./build --c-compiler /usr/bin/clang-15 --cxx-compiler /usr/bin/clang++-15 -j 256

# Fast build (skip install)
./build-tools/build.sh -o ./build --fast-build

# Rebuild and build template (E2E cases require the template library)
./build-tools/build.sh -r -o ./build --fast-build -t --bisheng-compiler=/usr/Ascend/cann/bin

Manual Build (Advanced)¶

For full manual control, follow these steps.

Prerequisites: submodule init (git submodule update --init --recursive) and patch application (source build-tools/apply_patches.sh).

# From the repo root
mkdir -p build
cd build

# LLVM source path: 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] \
    # [-Dother-options=value]

ninja -j32

Note: [] indicates optional options. To use an option, remove the leading # and [], and add the argument to the command.

Optional Option	Description
`-DCMAKE_INSTALL_PREFIX="${PWD}/install"`	Install path
`-DLLVM_MAJOR_VERSION_21_COMPATIBLE=ON`	Required when LLVM >= 21
`-DLLVM_ENABLE_ASSERTIONS=ON`	Enable assertions (common for Debug)
`-DMLIR_ENABLE_BINDINGS_PYTHON=ON`	Enable MLIR python-binding
`-DLLVM_TARGETS_TO_BUILD="host;Native"`	Enable CPU runner
`-DBISHENGIR_PUBLISH=OFF`	Disable unpublished features
`-DBISHENGIR_BUILD_TEMPLATE=ON -DBISHENG_COMPILER_PATH=...`	Build BiShengIR template

Binary Installation¶

AscendNPU IR binaries are installed with the CANN toolkit; see CANN Package Installation above.

Using Docker Images¶

Use Docker images for development and verification without environment configuration.

Reuse CANN Image¶

The CANN toolkit package includes complete AscendNPU IR binaries, and you can reuse the CANN Docker image.

Find relevant tags based on hardware platform and CANN version at https://quay.io/repository/ascend/cann?tab=tags. For example: ascend/cann:9.0.0-a3-openeuler24.03-py3.12

Build Local Image¶

Developers can also build local images using the architecture-specific Dockerfiles in the docker directory. All architectures include the Ascend CANN Toolkit package and the latest compiled AscendNpu IR. Install ops packages and Torch-related components to explore more features.

Base image information for different architectures:

x86_64: Based on ubuntu:22.04
aarch64: Based on openeuler/openeuler:24.03

Build command:

# Build x86_64 image
docker build -t ascendnpu-ir:latest -f docker/Dockerfile.x86_64 .

Image Usage¶

IMAGE_NAME="ascendnpu-ir:latest"      # CANN image can be `ascend/cann:9.0.0-a3-openeuler24.03-py3.12`
# The environment inside provides direct access to AscendNPU-IR tools such as bisheng-compile
docker run -it \
  --net=host --privileged \            # Host mode for development
  --security-opt seccomp=unconfined \  # Disable security restrictions
  --device=/dev/davinci0 \             # Mount NPU devices
  --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 \ # Mount dcmi and other devices
  -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   \              # Container name
  -v $(pwd):/workspace  \              # Mount current directory to container
  -w /workspace         \
  $IMAGE_NAME  /bin/bash

bishengir-compile --version # View AscendNPU IR version information

Running Tests¶

Build Test Target¶

# From the build directory
cmake --build . --target "check-mlir;check-bishengir"

This runs check-mlir and check-bishengir, executing the BiShengIR test suite via llvm-lit.

Typical Output¶

When tests pass:

-- Testing: 388 tests, 8 workers --
...

Testing Time: 45.23s

Total Discovered Tests: 388
  Unsupported: 89  (22.94%)
  Passed     : 299 (77.06)

When tests fail:

-- 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 ********************
...(failure details)...

********************
FAIL: bishengir :: test/failing-case.mlir (256 of 388)
******************** TEST 'FAIL: bishengir :: test/failing-case2.mlir' FAILED ********************
...(failure details)...

********************
********************
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%)
  ...

Test Pass Criteria¶

Pass: Exit code 0 and Failed is 0. The following count as pass:

PASS: Test passed
UNSUPPORTED: Not supported in current environment (e.g. UNSUPPORTED: bishengir_published)
XFAIL: Expected to fail and did fail

Fail: Non-zero exit code or Failed > 0. The following count as fail:

FAIL: Test failed
XPASS: Expected to fail but passed
UNRESOLVED: Result could not be determined
TIMEOUT: Timed out

Run Tests with LLVM LIT¶

# From the build directory
./bin/llvm-lit ../bishengir/test

You can specify a test path, e.g. ./bin/llvm-lit ../bishengir/test/bishengir-compile/commandline.mlir.

FAQ¶

Q: When building with build-tools/build.sh, I get “ninja: error: loading ‘build.ninja’: No such file or directory”. What should I do? A: Add the -r option to rerun CMake and regenerate build.ninja.

Q: Build fails with “Too many open files”. What should I do? A: The number of open files exceeded the system limit. Raise the per-process open-file limit, e.g. ulimit -n 65535.

Q: Build fails with:

 The CMAKE_CXX_COMPILER:

  clang++

 is not a full path and was not found in the PATH.

What should I do? A: The C++ compiler was not specified or the compiler binary is invalid. First try specifying the compiler with --cxx-compiler=${CXX-COMPILER-PATH}. If the error persists after specifying the compiler, reinstall or use another version (e.g. the recommended clang++-15).