Build from Source

This page builds Triton-distributed-ascend and its two native dependencies. It assumes you have already completed Installation, including sourcing CANN’s set_env.sh.

Manual Build Steps

If you prefer manual control or need to customize the build, follow the four steps below:

  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

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.

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:

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

Configure and build

Set the install prefix, then build:

export LLVM_INSTALL_PREFIX={PATH_TO}/llvm-install

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:

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.

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.

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

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 earlier, 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:

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:

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 (see Build LLVM)

Build and install AscendNPU-IR

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

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:

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

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

Build and install shmem

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

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 950PR&950DT products, add the SOC type:

bash scripts/build.sh -python_extension -soc_type Ascend950

Note

The default build targets the Ascend910B backend, which covers Atlas A3 products and Atlas A2 products. 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:

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:

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 following the Build LLVM section 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