Skip to content

Latest commit

 

History

History
273 lines (222 loc) · 12.9 KB

AGENTS.md

File metadata and controls

273 lines (222 loc) · 12.9 KB

CUDA Rust agent instructions

Repository-wide guidance. When a subdirectory has its own AGENTS.md, that file is the primary guide for the conventions and workflows of that component; this one covers what applies everywhere.

Choose the workspace before running Cargo

The root Cargo.toml is the stable host workspace. Its members are cuda-bindings, cuda-core, cuda-core-derive, and cuda-async. cuda-oxide/ and cutile-rs/ are separate nested workspaces, excluded from the root workspace. Running cargo test at the root tests the host workspace; it does not test either kernel programming model.

Run commands from the workspace that owns the package. For example, from the repository root:

cargo check -p cuda-core
(cd cuda-oxide && cargo test -p cuda-macros)
(cd cutile-rs && cargo test -p cutile-ir)
just -f cuda-oxide/Justfile check

These commands have different prerequisites; see each component's README and contribution guide. There is no root Justfile. The SIMT recipes live in cuda-oxide/Justfile and run with cuda-oxide/ as their working directory.

Component map

  • cuda-bindings/, cuda-core/, cuda-core-derive/, and cuda-async/ — shared host crates in the root workspace. Both kernel stacks depend on these by path.
  • cuda-oxide/ — the SIMT model. Its Cargo.toml explicitly lists workspace members under crates/; its rust-toolchain.toml pins the stable release (1.99.1) and rustc-dev / llvm-tools components needed for rustc_private (unlocked via RUSTC_BOOTSTRAP=1). The book is cuda-oxide/cuda-oxide-book/, and cuda-oxide/intrinsics/ holds the intrinsic catalog and ABI ledger. cuda-oxide/crates/rustc-codegen-cuda/ declares its own workspace and inherits the SIMT toolchain pin. Examples and test fixtures can also declare separate workspaces; a parent --workspace command does not include them.
  • cutile-rs/ — the Tile model, with its own workspace and stable toolchain pin. Its member crates are directly under cutile-rs/, and its book is cutile-rs/cutile-book/. cuda-tile-rs is outside default-members because its build downloads and compiles LLVM; --workspace includes it unless explicitly excluded.
  • docs/ — the umbrella landing page and docs/build_all_docs.sh, which builds the combined documentation site. The component books retain their own sources.

Running the checks

Use just -f cuda-oxide/Justfile --list from the repository root to list the SIMT recipes. The commands below are run from cuda-oxide/:

Recipe What it covers
just check SIMT formatting, clippy, tests, guards, intrinsics, and rustdoc checks
just fmt / just fmt-check Formatting scopes selected by cargo oxide fmt
just clippy SIMT and backend lints, with warnings as errors
just test Unit-test packages that need no CUDA toolkit, plus backend library tests
just test-cuda Toolkit-dependent packages; no GPU or driver required
just check-guards Repository guards and dependency/license checks
just check-intrinsics Catalog currency, PTX routes, and the ABI ledger
just doc-check SIMT rustdoc/doctests and backend rustdoc
just book Builds the cuda-oxide book with warnings as errors

just check needs a CUDA toolkit, cargo-deny, and Python. It does not cover all CI: example compilation, additional example lint scopes, book builds, and CodeQL have separate jobs. Read the recipe and relevant workflow when choosing validation for a change.

For Tile and shared-host changes, follow the cutile-rs section of CONTRIBUTING.md and .github/workflows/cutile-rs.yml. The CPU and assembler suite in cutile-rs/scripts/run_cpu_tests.sh runs with cutile-rs/ as its working directory and includes the CPU-safe shared-host tests. CPU-only does not mean toolkit-free: some suites require CUDA headers and the Tile IR assembler. GPU tests have a separate cutile-rs/scripts/run_gpu_tests.sh entry point. A bare root cargo test can include tests that require a GPU.

Dependency checks must cover each affected workspace's dependency graph and lockfile. just check-guards runs cargo deny for the host workspace, SIMT workspace, backend, and device-only fixture; use its actual invocations and .github/workflows/cargo-deny.yml rather than assuming one root check covers nested workspaces.

Toolchains

The root rust-toolchain.toml and cutile-rs/rust-toolchain.toml carry matching stable pins. cuda-oxide/rust-toolchain.toml supplies the SIMT stable pin and compiler components (rustc-dev, llvm-tools), including for its nested backend workspace. Do not float a pin to work around a failure. cuda-oxide/scripts/check-toolchain-parity.sh checks the SIMT pin against its scaffold, development container, and documentation. cuda-oxide/scripts/check-ci-image-pins.sh checks that the rust:<version> container images in the workflows match the root pin.

rustup normally resolves the toolchain from the working directory; an explicit override can change that. --manifest-path does not change the working directory, so pointing a root Cargo command at the SIMT manifest does not select the SIMT toolchain pin. Change directory first or select the required toolchain explicitly.

Nix environments live in cuda-oxide/flake.nix and cutile-rs/flake.nix. Run nix develop from the relevant component.

Commits and pull requests

  • Sign off every commit (git commit -s). The DCO is required; see CONTRIBUTING.md.
  • New first-party source files need an SPDX header — the NVIDIA copyright notice plus Apache-2.0, in the form shown under "License Headers" in CONTRIBUTING.md. Preserve existing and third-party notices. cuda-oxide/scripts/check-spdx-headers.sh enforces the policy.
  • Create new branches from the user's fork of this repository. Synchronize the fork's main with upstream before branching. For stacked work, base the next branch on the preceding feature branch in that same fork.
  • Never push to the canonical upstream repository, NVIDIA/cuda-rust. Treat it as read-only. Branch and push to a fork. Before pushing, run git remote -v and confirm the push remote is a fork of the base, comparing full OWNER/REPOSITORY names — not remote names like origin or upstream, and not the owner alone. Transplanting a cutile-rs pull request, below, is the exception: that feature branch is pushed to NVIDIA/cuda-rust.

Transplanting a cutile-rs pull request

Use this when replaying a pull request from NVlabs/cutile-rs onto current NVIDIA/cuda-rust main. The result is one commit by the original author, a feature branch on NVIDIA/cuda-rust, and a pull request that links both ways with the source pull request.

Do this from a clean tree, on a new branch based on current main. Do not stack it on another transplant.

Author

The commit's author, committer, and Signed-off-by trailer are the original author's. Read them from the source commit (git log -1 --format=fuller). Pass GIT_AUTHOR_* and GIT_COMMITTER_* into git commit-tree and git cherry-pick --continue. Do not pass git cherry-pick -s or git commit -s: that records whoever is running the transplant. Do not change git config.

If the pull request has several commits and every one has that same author, squash them first: the squashed tree is the pull-request head, the parent is the first commit's parent, and the message is the source pull request's description plus that author's existing sign-off. If the commits have different authors, stop and leave them unsquashed.

Paths

History was imported with git filter-repo --to-subdirectory-filter cutile-rs, then these directories were moved to the repository root:

  • cutile-rs/cuda-async → cuda-async
  • cutile-rs/cuda-bindings → cuda-bindings
  • cutile-rs/cuda-core → cuda-core
  • cutile-rs/cuda-core-derive → cuda-core-derive

Everything else from that repository, including CHANGELOG.md, stayed under cutile-rs/. Replay both steps. Prefix the squashed commit's trees with cutile-rs/, then cherry-pick so rename detection applies the later move. merge.directoryRenames=true carries new files (for example cuda-async/src/reaper.rs) into the renamed directory. Turn rerere off so a remembered resolution is not applied.

git fetch https://github.com/NVlabs/cutile-rs.git "pull/<n>/head:pr-<n>"
# PARENT is the squashed commit's parent; HEAD is the squashed commit.
# For a one-commit pull request, PARENT is that commit's parent.

IDX=$(mktemp -u)
export GIT_INDEX_FILE="$IDX"
git read-tree --prefix=cutile-rs/ "$PARENT^{tree}"
PARENT_TREE=$(git write-tree)
rm -f "$IDX"
git read-tree --prefix=cutile-rs/ "$HEAD^{tree}"
COMMIT_TREE=$(git write-tree)
rm -f "$IDX"
unset GIT_INDEX_FILE

PREFIX_PARENT=$(git commit-tree "$PARENT_TREE" \
  -m "cutile-rs subdirectory snapshot of the pull request parent")
PREFIXED=$(git log -1 --format=%B "$HEAD" \
  | GIT_AUTHOR_NAME="$AUTHOR_NAME" \
    GIT_AUTHOR_EMAIL="$AUTHOR_EMAIL" \
    GIT_AUTHOR_DATE="$AUTHOR_DATE" \
    git commit-tree "$COMMIT_TREE" -p "$PREFIX_PARENT")

git switch -c "feat/<short-name>" main
git -c rerere.enabled=false -c merge.directoryRenames=true \
  cherry-pick -X find-renames=50% "$PREFIXED"

Conflicts

Accept files Git auto-merges. Leave conflict markers in code for a developer to resolve. Do not edit those files, and do not finish the cherry-pick while they are unmerged.

A cutile-rs/CHANGELOG.md conflict is resolvable when the new note is the only addition and main has already published the surrounding section. Put that note under ## [Unreleased]. Leave a released section as it is, including bullets that already describe the same change. Then continue:

git add cutile-rs/CHANGELOG.md
GIT_EDITOR=true \
GIT_COMMITTER_NAME="$AUTHOR_NAME" \
GIT_COMMITTER_EMAIL="$AUTHOR_EMAIL" \
GIT_COMMITTER_DATE="$AUTHOR_DATE" \
  git cherry-pick --continue

Confirm git log -1 --format=fuller shows the original author as both author and committer, and that the message has only that author's sign-off.

Pull request

Push the feature branch to NVIDIA/cuda-rust. The local upstream URL may still say NVlabs/cuda-oxide; that repository redirects there. Push the branch, not main.

git remote -v
git push -u upstream HEAD:feat/<short-name>
gh pr create --repo NVIDIA/cuda-rust --base main --head feat/<short-name>
gh pr comment <n> --repo NVlabs/cutile-rs

The new pull request says it is on behalf of the original author and links the source pull request. The comment on the source pull request links back.

CI

Workflows run on NVIDIA self-hosted runners, which reject pull_request. They trigger on push to main and to pull-request/<n>, the branches copy-pr-bot mirrors trusted pull requests to. Do not add pull_request triggers or runs-on: ubuntu-latest; use linux-amd64-cpu4 (linux-amd64-cpu16 for the Tile test jobs). The one exception is the deploy job in book.yml, which stays on ubuntu-latest for GitHub Pages and runs only for refs/heads/main.

Copy-pr-bot creates pull-request/<n> at an existing SHA, which GitHub can treat as having no path changes, so no workflow uses a workflow-level paths: filter. ci.yml, examples-compile.yml, docs.yml, codeql.yml, book.yml, naming-guard.yml, and cutile-rs.yml gate their jobs on a changes job (dorny/paths-filter against main); an undetectable diff runs the jobs conservatively. The SIMT lanes include shared-host paths as well as cuda-oxide/; book filters follow documentation sources and build scripts. SIMT-only changes can skip the Tile and shared-host jobs when the diff is available. The reusable clippy.yml, fmt.yml, unit-tests.yml, and cargo-deny.yml workflows inherit the caller's trigger. Check the changes job and job conditions before interpreting a missing run as either a failure or successful validation.

Pull requests need cryptographically signed commits (SSH or GPG, Verified on GitHub) as well as the Signed-off-by line; copy-pr-bot holds a pull request with unsigned commits for validation. A history rewrite drops signatures, so re-sign with git rebase --signoff -S or git commit --amend -s -S.

Historical references and fixtures

  • Issue and pull-request permalinks may retain historical repository names such as NVlabs/cuda-oxide. Preserve a historical reference unless its destination is demonstrably wrong; use NVIDIA/cuda-rust for current repository links.
  • Trybuild .stderr files can contain $WORKSPACE-relative paths. Moving a crate can change those diagnostics. TRYBUILD=overwrite cargo test ... regenerates snapshots; read the diff before accepting it, because it can also bless a real regression.

Paths

Tools resolve repository data relative to the component that owns it. cuda-intrinsics-gen discovers the directory holding intrinsics/upstream.lock, and cargo-oxide discovers the one holding crates/rustc-codegen-cuda. Follow the owning tool's root-discovery convention instead of assuming every command starts at the repository root.