rules_cuda

KO | EN

gitlite — search

#python #ai #llm #rust #smart-contracts #solidity #web3 #agentic-ai #php #machine-learning #blockchain #arduino

★ 122 Open GitHub ↗

Starlark implementation of bazel rules for CUDA.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# CUDA rules for [Bazel](https://bazel.build)

This repository contains [Starlark](https://github.com/bazelbuild/starlark) implementation of CUDA rules for Bazel.

These rules provide a set of rules and macros that make it easier to build CUDA with Bazel.

## Getting Started

### Bzlmod

Add the following to your `MODULE.bazel` file and replace the placeholders with actual values.

```starlark
bazel_dep(name = "rules_cc", version = "{rules_cc_version}")
bazel_dep(name = "rules_cuda", version = "0.2.5")

# pick a specific version (this is optional and can be skipped)
archive_override(
    module_name = "rules_cuda",
    integrity = "{SRI value}",  # see https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
    url = "https://github.com/bazel-contrib/rules_cuda/archive/{git_commit_hash}.tar.gz",
    strip_prefix = "rules_cuda-{git_commit_hash}",
)

cuda = use_extension("@rules_cuda//cuda:extensions.bzl", "toolchain")
cuda.toolkit(
    name = "cuda",
    toolkit_path = "",
)
use_repo(cuda, "cuda")
```

`rules_cc` provides the C++ toolchain dependency for `rules_cuda`; in Bzlmod, the compatibility repository is handled by `rules_cc` itself.

#### Multi-version hermetic toolchains (Bzlmod)

To select CUDA versions and platforms at build time, define multiple `cuda.redist_json` entries and a single `cuda.toolkit`.
The target CUDA redist is auto-detected from the active target platform's `@platforms//cpu` + `@platforms//os` constraints.
Set `--platforms` to control it. linux-sbsa and linux-aarch64 share aarch64+linux constraints; the `@rules_cuda//cuda:aarch64` flag
disambiguates them (default `sbsa` → linux-sbsa, set to `aarch64` for Tegra/Jetson/Drive Thor → linux-aarch64).
Use `@rules_cuda//cuda:version` to pick the CUDA version (defaults to the highest declared if unset),
and `@rules_cuda//cuda:exec_platform` as an escape hatch to override the auto-detected exec redist.

```starlark
cuda = use_extension("@rules_cuda//cuda:extensions.bzl", "toolchain")

cuda.redist_json(
    name = "cuda_13_0_2",
    version = "13.0.2",
    platforms = [
        "linux-x86_64",
        "linux-sbsa",
    ],
)
cuda.redist_json(
    name = "cuda_13_0_0",
    version = "13.0.0",
    platforms = [
        "linux-x86_64",
        "linux-sbsa",
    ],
)

cuda.toolkit(name = "cuda")
use_repo(cuda, "cuda")
```

Example `.bazelrc` entries:

```
build --platforms=//:my_x86_platform
# For Tegra/Drive Thor targets (linux-aarch64 redist):
# build --platforms=//:my_aarch64_platform --@rules_cuda//cuda:aarch64=aarch64
# Optional: if omitted, the highest declared redist version is used.
build --@rules_cuda//cuda:version=13.0.0
```

Note: In Bzlmod, `platforms` is required for `cuda.redist_json` because module extensions don't have access to host OS/arch
information, so the platforms must be declared explicitly.

<details>
<summary>Traditional WORKSPACE approach</summary>

### Traditional WORKSPACE approach

Add the following to your `WORKSPACE` file and replace the placeholders with actual values.

```starlark
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
    name = "rules_cc",
    sha256 = "{rules_cc_sha256}",
    strip_prefix = "rules_cc-{rules_cc_version}",
    urls = ["https://github.com/bazelbuild/rules_cc/releases/download/{rules_cc_version}/rules_cc-{rules_cc_version}.tar.gz"],
)
load("@rules_cc//cc:extensions.bzl", "compatibility_proxy_repo")
compatibility_proxy_repo()

http_archive(
    name = "rules_cuda",
    sha256 = "{sha256_to_replace}",
    strip_prefix = "rules_cuda-{git_commit_hash}",
    urls = ["https://github.com/bazel-contrib/rules_cuda/archive/{git_commit_hash}.tar.gz"],
)
load("@rules_cuda//cuda:repositories.bzl", "rules_cuda_dependencies", "rules_cuda_toolchains")
rules_cuda_dependencies()
rules_cuda_toolchains(register_toolchains = True)
```

`rules_cc` needs to be available before loading `rules_cuda`, and `compatibility_proxy_repo()` must be called to populate the compatibility repository that `rules_cc` expects.

**NOTE**: `rules_cuda_toolchains` implicitly calls `register_detected_cuda_toolchains`, and the use of
`register_detected_cuda_toolchains` depends on the auto-detection of installed CUDA toolkits.

</details>

### Toolchain Detection

For hermetic toolchains, the rules handle toolchain configuration and library downloading automatically.
See [cuda.redist_json integration test](tests/integration/toolchain_redist_json) for a comprehensible example.

For locally installed toolchains,
[`_detect_local_cuda_toolkit`](https://github.com/bazel-contrib/rules_cuda/blob/ce98e4ae5c/cuda/private/repositories.bzl#L30-L45)
and [`detect_clang`](https://github.com/bazel-contrib/rules_cuda/blob/ce98e4ae5c/cuda/private/repositories.bzl#L215-L256)
determines how they are detected.

Either situation depends on cc toolchain availability, so you must also ensure the cc compiler is properly configured.
On Windows, this means that you will also need to set the environment variable `BAZEL_VC` properly.

### Rules

- `cuda_library`: Can be used to compile and create static library for CUDA kernel code. The resulting targets can be
  consumed by [C/C++ Rules](https://bazel.build/reference/be/c-cpp#rules).
- `cuda_objects`: If you don't understand what _device link_ means, you must never use it. This rule produces incomplete
  object files that can only be consumed by `cuda_library`. It is created for relocatable device code and device link
  time optimization source files.

### Macros

- `cuda_binary`: A convenience macro for building CUDA-enabled executables.
  It builds a `cc_binary`-style target from CUDA sources.
- `cuda_test`: A convenience macro for CUDA-enabled tests.
  It behaves like `cuda_binary` but creates a `cc_test`-style target that can be run with `bazel test`.

### Flags

Some flags are defined in [cuda/BUILD.bazel](cuda/BUILD.bazel). To use them, for example:

```
bazel build --@rules_cuda//cuda:archs=compute_61:compute_61,sm_61
```

In `.bazelrc` file, you can define a shortcut alias for the flag, for example:

```
# Convenient flag shortcuts.
build --flag_alias=cuda_archs=@rules_cuda//cuda:archs
```

and then you can use it as follows:

```
bazel build --cuda_archs=compute_61:compute_61,sm_61
```

#### Available flags

- `@rules_cuda//cuda:enable`

Enable or disable all rules_cuda related rules. When disabled, the detected CUDA toolchains will also be disabled to avoid potential human error.
  By default, rules_cuda rules are enabled. See `examples/if_cuda` for how to support both cuda-enabled and cuda-free builds.

- `@rules_cuda//cuda:archs`

Select the CUDA archs to support. See [cuda_archs specification DSL grammar](https://github.com/bazel-contrib/rules_cuda/blob/5633f0c0f7/cuda/private/rules/flags.bzl#L14-L44).

- `@rules_cuda//cuda:compiler`

Select the CUDA compiler; available options are `nvcc` or `clang`.

- `@rules_cuda//cuda:copts`

Add copts to all CUDA compile actions.

- `@rules_cuda//cuda:host_copts`

Add copts to the host compiler.

- `@rules_cuda//cuda:cc_host_compile_flags_to_skip`

Configure which C++ toolchain host compile flags should be filtered out before forwarding to CUDA host compilation.
  This defaults to skipping `-c`, and can be repeated, for example:
  `--@rules_cuda//cuda:cc_host_compile_flags_to_skip=-c --@rules_cuda//cuda:cc_host_compile_flags_to_skip=-fno-canonical-system-headers`.

- `@rules_cuda//cuda:runtime`

Set the default cudart to link; for example, `--@rules_cuda//cuda:runtime=@cuda//:cuda_runtime_static` links the static CUDA runtime.

- `--features=cuda_device_debug`

Sets nvcc flags to enable debug information in device code.
  Currently ignored for clang, where `--compilation_mode=debug` applies to both
  host and device code.

## Examples

Check out the examples to see if they fit your needs.

See [examples](./examples) for basic usage.

See [rules_cuda_examples](https://github.com/cloudhan/rules_cuda_examples) for extended real-world projects.

## Known issue

Sometimes the following error occurs:

```
cc1plus: fatal error: /tmp/tmpxft_00000002_00000019-2.cpp: No such file or directory
```

The problem is caused by nvcc using PIDs to determine temporary file names, and with `--spawn_strategy linux-sandbox`, which is the default strategy on Linux, the PIDs nvcc sees are all very small numbers (say 2~4) due to sandboxing. `linux-sandbox` is not hermetic because [it mounts root into the sandbox](https://docs.bazel.build/versions/main/command-line-reference.html#flag--experimental_use_hermetic_linux_sandbox), so `/tmp` is shared between sandboxes, which causes name conflicts under high parallelism. A similar problem has been reported on the [NVIDIA forums](https://forums.developer.nvidia.com/t/avoid-generating-temp-files-in-tmp-while-nvcc-compiling/197657/10).

To avoid it:

- Update to Bazel 7 where `--incompatible_sandbox_hermetic_tmp` is enabled by default.
- Using `--spawn_strategy local` should eliminate the case because it lets nvcc see the true PIDs.
- Using `--experimental_use_hermetic_linux_sandbox` should eliminate the case because it avoids sharing `/tmp`.
- Adding the `-objtemp` option should reduce the chance of this happening.

rules_cuda

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README