如何用 cuda-oxide 建立 Rust GPU 核心
這篇教你在 Linux 上安裝 cuda-oxide 所需工具鏈，並成功編譯與執行第一個 Rust GPU 核心。
這篇教你在 Linux 上安裝 cuda-oxide 所需工具鏈，並成功編譯與執行第一個 Rust GPU 核心。
這篇給想用 Rust 直接寫 NVIDIA GPU 核心的開發者，不必先切到 C++ 或另外學一套 DSL。照著做完，你會拿到可運作的本機環境，能把 Rust 核心編成 PTX，跑完 vecadd 範例，並看懂整個編譯流程。
這是一篇可直接照做的操作指南，每一步都會有明確產出，方便你逐項驗收。你會先確認 CUDA、LLVM、Clang 與 Rust 夜版，再把專案與 cargo 指令裝好，最後跑出第一個 GPU 核心。
開始之前
訂閱 AI 趨勢週報
每週精選模型發布、工具應用與深度分析，直送信箱。不定期，不騷擾。
不會寄垃圾信，隨時可取消。
- 作業系統：Linux，建議 Ubuntu 24.04
- Rust：nightly-2026-04-03，並安裝 rust-src、rustc-dev
- CUDA：CUDA Toolkit 12.x
- LLVM：LLVM 21，且要有 NVPTX backend
- Clang：Clang 21 或 libclang-common-21-dev
- 其他：Git、NVIDIA GPU、可用的 CUDA 驅動程式
Step 1: 檢查 CUDA 與 GPU 環境
目的：先確認機器已經有可用的 NVIDIA 驅動與 CUDA 工具鏈，避免後面編譯到一半才發現硬體或版本不相容。cuda-oxide 需要 Linux 上的 CUDA 環境，且 LLVM 21 才能完整支援較新的 GPU 功能。
nvcc --version
nvidia-smi
llc-21 --version | grep nvptx驗收：你應該看到 nvcc 顯示 CUDA Toolkit 12.x，nvidia-smi 列出你的 GPU，llc-21 的輸出中出現 NVPTX。若沒有 NVPTX，先補裝含 GPU backend 的 LLVM，再往下做。
Step 2: 安裝指定的 Rust 夜版
目的：讓 Rust 編譯器版本和專案期待一致，這樣自訂 codegen backend 才能正常掛進 rustc。這個專案使用夜版 Rust，並鎖定 nightly-2026-04-03 以確保可重現建置。
rustup toolchain install nightly-2026-04-03
rustup component add rust-src rustc-dev --toolchain nightly-2026-04-03
rustup show驗收：你應該看到 nightly-2026-04-03 已安裝，且 rust-src 與 rustc-dev 都在該工具鏈底下。若少了 rustc-dev，後續 backend 會無法使用編譯器內部 API。
Step 3: 安裝 LLVM 21 與 Clang 21
目的：提供 cuda-oxide 需要的 llc 與標頭檔，讓中間表示能順利轉成 PTX。專案會先產生 LLVM IR，再交給 llc，另外 bindgen 也需要 Clang 的資源標頭。
sudo apt update
sudo apt install llvm-21 clang-21 libclang-common-21-dev
llc-21 --version | grep nvptx
clang-21 --version驗收：你應該看到 LLVM 21 與 Clang 21 的版本資訊，並且 llc-21 輸出裡有 NVPTX。若之後 bindgen 找不到 stddef.h，通常代表你只裝到執行階段套件，沒有裝完整的 Clang 標頭。
Step 4: 下載專案並安裝 cargo-oxide
目的：把原始碼與 cargo 子指令準備好，讓 Cargo 能把核心建置流程交給 cuda-oxide。這個專案會用 cargo oxide build、run、debug 和 pipeline 來串起 Rust 到 PTX 的整段流程。
git clone https://github.com/NVlabs/cuda-oxide.git
cd cuda-oxide
cargo install --git https://github.com/NVlabs/cuda-oxide.git cargo-oxide
cargo oxide doctor驗收：你應該看到 cargo-oxide 安裝成功，接著 doctor 會檢查 Rust、CUDA、LLVM、Clang 與 backend 檔案。只要 doctor 有任何紅字，就先修好再往下編譯核心。
Step 5: 執行 vecadd 範例核心
目的：用官方範例驗證整條路徑都通了，包含主機端程式、裝置端 PTX 與 CUDA 驅動載入。vecadd 會在 GPU 上把 1,024 個 f32 數值相加，再回到主機端驗證結果。
cargo oxide run vecadd驗收：你應該看到成功訊息，表示 1,024 個元素全部正確。這代表主機程式已啟動、裝置程式已編成 PTX，而且 CUDA 驅動也成功載入核心。
Step 6: 檢視 Rust 到 PTX 的編譯流程
目的：確認 cuda-oxide 不是只給你結果，而是真的經過各階段轉換，方便你之後除錯或調校編譯器行為。這一步能讓你看到 Stable MIR、Pliron、LLVM IR 與 PTX 的每一段輸出。
cargo oxide pipeline vecadd
cargo oxide debug vecadd --tui驗收：你應該看到從 Rust MIR、dialect-mir、mem2reg、dialect-llvm、LLVM IR 到 PTX 的階段追蹤。debug 指令若能開啟 TUI，表示專案也能把裝置端除錯流程交給 cuda-gdb。
| 指標 | 基準／優化前 | 結果／優化後 |
|---|---|---|
| 編譯目標 | Rust 原始碼搭配獨立 CUDA 流程 | 單一來源 Rust 同時輸出主機二進位與 PTX |
| 核心建置路徑 | C++/CUDA 或 DSL 包裝層 | Rust 核心直接編譯成 PTX |
| 工具鏈需求 | 混合 Rust、C++、CUDA 工具 | Rust 夜版、LLVM 21、Clang 21、CUDA Toolkit 12.x+ |
常見錯誤
- LLVM 版本太舊。修法：改裝 LLVM 21 以上，並確認 llc-21 --version 有 NVPTX。
- 只裝了 libclang 執行階段套件。修法：改裝 clang-21 或 libclang-common-21-dev，讓 bindgen 找得到資源標頭。
- 沒有使用指定夜版或缺少 rustc-dev。修法：切到 nightly-2026-04-03，並用 rustup 補上 rust-src 與 rustc-dev。
接下來可以看什麼
當 vecadd 能跑之後，下一步可以自己寫一個 #[kernel] 函式，再用 cargo oxide pipeline 觀察單型別化後的 Rust、裝置內建函式與 barrier 語意如何一路保留到 PTX。接著再往 cuda-device crate、編譯器 backend 原始碼與更完整的 Rust GPU 生態延伸。