# Build from Source

This page builds Triton-distributed-ascend and its two native dependencies. It assumes you
have already completed [Installation](installation.md), including sourcing CANN's
`set_env.sh`.

There are four steps, in order:

1. Build LLVM (optional, only when no compatible prebuilt LLVM is available)
2. Build Triton-distributed-ascend
3. Build and install AscendNPU-IR
4. Build and install shmem

Steps 3 and 4 are not optional. AscendNPU-IR provides the compiler backend that lowers
kernels to the NPU, and shmem provides the device-side communication runtime. Without both,
the package imports but no distributed kernel will run.

```{note}
Every step below needs the CANN environment. Source it once per shell:
`source /usr/local/Ascend/ascend-toolkit/set_env.sh`
```

## 1. Build LLVM (optional)

Skip this step unless the build reports that no compatible prebuilt LLVM is available, or
you specifically need a custom LLVM. Building LLVM takes a long time and a lot of disk
space.

### Check out the pinned revision

The revision and patch are pinned. Using a different LLVM commit will not work.

```bash
git clone --no-checkout https://github.com/llvm/llvm-project.git
cd llvm-project
git checkout f6ded0be897e2878612dd903f7e8bb85448269e5
wget https://raw.githubusercontent.com/triton-lang/triton-ascend/2e69438a0a41a00ab72c7d46b44d97092cf2362c/third_party/ascend/patch/llvm_patch_f6ded0b.patch
git apply llvm_patch_f6ded0b.patch
```

### Install Clang and LLD

Clang and LLD 15 or later are recommended:

```bash
apt-get install -y clang-15 lld-15 ccache
```

### Configure and build

Set the install prefix, then build:

```bash
export LLVM_INSTALL_PREFIX={PATH_TO}/llvm-install
```

```bash
cd {PATH_TO}/llvm-project
mkdir build
cd build
cmake ../llvm \
  -G Ninja \
  -DCMAKE_C_COMPILER=/usr/bin/clang-15 \
  -DCMAKE_CXX_COMPILER=/usr/bin/clang++-15 \
  -DCMAKE_LINKER=/usr/bin/lld-15 \
  -DCMAKE_BUILD_TYPE=Release \
  -DLLVM_ENABLE_ASSERTIONS=ON \
  -DLLVM_ENABLE_PROJECTS="mlir;llvm;lld" \
  -DLLVM_TARGETS_TO_BUILD="host;NVPTX;AMDGPU" \
  -DLLVM_ENABLE_LLD=ON \
  -DCMAKE_INSTALL_PREFIX=${LLVM_INSTALL_PREFIX}
ninja install
```

### Copy the test tools

`ninja install` does not install `FileCheck` and `llvm-lit`, but the build expects them:

```bash
cp {PATH_TO}/llvm-project/build/bin/FileCheck ${LLVM_INSTALL_PREFIX}/bin/FileCheck
cp {PATH_TO}/llvm-project/build/bin/llvm-lit ${LLVM_INSTALL_PREFIX}/bin/llvm-lit
```

Pass `LLVM_SYSPATH=${LLVM_INSTALL_PREFIX}` to the build in the next step to use this LLVM.

## 2. Build Triton-distributed-ascend

### Clone and initialize submodules

Submodules are initialized in two stages: the outer repository first, then the nested
submodules inside `3rdparty/triton-ascend`.

```bash
git clone https://gitcode.com/Ascend/Triton-distributed-ascend.git
cd Triton-distributed-ascend

git submodule update --init --depth=1
cd 3rdparty/triton-ascend
git submodule update --init --depth=1
cd ../../
```

### Build and install

```bash
TRITON_USE_ASCEND=ON \
TRITON_BUILD_WITH_CLANG_LLD=ON \
TRITON_BUILD_PROTON=OFF \
TRITON_BUILD_LITTLE_KERNEL=OFF \
pip install ./python --no-build-isolation
```

If you built a custom LLVM in step 1, prepend `LLVM_SYSPATH=${LLVM_INSTALL_PREFIX}`.

```{note}
`--no-build-isolation` is required. The build reads the torch and pybind11 installs from
your environment, and an isolated build environment would not have them.
```

### Alternative build commands

For an editable install, which is what you want when working on the Python sources:

```bash
TRITON_USE_ASCEND=ON \
TRITON_BUILD_WITH_CLANG_LLD=ON \
TRITON_BUILD_PROTON=OFF \
TRITON_BUILD_LITTLE_KERNEL=OFF \
pip install -e ./python --verbose --no-build-isolation
```

To produce a wheel instead of installing:

```bash
TRITON_USE_ASCEND=ON \
TRITON_BUILD_WITH_CLANG_LLD=ON \
TRITON_BUILD_PROTON=OFF \
TRITON_BUILD_LITTLE_KERNEL=OFF \
pip wheel ./python --no-build-isolation
```

### Build options

| Variable | Meaning |
| --- | --- |
| `TRITON_USE_ASCEND=ON` | Build against triton-ascend instead of upstream Triton. Required. |
| `TRITON_BUILD_WITH_CLANG_LLD=ON` | Use Clang and LLD for linking |
| `TRITON_BUILD_PROTON=OFF` | Disable the Proton profiler build |
| `TRITON_BUILD_LITTLE_KERNEL=OFF` | Disable the mega-kernel build |
| `TRITON_PLUGIN_DIRS` | Path to the Triton plugin directory |
| `LLVM_SYSPATH` | Path to a custom LLVM install, from step 1 |

## 3. Build and install AscendNPU-IR

AscendNPU-IR is a separate repository. Clone it outside the Triton-distributed-ascend tree.

```bash
source /usr/local/Ascend/ascend-toolkit/set_env.sh
git clone https://gitcode.com/Ascend/AscendNPU-IR.git
cd AscendNPU-IR
git submodule update --init --depth=1
mkdir build
./build-tools/build.sh -o ./build -t --build-type Release \
  --apply-patches \
  --bisheng-compiler=$ASCEND_HOME_PATH/bin \
  --build-shmem-template
```

`--bisheng-compiler` points at the Bisheng compiler that ships with CANN, which is why
`ASCEND_HOME_PATH` must be set. If it is empty, source `set_env.sh` again.

The build produces binaries in `AscendNPU-IR/build/bin`, which must be on your `PATH` at
runtime:

```bash
export PATH={PATH_TO}/AscendNPU-IR/build/bin:$PATH
```

Add this to your shell profile so it persists across sessions.

## 4. Build and install shmem

shmem lives in the repository as a submodule and provides the device-side communication
runtime.

```bash
source /usr/local/Ascend/ascend-toolkit/set_env.sh
cd Triton-distributed-ascend/3rdparty/shmem/
bash scripts/build.sh -python_extension
pip install dist/shmem-*.whl
```

The `-python_extension` flag builds the Python extension and produces a wheel in `dist/`.

For Ascend 950 hardware, add the SOC type:

```bash
bash scripts/build.sh -python_extension -soc_type Ascend950
```

```{note}
The default build targets the Ascend910B backend, which covers the A2 and A3 series.
Run `bash scripts/build.sh --help` to see the other options, including RDMA support.
```

## Verifying the build

Check that the package and the communication runtime both import:

```bash
python -c "import triton_dist; print(triton_dist.__file__)"
python -c "import shmem; print('shmem ok')"
```

Then run the Ascend unit tests, from the repository root:

```bash
pytest python/triton_dist/test/ascend/ -m dist
```

These tests exercise the communication primitives directly (barriers, wait/notify, symmetric
memory addressing, put/get) and need at least two NPUs.

## Troubleshooting

**`ASCEND_HOME_PATH` is empty.** You did not source `set_env.sh` in the current shell, or
CANN is installed somewhere other than `/usr/local/Ascend`. Adjust the path and source it
again.

**Build fails looking for LLVM.** No compatible prebuilt LLVM was found for your platform.
Build LLVM using step 1 and pass `LLVM_SYSPATH`.

**`import triton_dist` succeeds but kernels fail to compile.** The AscendNPU-IR binaries are
probably not on `PATH`. Confirm with `which` against a binary in
`AscendNPU-IR/build/bin`.

**Missing torch or pybind11 during the build.** You likely dropped
`--no-build-isolation`, or `pip install -r requirements.txt` was not run.

## Next steps

- [Quick Start](quick-start.md) to run your first distributed kernel.