安装指南#

本章节将引导你完成在本地机器上运行 cargo oxide run vecadd 所需的一切。

前提条件#

要求

版本

备注

Linux

Ubuntu 24.04 已测试

其他发行版可能可用，但未经测试

NVIDIA GPU

Ampere+ (sm_80+)

推荐驱动 545+

CUDA Toolkit

12.x+

必须能访问 nvcc 和 cuda.h

LLVM

21+

必须包含 NVPTX 后端

Clang

21+

clang-21——宿主 cuda-bindings 的 bindgen 需要

Rust

Nightly（固定版本）

在 rust-toolchain.toml 中固定

备注

cuda-oxide 目前仅支持 Linux。不支持 Windows。

开发容器#

仓库在 .devcontainer/ 中包含一个标准的 devcontainer 设置。使用它是获得可复现开发环境的最快方式，环境预装了 CUDA Toolkit 13.0、LLVM 21、Clang 21 和固定版本的 Rust nightly。

宿主机不需要安装 CUDA Toolkit。它需要：

  • 一块 NVIDIA GPU

  • 与 CUDA 13.0 兼容的 NVIDIA 驱动

  • 安装了 NVIDIA Container Toolkit 的 Docker

使用支持 devcontainer 的编辑器，打开仓库并在提示时选择"在容器中重新打开"。编辑器会读取 .devcontainer/devcontainer.json，构建镜像，使用 --gpus=all 请求 GPU 访问，并在容器内打开工作区。

对于纯 CLI 使用，用以下命令启动容器：

npx -y @devcontainers/cli up --workspace-folder .

然后在容器内运行命令：

npx -y @devcontainers/cli exec --workspace-folder . cargo oxide doctor
npx -y @devcontainers/cli exec --workspace-folder . cargo oxide run vecadd

如果宿主机驱动太旧，容器内的 GPU 命令（如 nvidia-smi、cargo oxide doctor 或 cargo oxide run vecadd）将会失败。请更新宿主机的 NVIDIA 驱动，而不是在容器内安装其他版本的 CUDA Toolkit。

如果你使用 devcontainer，可以跳过下面手动安装 CUDA、LLVM、Clang 和 Rust 的部分。

CUDA Toolkit#

从 NVIDIA CUDA 下载 页面安装 CUDA Toolkit，然后确保它在你的 PATH 中：

export PATH="/usr/local/cuda/bin:$PATH"

验证安装：

nvcc --version

小技巧

如果你将 CUDA 安装到了非默认位置，请设置 CUDA_TOOLKIT_PATH 为其根目录（即包含 include/cuda.h 的目录）。如果未设置，cuda-oxide 默认使用 /usr/local/cuda。

LLVM (21+)#

cuda-oxide 使用 LLVM 的 NVPTX 后端将 LLVM IR 降级为 PTX。安装 LLVM 21 或更高版本，并确保 llc-21（或 llc-22）在你的 PATH 中：

# 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 的一行。编译流水线按 llc-22、llc-21 的顺序自动探测；如果需要，可以通过 CUDA_OXIDE_LLC=/usr/bin/llc-21 指定特定的二进制文件。

警告

没有启用 NVPTX 后端的标准 LLVM 构建无法工作。llvm-21 Ubuntu 软件包默认包含它，但如果你从源码构建 LLVM，必须将 -DLLVM_TARGETS_TO_BUILD="X86;NVPTX" 传递给 CMake。

重要

为什么需要 LLVM 21？ 我们生成 TMA / tcgen05 / WGMMA 内部函数，LLVM 20 及更早版本的 llc 无法处理。简单的内核可能仍能在较旧的 llc 上运行（设置 CUDA_OXIDE_LLC=/path/to/llc-20），但任何 Hopper / Blackwell 的内核都需要 21+。

Clang（宿主 cuda-bindings）#

宿主 cuda-bindings crate 运行 bindgen，它在运行时加载 libclang.so，并且需要 clang 自身的 resource-dir 中的 stddef.h——仅靠 libclang1-* 运行时包是不够的。需要安装以下三个包：

sudo apt install libclang-21-dev libclang-cpp21-dev libclang-common-21-dev

cargo oxide doctor 会提前检测到这一点；如果缺失，症状是在宿主构建过程中出现 'stddef.h' file not found 错误。

备注

全新 Ubuntu 24.04 / DGX-OS： 如上所示通过 apt.llvm.org/llvm.sh 安装 LLVM 21 后，clang-21 / clang++-21 二进制文件存在，但 cargo oxide doctor 查找的无版本号别名不存在。请使用 update-alternatives 添加它们：

sudo update-alternatives --install /usr/bin/clang   clang   /usr/bin/clang-21   100
sudo update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-21 100

已在 Asus GX10 / NVIDIA DGX Spark 上验证。

Rust 工具链#

工作区附带一个 rust-toolchain.toml，固定了确切的 nightly 版本和所需组件。当你在仓库中首次运行任何 cargo 命令时，rustup 将自动安装正确的工具链。

如果你需要手动安装：

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

两个额外组件是代码生成后端所需的：

  • rust-src——Rust 标准库的源代码，用于交叉编译到 NVPTX 目标。

  • rustc-dev——编译器内部接口，后端链接时使用。

cargo-oxide#

cargo-oxide 是驱动整个构建流水线的 cargo 子命令（cargo oxide run、build、debug、pipeline 等）。

在 cuda-oxide 仓库内，它通过工作区别名直接可用——无需额外安装步骤。

在仓库外部使用（你自己的项目）：

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

首次运行时，cargo-oxide 会自动获取并构建代码生成后端。后续运行将复用缓存的构建。

验证安装#

运行内置的诊断检查：

cargo oxide doctor

cargo oxide doctor 一次性验证你的 Rust 工具链、CUDA toolkit（包括用于使用数学内部函数的内核所需的 libNVVM / nvJitLink / libdevice）、LLVM 安装和代码生成后端。

然后端到端构建并运行一个示例：

cargo oxide run vecadd

如果一切配置正确，这将把 Rust 内核编译为 PTX，在 GPU 上启动它，并打印成功消息。

小技巧

常见问题：

  • No working llc-21 or llc-22 found on PATH——安装 LLVM 21+（sudo apt install llvm-21），将 /usr/lib/llvm-21/bin 添加到 PATH，或设置 CUDA_OXIDE_LLC=/usr/bin/llc-21。

  • 构建宿主 cuda-bindings 时出现 'stddef.h' file not found——安装 clang 开发头文件：sudo apt install clang-21（或 libclang-common-21-dev）。

  • cuda.h not found——设置 CUDA_TOOLKIT_PATH 为你的 CUDA 安装根目录，或确保 /usr/local/cuda/include/cuda.h 存在。

  • rust-src component missing——运行 rustup component add rust-src --toolchain nightly-2026-04-03。