# 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

1. Clone the repository (then enter the repo directory, typically `ascendnpu-ir`).

    ```bash
    git clone https://gitcode.com/Ascend/ascendnpu-ir.git
    cd ascendnpu-ir
    ```

2. 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.

    ```bash
    # 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.

1. Download CANN: obtain the toolkit package and the ops package for your hardware from the [Ascend CANN download page](https://www.hiascend.com/cann/download).

2. Install CANN:

    ```bash
    # 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}]
    ```

3. Set environment variables:

    ```bash
    # 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):

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

**Subsequent builds** (when build directory already exists):

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

**Rebuild** (clean build directory and reconfigure):

```bash
./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

```bash
# 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`).

```bash
# 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](#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](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:

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

### Image Usage

```bash
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

```bash
# 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**:

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

Testing Time: 45.23s

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

**When tests fail**:

```text
-- 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

```bash
# 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:

```bash
 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).