# 从源码构建

本页介绍如何构建 Triton-distributed-ascend 及其两个原生依赖项。假设你已经完成
[安装](installation.md)，包括 source CANN 的 `set_env.sh`。

构建共分四步，按顺序执行：

1. 构建 LLVM（可选，仅当没有兼容的预编译 LLVM 时）
2. 构建 Triton-distributed-ascend
3. 构建并安装 AscendNPU-IR
4. 构建并安装 shmem

第 3 步和第 4 步是必需的。AscendNPU-IR 提供将 kernel 降低到 NPU 的编译器后端，shmem
提供设备侧通信运行时。缺少任何一个，软件包虽然能够导入但无法运行分布式 kernel。

```{note}
以下每一步都需要 CANN 环境。每个 shell 都需要 source 一次：
`source /usr/local/Ascend/ascend-toolkit/set_env.sh`
```

## 1. 构建 LLVM（可选）

除非构建过程报告没有兼容的预编译 LLVM，或者你确实需要自定义 LLVM，否则可以跳过本步骤。
构建 LLVM 耗时很长且占用大量磁盘空间。

### 检出固定的版本

版本与补丁均已固定。使用其他 LLVM commit 将无法正常工作。

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

### 安装 Clang 与 LLD

建议使用 Clang 和 LLD 15 或更高版本：

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

### 配置并构建

设置安装前缀，然后构建：

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

### 拷贝测试工具

`ninja install` 不会安装 `FileCheck` 和 `llvm-lit`，但构建过程需要它们：

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

在下一步构建时通过 `LLVM_SYSPATH=${LLVM_INSTALL_PREFIX}` 使用此 LLVM。

## 2. 构建 Triton-distributed-ascend

### 克隆并初始化子模块

子模块分两个阶段初始化：先初始化外层仓库，然后再初始化 `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 ../../
```

### 构建并安装

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

如果在第 1 步中构建了自定义 LLVM，请添加 `LLVM_SYSPATH=${LLVM_INSTALL_PREFIX}`。

```{note}
必须使用 `--no-build-isolation`。构建过程需要从你的环境中读取 torch 和 pybind11，
隔离的构建环境中不会有这些依赖。
```

### 其他构建命令

如需可编辑安装（在修改 Python 源码时使用）：

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

仅生成 wheel 包而不安装：

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

### 构建选项

| 变量 | 含义 |
| --- | --- |
| `TRITON_USE_ASCEND=ON` | 使用 triton-ascend 而非上游 Triton 构建。必需。 |
| `TRITON_BUILD_WITH_CLANG_LLD=ON` | 使用 Clang 和 LLD 进行链接 |
| `TRITON_BUILD_PROTON=OFF` | 禁用 Proton profiler 构建 |
| `TRITON_BUILD_LITTLE_KERNEL=OFF` | 禁用 mega-kernel 构建 |
| `TRITON_PLUGIN_DIRS` | Triton 插件目录路径 |
| `LLVM_SYSPATH` | 自定义 LLVM 安装路径，来自第 1 步 |

## 3. 构建并安装 AscendNPU-IR

AscendNPU-IR 是独立的仓库。请在 Triton-distributed-ascend 目录树之外克隆它。

```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` 指向 CANN 附带的毕昇编译器，因此 `ASCEND_HOME_PATH` 必须已设置。
如果该变量为空，请重新 source `set_env.sh`。

构建会在 `AscendNPU-IR/build/bin` 中生成二进制文件，运行时必须将其加入 `PATH`：

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

请将其加入 shell 配置文件以便在多个会话间持久化。

## 4. 构建并安装 shmem

shmem 位于仓库的子模块中，提供设备侧通信运行时。

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

`-python_extension` 标志会构建 Python 扩展并在 `dist/` 中生成 wheel 包。

对于昇腾 Ascend 950 硬件，需添加 SOC 类型：

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

```{note}
默认构建面向 Ascend910B 后端，覆盖 A2 和 A3 系列。运行 `bash scripts/build.sh --help`
可查看其他选项，包括 RDMA 支持。
```

## 验证构建

检查软件包与通信运行时能否正常导入：

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

然后从仓库根目录运行昇腾单元测试：

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

这些测试直接验证通信原语（barrier、wait/notify、对称内存寻址、put/get），需要至少两张 NPU。

## 故障排查

**`ASCEND_HOME_PATH` 为空。** 你没有在当前 shell 中 source `set_env.sh`，或者 CANN
安装在 `/usr/local/Ascend` 以外的位置。调整路径后重新 source。

**构建时找不到 LLVM。** 你的平台没有兼容的预编译 LLVM。请按第 1 步构建 LLVM 并传入
`LLVM_SYSPATH`。

**`import triton_dist` 成功但 kernel 编译失败。** AscendNPU-IR 二进制文件可能不在
`PATH` 中。用 `which` 检查 `AscendNPU-IR/build/bin` 中的某个二进制文件。

**构建时缺少 torch 或 pybind11。** 你可能丢掉了 `--no-build-isolation`，或者没有运行
`pip install -r requirements.txt`。

## 后续步骤

- [快速开始](quick-start.md)：运行你的第一个分布式 kernel。