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.

Running Tests¶

Build Test Target¶

# From the build directory
cmake --build . --target "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).