从源码构建#

本附录介绍从全新检出开始搭建 cuda-oxide 开发环境的步骤。如果你只想运行示例，可以阅读编写你的第一个内核章节，速度更快。

依赖要求#

依赖	版本	用途
Rust nightly	`nightly-2026-04-03`（锁定版本）	编译器工具链，代码生成后端需要 `rustc-dev` 组件
CUDA Toolkit	12.x+	Driver API、`nvcc`、PTX 汇编器
LLVM	21+（需启用 NVPTX 后端）	用于 LLVM IR → PTX 降层的 `llc-21`/`llc-22`
Clang	21+（`clang-21` 软件包）	宿主 `cuda-bindings` 中的 `bindgen` 需要 clang 的头文件
Linux	已在 Ubuntu 24.04 上测试	Windows 和 macOS 不受支持
GPU	sm_80, sm_90, sm_100a	硬件目标

克隆仓库#

git clone https://github.com/NVlabs/cuda-oxide.git
cd cuda-oxide

安装 Rust 工具链#

仓库中包含一个 rust-toolchain.toml 文件，锁定了确切的 nightly 版本和组件。 Rustup 会自动识别：

# rust-toolchain.toml (already in the repo root)
[toolchain]
channel = "nightly-2026-04-03"
components = ["rust-src", "rustc-dev", "rust-analyzer"]

如果需要手动安装：

rustup toolchain install nightly-2026-04-03
rustup component add rust-src rustc-dev --toolchain nightly-2026-04-03

rust-src 提供用于交叉编译的标准库源码；rustc-dev 暴露代码生成后端需要链接的编译器内部接口。

安装 CUDA#

确保 CUDA toolkit 在 PATH 中：

export PATH="/usr/local/cuda/bin:$PATH"
nvcc --version   # 应输出 12.x 或更高版本

如果在没有 GPU 的系统上构建（如 CI），仍然需要 toolkit 以获取 ptxas 和头文件，但无法运行内核。

安装 LLVM#

代码生成管线会生成 LLVM IR 并调用 llc 生成 PTX。需要 LLVM 21 或更高版本 ——更早的 llc 版本会拒绝 cuda-oxide 发出的 TMA / tcgen05 / WGMMA 内建函数签名。必须启用 NVPTX 后端：

# Ubuntu / Debian
sudo apt install llvm-21

如果你的发行版软件源未提供 llvm-21，可使用 LLVM 的 apt 辅助脚本：

sudo apt-get install -y lsb-release wget software-properties-common gnupg
wget https://apt.llvm.org/llvm.sh && chmod +x llvm.sh
sudo ./llvm.sh 21

# 验证 NVPTX 支持
llc-21 --version | grep nvptx

你应该能在目标列表中看到 nvptx64 - NVIDIA PTX 64-bit。管线会按 llc-22 → llc-21 的顺序自动搜索 PATH 中的二进制文件；如需锁定特定二进制文件，请设置 CUDA_OXIDE_LLC=/usr/bin/llc-21。

备注

较旧的 llc 二进制文件（LLVM 20 及更早版本）在通过 CUDA_OXIDE_LLC=/path/to/llc-20 指定时可以编译较简单的内核，但任何使用了现代 TMA / tcgen05 / WGMMA 内建函数（tma_copy、gemm_sol、 tcgen05_matmul、wgmma 等）的示例都会因 Intrinsic has incorrect argument type! 而失败，直到升级到 LLVM 21+。

安装 Clang（用于宿主 `cuda-bindings`）#

宿主 cuda-bindings crate 会运行 bindgen，后者加载 libclang 并需要 clang 自带的 resource-dir stddef.h——仅有 libclang1-* 运行时库是不够的。

sudo apt install clang-21   # 或 libclang-common-21-dev

cargo oxide doctor 会预先验证这一点。

构建工作区#

主工作区包含面向用户的 crate（cuda-device、cuda-core、 cuda-async 等）和构建工具（cargo-oxide）：

cargo build

备注

代码生成后端（crates/rustc-codegen-cuda/）有意不作为工作区成员，因为它需要特定的 nightly 特性和不同的构建流程。cargo-oxide 会透明地处理其构建。

安装 cargo-oxide#

cargo-oxide 是驱动完整编译管线的 cargo 子命令。在仓库内部，它通过工作区别名运行。独立使用：

cargo install --git https://github.com/NVlabs/cuda-oxide.git cargo-oxide

首次运行时，cargo-oxide 会自动获取并构建代码生成后端的 dylib。

验证安装#

# 检查所有前置条件
cargo oxide doctor

# 编译并运行标准入门示例
cargo oxide run vecadd

cargo oxide doctor 会验证 Rust 工具链、CUDA toolkit（包括使用数学内建函数的内核所需的 libNVVM / nvJitLink / libdevice）、LLVM 安装和代码生成后端。如果一切配置正确， cargo oxide run vecadd 会将 Rust 内核编译为 PTX，在 GPU 上启动执行，并输出成功消息。

常用命令#

# 构建并运行示例
cargo oxide run <example>

# 显示完整编译管线（MIR → LLVM IR → PTX）
cargo oxide pipeline <example>

# 使用 cuda-gdb 调试
cargo oxide debug <example> --tui

# 构建 NVVM IR 以用于 libNVVM/nvJitLink 互操作
cargo oxide build <example> --emit-nvvm-ir --arch sm_120

构建本书#

文档位于 cuda-oxide-book/ 目录，使用 Sphinx 和 MyST Markdown。本地构建和预览：

cd cuda-oxide-book
make setup      # 创建虚拟环境，安装依赖
source .venv/bin/activate
make livehtml   # 在 http://localhost:8000 启动开发服务器

生成 API 文档#

标准 cargo doc 适用于工作区 crate：

cargo doc --no-deps --open

这会为 cuda-device、cuda-core、cuda-async 及所有其他工作区成员生成 rustdoc。代码生成后端由于不是工作区成员而被排除在外。

工作区结构#

cuda-oxide/
├── Cargo.toml              # 工作区根文件
├── rust-toolchain.toml     # 锁定的 nightly 版本 + 组件
├── crates/
│   ├── cuda-device/          # 设备端内建函数 (#![no_std])
│   ├── cuda-host/            # 宿主端 launch API
│   ├── cuda-macros/          # 过程宏 (#[kernel], #[device], gpu_printf!)
│   ├── cuda-bindings/        # 对 cuda.h 的原始 bindgen FFI
│   ├── cuda-core/            # 安全的 RAII 封装器 (CudaContext, DeviceBuffer)
│   ├── cuda-async/           # 异步执行 (DeviceOperation, DeviceFuture)
│   ├── cargo-oxide/          # Cargo 子命令
│   ├── rustc-codegen-cuda/   # 代码生成后端（非工作区成员）
│   ├── mir-importer/         # MIR → Pliron IR 转换
│   ├── mir-lower/            # `dialect-mir` → `dialect-llvm` 降层
│   ├── dialect-mir/          # 对 Rust MIR 建模的 pliron 方言
│   ├── dialect-llvm/         # 对 LLVM IR 建模的 pliron 方言（+ 导出）
│   ├── dialect-nvvm/         # NVVM 内建函数方言
│   ├── libnvvm-sys/          # libNVVM 的 dlopen 绑定
│   ├── nvjitlink-sys/        # nvJitLink 的 dlopen 绑定
│   ├── reserved-oxide-symbols/ # 共享命名约定
│   └── fuzzer/               # 差分测试支持
└── cuda-oxide-book/        # 本书（Sphinx + MyST）

故障排查#

找不到 llc 或缺少 NVPTX 支持: 确保已安装 LLVM 21+ 且 llc-21（或 llc-22）在 PATH 中。管线按 llc-22 → llc-21 的顺序查找；也可以设置 CUDA_OXIDE_LLC=/usr/bin/llc-21 来指定特定二进制文件。
Intrinsic has incorrect argument type!（来自 llc）: 你的 llc 版本低于 LLVM 21，无法降层现代 TMA / tcgen05 / WGMMA 内建函数签名。请安装 llvm-21 并重新运行。
error[E0463]: can't find crate for rustc_middle: 缺少 rustc-dev 组件。运行： rustup component add rustc-dev --toolchain nightly-2026-04-03。
CUDA 驱动版本不匹配: toolkit 版本（编译时）和驱动版本（运行时）必须兼容。运行 nvidia-smi 检查驱动版本，运行 nvcc --version 检查 toolkit 版本。
cargo oxide doctor 在代码生成后端检查上失败: 后端在首次使用时构建。如果构建失败，请检查 rust-src 是否已安装，以及 nightly 版本是否与 rust-toolchain.toml 匹配。