From 61a8db1e01cd7d38b2aaec79b61302b0052edd1e Mon Sep 17 00:00:00 2001 From: nihalpasham Date: Fri, 23 Oct 2026 13:10:03 +0530 Subject: [PATCH 1/4] docs(cuda-oxide): update remaining nightly references and doctor check for 1.99.1 - Update the root `README.md`, umbrella `docs/index.md`, `building-from-source.md`, `error-handling-and-debugging.md`, crate READMEs (`cargo-oxide`, `cuda-oxide-codegen`, `cute-rs`, `ctm-rs`, `cute-layout`), workspace manifests, and CI/script comments to describe the pinned stable `1.99.1` toolchain rather than a nightly pin. - Update `cargo oxide doctor` (`doctor.rs`) so step 1 checks `rustc --version` without requiring the string `"nightly"` (step 2 already verifies the active toolchain against `rust-toolchain.toml`). Signed-off-by: nihalpasham --- .github/workflows/clippy.yml | 2 +- .github/workflows/fmt.yml | 4 +-- Cargo.toml | 2 +- README.md | 4 +-- cuda-oxide/Cargo.toml | 5 ++-- cuda-oxide/crates/cargo-oxide/README.md | 12 ++++----- cuda-oxide/crates/cargo-oxide/src/backend.rs | 2 +- .../crates/cargo-oxide/src/commands/doctor.rs | 12 +++------ cuda-oxide/crates/cuda-host/src/lib.rs | 8 +++--- .../crates/cuda-oxide-codegen/README.md | 2 +- .../crates/cuda-oxide-codegen/src/lib.rs | 2 +- .../crates/rustc-codegen-cuda/Cargo.toml | 2 +- .../appendix/building-from-source.md | 15 ++++++----- .../error-handling-and-debugging.md | 26 +++++++++---------- cuda-oxide/cute-rs-preview/ctm-rs/README.md | 2 +- .../cute-rs-preview/cute-layout/README.md | 2 +- cuda-oxide/cute-rs-preview/cute-rs/README.md | 2 +- cuda-oxide/scripts/check-book-import-order.sh | 2 +- .../scripts/check-dependency-licenses.sh | 2 +- cuda-oxide/scripts/smoketest.sh | 2 +- docs/index.md | 11 ++++---- rust-toolchain.toml | 4 +-- 22 files changed, 61 insertions(+), 64 deletions(-) diff --git a/.github/workflows/clippy.yml b/.github/workflows/clippy.yml index 24655cfa24..b11f5374cf 100644 --- a/.github/workflows/clippy.yml +++ b/.github/workflows/clippy.yml @@ -49,7 +49,7 @@ jobs: # Point all of those invocations at one shared CARGO_TARGET_DIR under # ${RUNNER_TEMP}. Cargo fingerprints each unit by package + features # + workspace_root + toolchain, so co-located workspaces using the - # same pinned nightly deduplicate on identical deps and compile each + # same pinned toolchain deduplicate on identical deps and compile each # one once. This is intentionally scoped *not* to cover the # `cargo clippy --workspace` step above, which already has a # well-defined `target/` under cuda-oxide. diff --git a/.github/workflows/fmt.yml b/.github/workflows/fmt.yml index 40a946953e..33ba68059d 100644 --- a/.github/workflows/fmt.yml +++ b/.github/workflows/fmt.yml @@ -20,7 +20,7 @@ jobs: # rustfmt comes from cuda-oxide/rust-toolchain.toml's component list, # like clippy, - # so `cargo fmt` resolves against the same nightly as the rest of CI. + # so `cargo fmt` resolves against the same toolchain as the rest of CI. - name: Check stable host workspace formatting run: cargo fmt --all -- --check @@ -61,7 +61,7 @@ jobs: example_dir="$(dirname "$manifest")" echo "::group::cargo fmt --check ($example_dir)" # Run inside the component so rustup discovers CUDA Oxide's - # directory-scoped nightly pin. + # directory-scoped toolchain pin. (cd "$example_dir" && cargo fmt -- --check) echo "::endgroup::" done diff --git a/Cargo.toml b/Cargo.toml index e27f86ecc4..efd77cfc1c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,7 +3,7 @@ resolver = "3" members = [ # Stable host-side crates shared by the Tile and SIMT components. # Package metadata and dependencies stay in each crate so this workspace - # does not impose CUDA Oxide's nightly toolchain or edition. + # does not impose CUDA Oxide's workspace toolchain pin or edition. "cuda-bindings", "cuda-core", "cuda-core-derive", diff --git a/README.md b/README.md index ecbfb2d9bc..9fe71ec86b 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ shape its direction by sharing feedback on your experience. | Safety | Data-race freedom for disjoint slice accesses; you control thread synchronization and shared memory | Data-race freedom by construction within a kernel: no explicit thread indexing, shared memory, or synchronization | | Indexing | Explicit thread/block indices | Implicit via partitions | | Compiles | Ahead of time, Rust → PTX | JIT at first launch, Rust → Tile IR → cubin | -| Toolchain | Pinned nightly, managed by `cargo oxide` | Stable Rust 1.89 or newer | +| Toolchain | Pinned stable Rust (`1.99.1`), managed by `cargo oxide` | Stable Rust 1.89 or newer | | Portability | Produces PTX that the driver compiles for compatible GPUs; you control tuning per GPU | CUDA architecture-agnostic; the compiler tunes per GPU | | Reach for it when | You need direct control over threads, warps, shared memory, TMA, or cluster ops | Your problem is naturally expressed as tensor computations and you want the compiler to handle scheduling details | @@ -81,7 +81,7 @@ are documented in the cutile-rs book. ## Contributing -See [CONTRIBUTING.md](CONTRIBUTING.md) for commit sign-off requirements, pull requests, and CI. Toolchain requirements differ between the two: cutile-rs builds on stable Rust, cuda-oxide needs its pinned nightly via `cargo oxide`; each book covers its own. +See [CONTRIBUTING.md](CONTRIBUTING.md) for commit sign-off requirements, pull requests, and CI. Both components build on stable Rust and pin their toolchains in their respective `rust-toolchain.toml` files (with `rustc-dev` and `llvm-tools` for `cuda-oxide`, managed via `cargo oxide`); each book covers its own setup. ## License diff --git a/cuda-oxide/Cargo.toml b/cuda-oxide/Cargo.toml index 0854cb991d..ec0021d2eb 100644 --- a/cuda-oxide/Cargo.toml +++ b/cuda-oxide/Cargo.toml @@ -47,8 +47,9 @@ authors = ["Nihal Pasham "] license = "Apache-2.0" repository = "https://github.com/NVIDIA/cuda-rust" -# Note: crates/rustc-codegen-cuda is NOT a workspace member because it requires -# special rustc nightly features and a different build process. +# Note: crates/rustc-codegen-cuda is NOT a workspace member because it links +# against rustc_private (via rustc-dev and RUSTC_BOOTSTRAP=1) and uses a +# separate build process. # Build and run examples with: cargo oxide run # Examples are in: crates/rustc-codegen-cuda/examples/ and cute-rs-preview/examples/ # Complete model workloads are in: cute-rs-preview/models/ diff --git a/cuda-oxide/crates/cargo-oxide/README.md b/cuda-oxide/crates/cargo-oxide/README.md index f9158e3c39..4ffdbedffc 100644 --- a/cuda-oxide/crates/cargo-oxide/README.md +++ b/cuda-oxide/crates/cargo-oxide/README.md @@ -452,7 +452,7 @@ merged repository it also formats the parent shared-host workspace. With ### `cargo oxide doctor` -Validates that your environment is correctly set up: Rust nightly toolchain, +Validates that your environment is correctly set up: pinned Rust toolchain, CUDA headers (`cuda.h`), CUDA toolkit (`nvcc`, libNVVM, nvJitLink, libdevice), LLVM (`llc`), clang/libclang, the NVIDIA driver / GPU, and the codegen backend `.so`. Optional probes cover `cuda-gdb` (for `debug`) and @@ -510,11 +510,11 @@ Cargo.lock cuda-device = git+https://github.com/NVIDIA/cuda-rust.git# The kernels compile against the crates at that commit and the backend that lowers them is built from the same commit, so the two cannot drift. Changing the dependency (`cargo update`, a new `rev = ...`) rebuilds the cache on the -next build. The checkout's `rust-toolchain.toml` names the nightly that commit -needs; if the project pins a different one, the build stops before compiling -and tells you which channel to set. A path dependency on a local checkout -builds in place, like step 3. Projects with no cuda-oxide dependency fall back -to a one-time clone of `main`. The backend's build tree lives at +next build. The checkout's `rust-toolchain.toml` names the toolchain channel +that commit needs; if the project pins a different one, the build stops before +compiling and tells you which channel to set. A path dependency on a local +checkout builds in place, like step 3. Projects with no cuda-oxide dependency +fall back to a one-time clone of `main`. The backend's build tree lives at `~/.cargo/cuda-oxide/target` (shared by every commit's builds; delete it to reclaim the space). diff --git a/cuda-oxide/crates/cargo-oxide/src/backend.rs b/cuda-oxide/crates/cargo-oxide/src/backend.rs index 37d63ebea1..ffee12453e 100644 --- a/cuda-oxide/crates/cargo-oxide/src/backend.rs +++ b/cuda-oxide/crates/cargo-oxide/src/backend.rs @@ -813,7 +813,7 @@ fn report_unhealable_toolchain_mismatch(current: &str, recorded: &str) { toolchain_identity_line(recorded) ); eprintln!( - "Your project's rust-toolchain.toml pins a different nightly than the \ + "Your project's rust-toolchain.toml pins a different toolchain than the \ cuda-oxide backend source it depends on. Align the pins (and run \ `cargo oxide update` after changing them), or point CUDA_OXIDE_BACKEND \ at a backend built with your project's toolchain." diff --git a/cuda-oxide/crates/cargo-oxide/src/commands/doctor.rs b/cuda-oxide/crates/cargo-oxide/src/commands/doctor.rs index 143d7e979b..cec6417c35 100644 --- a/cuda-oxide/crates/cargo-oxide/src/commands/doctor.rs +++ b/cuda-oxide/crates/cargo-oxide/src/commands/doctor.rs @@ -360,7 +360,7 @@ pub(super) fn backend_source_check( /// Validate the development environment. /// -/// Checks for: Rust nightly toolchain, `rust-toolchain.toml`, the codegen +/// Checks for: Rust toolchain (`rustc`), `rust-toolchain.toml`, the codegen /// backend `.so` (informational), CUDA headers (`cuda.h`), CUDA toolkit /// (`nvcc`, libNVVM, nvJitLink, libdevice), LLVM (`llc`), clang/libclang, /// the NVIDIA driver / GPU (informational), and optionally `cuda-gdb` / @@ -379,17 +379,11 @@ pub fn doctor(ctx: &Context) { let mut ok = true; // 1. Rust toolchain - print!("Rust nightly toolchain... "); + print!("Rust toolchain... "); match Command::new("rustc").args(["--version"]).output() { Ok(output) if output.status.success() => { let version = String::from_utf8_lossy(&output.stdout); - let version = version.trim(); - if version.contains("nightly") { - println!("✓ {}", version); - } else { - println!("✗ expected nightly, got: {}", version); - ok = false; - } + println!("✓ {}", version.trim()); } _ => { println!("✗ rustc not found"); diff --git a/cuda-oxide/crates/cuda-host/src/lib.rs b/cuda-oxide/crates/cuda-host/src/lib.rs index 5e6a866a7a..2e5505cdbe 100644 --- a/cuda-oxide/crates/cuda-host/src/lib.rs +++ b/cuda-oxide/crates/cuda-host/src/lib.rs @@ -10,10 +10,10 @@ // that would silently reject non-`'static` borrowing closures). // // We accept the `internal_features` warning here: cuda-oxide already ships -// `rustc_codegen_cuda` against `rustc_private` and pins a nightly -// toolchain, so the broader project is firmly inside rustc's internal API -// surface. Anyone trying to lift this helper to a stable crate will hit -// the same gate and have to make the same trade-off there. +// `rustc_codegen_cuda` against `rustc_private` and pins its Rust toolchain +// with `RUSTC_BOOTSTRAP=1`, so the broader project is firmly inside rustc's +// internal API surface. Anyone trying to lift this helper to a standalone +// crate will hit the same gate and have to make the same trade-off there. #![feature(core_intrinsics)] #![allow(internal_features)] diff --git a/cuda-oxide/crates/cuda-oxide-codegen/README.md b/cuda-oxide/crates/cuda-oxide-codegen/README.md index 9ac68d1d56..db30c9df38 100644 --- a/cuda-oxide/crates/cuda-oxide-codegen/README.md +++ b/cuda-oxide/crates/cuda-oxide-codegen/README.md @@ -8,7 +8,7 @@ lowering, and LLVM tooling as the rustc frontend uses. The only supported public surface is the `experimental` module. The point is the absence of a dependency: this crate has **no rustc linkage**. -It needs neither `rustc_private` nor a nightly toolchain matched to +It needs neither `rustc_private` nor a toolchain pin matched to `rustc_driver`, so a caller that can build the IR itself can reach PTX without the compiler-plugin machinery `rustc-codegen-cuda` requires. diff --git a/cuda-oxide/crates/cuda-oxide-codegen/src/lib.rs b/cuda-oxide/crates/cuda-oxide-codegen/src/lib.rs index 682d9c2fc1..ba090dc822 100644 --- a/cuda-oxide/crates/cuda-oxide-codegen/src/lib.rs +++ b/cuda-oxide/crates/cuda-oxide-codegen/src/lib.rs @@ -11,7 +11,7 @@ //! the rustc frontend. //! //! This crate intentionally has no rustc linkage. It does not require -//! `rustc_private` or a nightly toolchain matched to `rustc_driver`. +//! `rustc_private` or a toolchain pin matched to `rustc_driver`. #![warn(missing_docs)] diff --git a/cuda-oxide/crates/rustc-codegen-cuda/Cargo.toml b/cuda-oxide/crates/rustc-codegen-cuda/Cargo.toml index c20211c939..67b39a8c36 100644 --- a/cuda-oxide/crates/rustc-codegen-cuda/Cargo.toml +++ b/cuda-oxide/crates/rustc-codegen-cuda/Cargo.toml @@ -12,7 +12,7 @@ readme = "README.md" [lib] crate-type = ["dylib"] -# Keep out of workspace - requires special nightly build +# Keep out of workspace - links against rustc_private (rustc-dev) [workspace] [dependencies] diff --git a/cuda-oxide/cuda-oxide-book/appendix/building-from-source.md b/cuda-oxide/cuda-oxide-book/appendix/building-from-source.md index 13f9b29936..f3049e37b5 100644 --- a/cuda-oxide/cuda-oxide-book/appendix/building-from-source.md +++ b/cuda-oxide/cuda-oxide-book/appendix/building-from-source.md @@ -138,7 +138,7 @@ crates (`cuda-device`, `cuda-host`, `cuda-macros`, etc.) and the build tooling (`cargo-oxide`). The host runtime (`cuda-bindings`, `cuda-core`, `cuda-async`) is shared with cutile-rs and lives at the repository root; the SIMT workspace depends on those crates by path. This section, "Verify the installation", and -"Common commands" run from `cuda-oxide/`, where the nightly pin and the +"Common commands" run from `cuda-oxide/`, where the SIMT toolchain pin and the `cargo oxide` workspace alias apply: ```bash @@ -148,8 +148,9 @@ cargo build ```{note} The codegen backend (`cuda-oxide/crates/rustc-codegen-cuda/`) is intentionally **not** a -workspace member because it requires special nightly features and a different -build process. `cargo-oxide` handles building it transparently. +workspace member because it links against `rustc_private` (via `rustc-dev` and +`RUSTC_BOOTSTRAP=1`) and uses a separate build process. `cargo-oxide` handles +building it transparently. ``` ## Install cargo-oxide @@ -248,8 +249,8 @@ repository/ ├── cuda-async/ # Shared async runtime ├── cutile-rs/ # Tile DSL (nested import) └── cuda-oxide/ - ├── Cargo.toml # Nightly SIMT workspace - ├── rust-toolchain.toml # Pinned nightly + components + ├── Cargo.toml # SIMT workspace + ├── rust-toolchain.toml # Pinned stable toolchain (1.99.1) + components ├── crates/ │ ├── cuda-device/ # Device intrinsics (#![no_std]) │ ├── cuda-host/ # Host launch APIs @@ -295,5 +296,5 @@ CUDA driver version mismatch `cargo oxide doctor` fails on codegen backend : The backend is built on first use. If the build fails, check that - `rust-src` is installed and that the nightly version matches - `rust-toolchain.toml`. + `rust-src` and `rustc-dev` are installed and that the active toolchain + matches `rust-toolchain.toml`. diff --git a/cuda-oxide/cuda-oxide-book/gpu-programming/error-handling-and-debugging.md b/cuda-oxide/cuda-oxide-book/gpu-programming/error-handling-and-debugging.md index 56038c8a42..f48e28e4b5 100644 --- a/cuda-oxide/cuda-oxide-book/gpu-programming/error-handling-and-debugging.md +++ b/cuda-oxide/cuda-oxide-book/gpu-programming/error-handling-and-debugging.md @@ -488,19 +488,19 @@ cargo oxide doctor Doctor checks: -| Check | What it verifies | -|:----------------|:-----------------------------------------------| -| Rust toolchain | Nightly compiler with required components | -| Codegen backend | `librustc_codegen_cuda.so` built | -| CUDA headers | `cuda.h` present under the toolkit root | -| CUDA toolkit | `nvcc` found and version compatible | -| libNVVM | `libnvvm.so` loadable (libdevice math kernels) | -| nvJitLink | `libnvJitLink.so` loadable (same) | -| libdevice | `libdevice.10.bc` discoverable (same) | -| LLVM | `llc` (21+) available for PTX generation | -| Driver / GPU | `nvidia-smi` reports a GPU and its compute cap | -| cuda-gdb | Optional; only needed for `cargo oxide debug` | -| compute-sanitizer | Optional; only needed for `cargo oxide sanitize` | +| Check | What it verifies | +|:----------------|:----------------------------------------------------| +| Rust toolchain | Pinned compiler (`1.99.1`) with required components | +| Codegen backend | `librustc_codegen_cuda.so` built | +| CUDA headers | `cuda.h` present under the toolkit root | +| CUDA toolkit | `nvcc` found and version compatible | +| libNVVM | `libnvvm.so` loadable (libdevice math kernels) | +| nvJitLink | `libnvJitLink.so` loadable (same) | +| libdevice | `libdevice.10.bc` discoverable (same) | +| LLVM | `llc` (21+) available for PTX generation | +| Driver / GPU | `nvidia-smi` reports a GPU and its compute cap | +| cuda-gdb | Optional; only needed for `cargo oxide debug` | +| compute-sanitizer | Optional; only needed for `cargo oxide sanitize` | The libNVVM / nvJitLink / libdevice checks fire only when a kernel calls CUDA libdevice math (`sin`, `cos`, `exp`, `pow`, `sqrt`, ...). If your diff --git a/cuda-oxide/cute-rs-preview/ctm-rs/README.md b/cuda-oxide/cute-rs-preview/ctm-rs/README.md index 7638278a7a..bc0d05e732 100644 --- a/cuda-oxide/cute-rs-preview/ctm-rs/README.md +++ b/cuda-oxide/cute-rs-preview/ctm-rs/README.md @@ -76,7 +76,7 @@ expansions name it. ## Check -From `cuda-oxide/` with its pinned nightly: +From `cuda-oxide/` with its pinned toolchain: ```sh cargo test -p ctm-rs --all-targets diff --git a/cuda-oxide/cute-rs-preview/cute-layout/README.md b/cuda-oxide/cute-rs-preview/cute-layout/README.md index 2dca9aab98..d5795d4b10 100644 --- a/cuda-oxide/cute-rs-preview/cute-layout/README.md +++ b/cuda-oxide/cute-rs-preview/cute-layout/README.md @@ -36,7 +36,7 @@ documented arithmetic and shape preconditions. ## Validation -Run from `cuda-oxide/` with its pinned nightly: +Run from `cuda-oxide/` with its pinned toolchain: ```sh cargo test -p cute-layout diff --git a/cuda-oxide/cute-rs-preview/cute-rs/README.md b/cuda-oxide/cute-rs-preview/cute-rs/README.md index bb30b41a2d..4e33bdedf2 100644 --- a/cuda-oxide/cute-rs-preview/cute-rs/README.md +++ b/cuda-oxide/cute-rs-preview/cute-rs/README.md @@ -34,7 +34,7 @@ items are the `epilogue::sm120` items. ## Checks -Run from the `cuda-oxide/` workspace with its pinned nightly: +Run from the `cuda-oxide/` workspace with its pinned toolchain: ```sh cargo test -p cute-rs --no-default-features diff --git a/cuda-oxide/scripts/check-book-import-order.sh b/cuda-oxide/scripts/check-book-import-order.sh index 142078265a..9f8a98017f 100755 --- a/cuda-oxide/scripts/check-book-import-order.sh +++ b/cuda-oxide/scripts/check-book-import-order.sh @@ -37,7 +37,7 @@ # surface in the same way and stay out. # # rustfmt comes from rust-toolchain.toml's component list, through the rustup -# proxy, so the order checked here is the order the pinned nightly writes. +# proxy, so the order checked here is the order the pinned toolchain writes. # `--edition 2024` matches the edition `cargo oxide new` scaffolds; under 2021 # rustfmt keeps the old case-insensitive order and this guard would say # nothing. A `use` line rustfmt cannot parse is reported too: a reader pastes diff --git a/cuda-oxide/scripts/check-dependency-licenses.sh b/cuda-oxide/scripts/check-dependency-licenses.sh index 778581f439..0d6d3f96c8 100755 --- a/cuda-oxide/scripts/check-dependency-licenses.sh +++ b/cuda-oxide/scripts/check-dependency-licenses.sh @@ -106,7 +106,7 @@ print("\n".join(sorted(names))) # here matters: # # 1. Cargo.toml -- the stable shared-host workspace. -# 2. cuda-oxide/Cargo.toml -- the nightly SIMT workspace. +# 2. cuda-oxide/Cargo.toml -- the SIMT workspace. # 3. cuda-oxide/crates/rustc-codegen-cuda/Cargo.toml -- its own `[workspace]` for the # rustc-private dylibs, so `-p` from the root cannot reach it and the root # `cargo metadata` stops at that boundary. That is how the backend crate diff --git a/cuda-oxide/scripts/smoketest.sh b/cuda-oxide/scripts/smoketest.sh index 35d8eb57a2..1872145b16 100755 --- a/cuda-oxide/scripts/smoketest.sh +++ b/cuda-oxide/scripts/smoketest.sh @@ -2423,7 +2423,7 @@ run_tilelib() { # dominant cost of this script. Point all example builds at one shared # CARGO_TARGET_DIR: cargo fingerprints each unit by package + features + # workspace_root + toolchain, so identical deps built with the same pinned -# nightly + backend RUSTFLAGS compile exactly once and are reused across every +# toolchain + backend RUSTFLAGS compile exactly once and are reused across every # example. (Same trick the clippy CI job uses for these workspaces.) # # The codegen backend .so is built FIRST, with CARGO_TARGET_DIR explicitly diff --git a/docs/index.md b/docs/index.md index 5b4c2e154f..6b01f4e8a7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -41,7 +41,7 @@ shape its direction by sharing feedback on your experience. | Safety | Data-race freedom for disjoint slice accesses; you control thread synchronization and shared memory | Data-race freedom by construction within a kernel: no explicit thread indexing, shared memory, or synchronization | | Indexing | Explicit thread/block indices | Implicit via partitions | | Compiles | Ahead of time, Rust → PTX | JIT at first launch, Rust → Tile IR → cubin | -| Toolchain | Pinned nightly, managed by `cargo oxide` | Stable Rust 1.89 or newer | +| Toolchain | Pinned stable Rust (`1.99.1`), managed by `cargo oxide` | Stable Rust 1.89 or newer | | Portability | Produces PTX that the driver compiles for compatible GPUs; you control tuning per GPU | CUDA architecture-agnostic; the compiler tunes per GPU | | Reach for it when | You need direct control over threads, warps, shared memory, TMA, or cluster ops | Your problem is naturally expressed as tensor computations and you want the compiler to handle scheduling details | @@ -67,7 +67,7 @@ Disjoint slices give each thread exclusive access to its own elements, preventin when launch geometry matches the kernel's contract. You control how threads synchronize and use shared memory. -Kernels compile ahead of time from Rust to PTX using a pinned nightly toolchain managed by `cargo oxide`. +Kernels compile ahead of time from Rust to PTX using a pinned stable Rust toolchain (`1.99.1`) managed by `cargo oxide`. You have direct control over how your kernels are tuned for each GPU architecture. Choose between Tile and SIMT based on [each kernel's requirements](https://docs.nvidia.com/cuda/cuda-programming-guide/01-introduction/programming-model.html#relationship-to-simt-programming). @@ -96,9 +96,10 @@ guides, and reference material. The runtime crates (`cuda-bindings`, ## Contributing See [CONTRIBUTING.md](https://github.com/NVIDIA/cuda-rust/blob/main/CONTRIBUTING.md) -for commit sign-off requirements, pull requests, and CI. Toolchain requirements -differ between the two: cutile-rs builds on stable Rust, cuda-oxide needs its -pinned nightly via `cargo oxide`; each book covers its own. +for commit sign-off requirements, pull requests, and CI. Both components build +on stable Rust and pin their toolchains in their respective `rust-toolchain.toml` +files (with `rustc-dev` and `llvm-tools` for `cuda-oxide`, managed via +`cargo oxide`); each book covers its own setup. ```{toctree} :maxdepth: 2 diff --git a/rust-toolchain.toml b/rust-toolchain.toml index 9ba4c5ed89..0724b3bf69 100644 --- a/rust-toolchain.toml +++ b/rust-toolchain.toml @@ -1,7 +1,7 @@ # Stable pin for the git-root host workspace (cuda-bindings, cuda-core, # cuda-core-derive, cuda-async). rustup walks up from the working directory, -# so `cargo` at the git root must not inherit the Oxide nightly under -# cuda-oxide/. Keep this channel in lockstep with cutile-rs/rust-toolchain.toml. +# so `cargo` at the git root does not inherit `cuda-oxide/rust-toolchain.toml`. +# Keep this channel in lockstep with cutile-rs/rust-toolchain.toml. [toolchain] channel = "1.98.0" components = ["rustfmt", "clippy"] From 4f412322f9ce6a449d02dbdbb29fb53605f2e5e4 Mon Sep 17 00:00:00 2001 From: nihalpasham Date: Fri, 23 Oct 2026 08:49:11 +0000 Subject: [PATCH 2/4] docs(cute-rs): one Python setup for the comparison examples and models Every cute-rs README that runs a CuTeDSL comparison now gives the same three-line setup: install the CUTLASS compiler, create cute-rs-preview/.venv, and install cute-rs-preview/requirements.txt. The per-example requirements files include the shared one, so the DSL 4.7.0 family (SM120a prefill and decode, SM100 FMHA prefill, SM100 MLA decode, fp16_gemm) shares a single environment. The blockscale references keep their own pins. The runners agree on where to look: --python where it exists, CUDA_OXIDE_CUTE_PYTHON, the example's .venv, the shared cute-rs-preview/.venv, then python3. The SM100 runners no longer fall back to the fp16_gemm venv, and fp16_gemm's automatic setup creates the shared environment instead of a local one. Each comparison script checks for numpy, torch, cutlass and cuda before any GPU work and prints the setup commands when they are missing, instead of a traceback after the Rust build. The Rust-only READMEs name the `cargo oxide toolchain install cutlass` step inline, and the devcontainer installs python3-venv so the setup works there. Signed-off-by: nihalpasham Co-Authored-By: Claude Fable 5.1 --- cuda-oxide/.devcontainer/Dockerfile | 1 + .../examples/ffn_cute/README.md | 4 +- .../fmha_decode_sm120a_cute/README.md | 12 +++--- .../reference/README.md | 8 ++-- .../reference/requirements.txt | 7 ++-- .../fmha_prefill_sm120a_cute/README.md | 12 +++--- .../fmha_prefill_sm120a_cute/compare.py | 14 +++++++ .../reference/README.md | 9 +++-- .../reference/requirements.txt | 8 ++-- .../examples/fp16_gemm_256x352_ctm/README.md | 19 ++++++---- .../examples/fp16_gemm_256x352_cute/README.md | 15 +++++--- .../fp16_gemm_256x352_cute/compare.py | 10 +++-- .../public_reference/README.md | 32 +++++++--------- .../public_reference/requirements.txt | 6 +-- .../public_reference/test_setup.py | 38 +++++++++---------- .../fp16_gemm_256x352_cute/setup_reference.py | 18 +++++---- .../fp16_gemm_256x352_cute/src/main.rs | 2 +- .../fp16_gemm_256x352_cute/src/python.rs | 36 +++++++++++++++++- .../examples/rmsnorm_cute/README.md | 4 +- .../examples/rope_cache_cute/README.md | 4 +- .../sm100_fmha_prefill_cute/README.md | 11 +++++- .../sm100_fmha_prefill_cute/compare.py | 14 +++++++ .../reference/README.md | 26 ++++++------- .../reference/requirements.txt | 9 +---- .../sm100_fmha_prefill_cute/src/main.rs | 6 +-- .../sm100_mla_decode_fp16_cute/README.md | 11 +++++- .../sm100_mla_decode_fp16_cute/compare.py | 22 +++++++++-- .../reference/README.md | 14 ++++--- .../reference/requirements.txt | 9 +---- .../src/comparison.rs | 6 +-- .../examples/swiglu_cute/README.md | 4 +- .../models/qwen3_8b_cute/README.md | 12 +++++- .../models/qwen_decoder_cute/README.md | 2 +- cuda-oxide/cute-rs-preview/requirements.txt | 13 +++++++ 34 files changed, 260 insertions(+), 158 deletions(-) create mode 100644 cuda-oxide/cute-rs-preview/requirements.txt diff --git a/cuda-oxide/.devcontainer/Dockerfile b/cuda-oxide/.devcontainer/Dockerfile index a92200f9ea..fa16226542 100644 --- a/cuda-oxide/.devcontainer/Dockerfile +++ b/cuda-oxide/.devcontainer/Dockerfile @@ -28,6 +28,7 @@ RUN apt-get update \ pkg-config \ python3 \ python3-pip \ + python3-venv \ xz-utils \ && curl -fsSL https://apt.llvm.org/llvm-snapshot.gpg.key \ | gpg --dearmor -o /usr/share/keyrings/apt.llvm.org.gpg \ diff --git a/cuda-oxide/cute-rs-preview/examples/ffn_cute/README.md b/cuda-oxide/cute-rs-preview/examples/ffn_cute/README.md index 0ecb3375c1..cb6847c581 100644 --- a/cuda-oxide/cute-rs-preview/examples/ffn_cute/README.md +++ b/cuda-oxide/cute-rs-preview/examples/ffn_cute/README.md @@ -25,8 +25,8 @@ input work and completes all four kernels before returning. ## Run it -From `cuda-oxide/`, with the pinned toolchain, CUDA toolkit, CUTLASS compiler, -and an RTX 5090: +From `cuda-oxide/`, with the pinned toolchain, CUDA toolkit, the CUTLASS compiler +(`cargo oxide toolchain install cutlass`) and an RTX 5090: ```bash CUDA_OXIDE_DEVICE_BACKEND=cutlass-mlir \ diff --git a/cuda-oxide/cute-rs-preview/examples/fmha_decode_sm120a_cute/README.md b/cuda-oxide/cute-rs-preview/examples/fmha_decode_sm120a_cute/README.md index cd13041d97..6aeeab2f70 100644 --- a/cuda-oxide/cute-rs-preview/examples/fmha_decode_sm120a_cute/README.md +++ b/cuda-oxide/cute-rs-preview/examples/fmha_decode_sm120a_cute/README.md @@ -17,12 +17,12 @@ Q/K/V tensor views → typed copies → FP32 dot products and local softmax - The cache contains only visible tokens. Cache management, paging and grouped-query attention are outside this example. -From `cuda-oxide/`, install CUTLASS 4.7 (`cargo oxide toolchain install cutlass`) -and prepare the shared Python environment once for prefill and decode: +From `cuda-oxide/`, once per checkout: ```bash +cargo oxide toolchain install cutlass python3 -m venv cute-rs-preview/.venv -cute-rs-preview/.venv/bin/python -m pip install -r cute-rs-preview/examples/fmha_prefill_sm120a_cute/reference/requirements.txt +cute-rs-preview/.venv/bin/pip install -r cute-rs-preview/requirements.txt ``` Compare runtime and static specialization on RTX 5090: @@ -45,10 +45,8 @@ Add `--json PATH` to save the comparison, `--iters 0` to verify without timing, or `--rust-only` for a standalone Rust report. `--all-cases` cannot be combined with `--rust-only`. Pass `--help` after `--` for all options. -The comparison needs CUDA-enabled PyTorch and CUTLASS DSL 4.7; see -[reference setup](reference/README.md). The shared virtualenv is found -automatically. Use `--python PATH` to select another interpreter and -`--device N` to select another visible GPU; device 0 is the default. +Use `--python PATH` to select another interpreter and `--device N` to select +another visible GPU; device 0 is the default. The CuTeDSL reference is independently authored here using the same split-KV algorithm; it is **not an upstream CUTLASS decode kernel**. diff --git a/cuda-oxide/cute-rs-preview/examples/fmha_decode_sm120a_cute/reference/README.md b/cuda-oxide/cute-rs-preview/examples/fmha_decode_sm120a_cute/reference/README.md index b2bacf016c..90dcf19022 100644 --- a/cuda-oxide/cute-rs-preview/examples/fmha_decode_sm120a_cute/reference/README.md +++ b/cuda-oxide/cute-rs-preview/examples/fmha_decode_sm120a_cute/reference/README.md @@ -18,16 +18,16 @@ stride and merge bounds dynamic. The comparison requires the same effective mode on both sides, so neither compiler receives an extra shape advantage. Use `nvidia-cutlass-dsl[cu13]==4.7.0` with a compatible CUDA-enabled PyTorch -build and driver. `requirements.txt` pins the DSL; dependencies retain their -own licenses. All code in this directory has the indicated first-party -Apache-2.0 license. +build and driver. The shared [`requirements.txt`](../../../requirements.txt) +pins the DSL; dependencies retain their own licenses. All code in this +directory has the indicated first-party Apache-2.0 license. Prepare the shared Python environment once for both prefill and decode, from `cuda-oxide/`: ```bash python3 -m venv cute-rs-preview/.venv -cute-rs-preview/.venv/bin/python -m pip install -r cute-rs-preview/examples/fmha_prefill_sm120a_cute/reference/requirements.txt +cute-rs-preview/.venv/bin/pip install -r cute-rs-preview/requirements.txt ``` Select a CUDA-enabled PyTorch build that supports SM120 and matches your CUDA diff --git a/cuda-oxide/cute-rs-preview/examples/fmha_decode_sm120a_cute/reference/requirements.txt b/cuda-oxide/cute-rs-preview/examples/fmha_decode_sm120a_cute/reference/requirements.txt index 9591ba71e7..b2cb40f71c 100644 --- a/cuda-oxide/cute-rs-preview/examples/fmha_decode_sm120a_cute/reference/requirements.txt +++ b/cuda-oxide/cute-rs-preview/examples/fmha_decode_sm120a_cute/reference/requirements.txt @@ -1,5 +1,4 @@ -# Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 - -nvidia-cutlass-dsl[cu13]==4.7.0 -torch +# This comparison uses the shared environment pinned in cute-rs-preview/requirements.txt. +-r ../../../requirements.txt diff --git a/cuda-oxide/cute-rs-preview/examples/fmha_prefill_sm120a_cute/README.md b/cuda-oxide/cute-rs-preview/examples/fmha_prefill_sm120a_cute/README.md index 332b4e3aaf..fefed1881e 100644 --- a/cuda-oxide/cute-rs-preview/examples/fmha_prefill_sm120a_cute/README.md +++ b/cuda-oxide/cute-rs-preview/examples/fmha_prefill_sm120a_cute/README.md @@ -13,12 +13,12 @@ Q/K/V tensor views → typed shared-memory copies → warp MMA fragments equal query/KV lengths; `--noncausal` permits unequal lengths and `Sq=1`. - Runtime shapes are the default. `--shape-mode static` requires **Sq=Sk=1024, H=8**. -From `cuda-oxide/`, install CUTLASS 4.7 (`cargo oxide toolchain install cutlass`) -and prepare the shared Python environment once for prefill and decode: +From `cuda-oxide/`, once per checkout: ```bash +cargo oxide toolchain install cutlass python3 -m venv cute-rs-preview/.venv -cute-rs-preview/.venv/bin/python -m pip install -r cute-rs-preview/examples/fmha_prefill_sm120a_cute/reference/requirements.txt +cute-rs-preview/.venv/bin/pip install -r cute-rs-preview/requirements.txt ``` Compare all four cases on RTX 5090: @@ -41,10 +41,8 @@ comparison, `--iters 0` to verify without timing, or `--rust-only` for a standal Rust report. `--all-cases` cannot be combined with `--rust-only`. Pass `--help` after `--` for all options. -The comparison needs CUDA-enabled PyTorch and CUTLASS DSL 4.7; see -[reference setup](reference/README.md). The shared virtualenv is found -automatically. Use `--python PATH` to select another interpreter and -`--device N` to select another visible GPU; device 0 is the default. +Use `--python PATH` to select another interpreter and `--device N` to select +another visible GPU; device 0 is the default. RTX 5090 results at `a0d5776b2` (2026-10-18), **B=1, Sq=Sk=1024, H=8, D=64**, CUTLASS 4.7 at optimization level 2 on both sides. Each value is the median of diff --git a/cuda-oxide/cute-rs-preview/examples/fmha_prefill_sm120a_cute/compare.py b/cuda-oxide/cute-rs-preview/examples/fmha_prefill_sm120a_cute/compare.py index cd075a72c9..f5990ddb3f 100644 --- a/cuda-oxide/cute-rs-preview/examples/fmha_prefill_sm120a_cute/compare.py +++ b/cuda-oxide/cute-rs-preview/examples/fmha_prefill_sm120a_cute/compare.py @@ -22,6 +22,19 @@ HERE = Path(__file__).resolve().parent +SETUP_HINT = ("from cuda-oxide/ run `python3 -m venv cute-rs-preview/.venv && " + "cute-rs-preview/.venv/bin/pip install -r cute-rs-preview/requirements.txt`, " + "then rerun; or set CUDA_OXIDE_CUTE_PYTHON to an environment that has them") + + +def require_reference_environment(): + """Stop before any GPU work when the shared comparison environment is missing.""" + missing = [name for name in ("numpy", "torch", "cutlass", "cuda") + if importlib.util.find_spec(name) is None] + if missing: + sys.exit(f"missing Python packages: {', '.join(missing)}; {SETUP_HINT}") + + def load_module(name, path): spec = importlib.util.spec_from_file_location(name, path) module = importlib.util.module_from_spec(spec) @@ -199,6 +212,7 @@ def main(argv=None): options, runner_cli = parser.parse_known_args(argv) if not math.isfinite(options.timeout) or options.timeout <= 0: parser.error("timeout must be positive and finite") + require_reference_environment() try: report = compare_all_cases(options, runner_cli) if options.all_cases else compare(options, runner_cli) if options.json: diff --git a/cuda-oxide/cute-rs-preview/examples/fmha_prefill_sm120a_cute/reference/README.md b/cuda-oxide/cute-rs-preview/examples/fmha_prefill_sm120a_cute/reference/README.md index 3e6ffbb377..219b4fe61a 100644 --- a/cuda-oxide/cute-rs-preview/examples/fmha_prefill_sm120a_cute/reference/README.md +++ b/cuda-oxide/cute-rs-preview/examples/fmha_prefill_sm120a_cute/reference/README.md @@ -15,16 +15,17 @@ runtime source is not vendored here. Use Python 3.10 or later supported by CUTLASS DSL 4.7, a CUDA-enabled PyTorch build supporting the selected GPU, CUDA bindings, and `nvidia-cutlass-dsl==4.7.0`. -`requirements.txt` selects the CUDA 13 package extra. The upstream CUDA 12.9 -alternative is `nvidia-cutlass-dsl==4.7.0` without that extra. Match the CUDA -runtime, toolkit, and driver to the package variant. +The shared [`requirements.txt`](../../../requirements.txt) selects the CUDA 13 +package extra. The upstream CUDA 12.9 alternative is `nvidia-cutlass-dsl==4.7.0` +without that extra. Match the CUDA runtime, toolkit, and driver to the package +variant. Prepare the shared Python environment once for both prefill and decode, from `cuda-oxide/`: ```bash python3 -m venv cute-rs-preview/.venv -cute-rs-preview/.venv/bin/python -m pip install -r cute-rs-preview/examples/fmha_prefill_sm120a_cute/reference/requirements.txt +cute-rs-preview/.venv/bin/pip install -r cute-rs-preview/requirements.txt ``` Select a CUDA-enabled PyTorch build that supports SM120 and matches your CUDA diff --git a/cuda-oxide/cute-rs-preview/examples/fmha_prefill_sm120a_cute/reference/requirements.txt b/cuda-oxide/cute-rs-preview/examples/fmha_prefill_sm120a_cute/reference/requirements.txt index e43bf673d3..b2cb40f71c 100644 --- a/cuda-oxide/cute-rs-preview/examples/fmha_prefill_sm120a_cute/reference/requirements.txt +++ b/cuda-oxide/cute-rs-preview/examples/fmha_prefill_sm120a_cute/reference/requirements.txt @@ -1,6 +1,4 @@ -# Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 - -# Matches the vendored CUTLASS 4.7 reference; use an SM120-capable CUDA PyTorch build. -nvidia-cutlass-dsl[cu13]==4.7.0 -torch +# This comparison uses the shared environment pinned in cute-rs-preview/requirements.txt. +-r ../../../requirements.txt diff --git a/cuda-oxide/cute-rs-preview/examples/fp16_gemm_256x352_ctm/README.md b/cuda-oxide/cute-rs-preview/examples/fp16_gemm_256x352_ctm/README.md index 67df0f63ad..b4d6d232dc 100644 --- a/cuda-oxide/cute-rs-preview/examples/fp16_gemm_256x352_ctm/README.md +++ b/cuda-oxide/cute-rs-preview/examples/fp16_gemm_256x352_ctm/README.md @@ -26,21 +26,24 @@ expresses the same schedule with typed layouts, tensor operations and pipelines. ## Run it -You need an SM100 GPU, a compatible CUDA driver and the cuda-oxide toolchain. -The comparison uses the checked-in [Python CTM reference](../fp16_gemm_256x352_cute/public_reference/README.md): +You need an SM100 GPU and a compatible CUDA driver. The comparison uses the +checked-in [Python CTM reference](../fp16_gemm_256x352_cute/public_reference/README.md): CUTLASS instruction primitives with CuTe compilation and epilogue helpers. -Setup needs `python3` with `venv`/`ensurepip`, or `uv` on `PATH`, and network -access for installation. From `cuda-oxide/`: +From `cuda-oxide/`, once per checkout: ```bash cargo oxide toolchain install cutlass +python3 -m venv cute-rs-preview/.venv +cute-rs-preview/.venv/bin/pip install -r cute-rs-preview/requirements.txt +``` + +Then: + +```bash CUDA_OXIDE_DEVICE_BACKEND=cutlass-mlir CUDA_OXIDE_MLIR_PROFILE=cutlass-primitives-mlir22 \ cargo oxide build fp16_gemm_256x352_ctm --arch sm_100a -# Prepare the shared environment; subsequent runs reuse it. -python3 cute-rs-preview/examples/fp16_gemm_256x352_cute/setup_reference.py - -cute-rs-preview/examples/fp16_gemm_256x352_cute/.venv/bin/python \ +cute-rs-preview/.venv/bin/python \ cute-rs-preview/examples/fp16_gemm_256x352_cute/compare.py \ --rust-bin cute-rs-preview/examples/fp16_gemm_256x352_ctm/target/release/fp16_gemm_256x352_ctm \ --mnk 8192,8096,8192 --warmup 2000 --iters 301 --json /tmp/ctm-gemm.json diff --git a/cuda-oxide/cute-rs-preview/examples/fp16_gemm_256x352_cute/README.md b/cuda-oxide/cute-rs-preview/examples/fp16_gemm_256x352_cute/README.md index feff2dff8a..b874398d5c 100644 --- a/cuda-oxide/cute-rs-preview/examples/fp16_gemm_256x352_cute/README.md +++ b/cuda-oxide/cute-rs-preview/examples/fp16_gemm_256x352_cute/README.md @@ -25,13 +25,17 @@ expresses the same schedule directly through instruction types and physical form ## Run it -You need an SM100 GPU, a compatible CUDA driver and the cuda-oxide toolchain. -Python comparison setup runs automatically on first use and reuses a local -`.venv`. It needs `python3` with `venv`/`ensurepip`, or `uv` on `PATH`, plus -network access for installation. From `cuda-oxide/`: +You need an SM100 GPU and a compatible CUDA driver. From `cuda-oxide/`, once per checkout: ```bash cargo oxide toolchain install cutlass +python3 -m venv cute-rs-preview/.venv +cute-rs-preview/.venv/bin/pip install -r cute-rs-preview/requirements.txt +``` + +Then: + +```bash export CUDA_OXIDE_DEVICE_BACKEND=cutlass-mlir # Small correctness comparison @@ -51,7 +55,8 @@ cute-rs: