Skip to content

Using the rules

cuda_archs

load("@rules_cuda_docs//:user_docs.bzl", "cuda_archs")

cuda_archs(name)

A build setting for specifying cuda archs to compile for.

To retain the flexibility of NVCC, the extended notation is adopted.

When passing cuda_archs from commandline, its spec grammar is as follows:

ARCH_SPECS   ::= ARCH_SPEC [ ';' ARCH_SPECS ]
ARCH_SPEC    ::= [ VIRTUAL_ARCH ':' ] GPU_ARCHS
GPU_ARCHS    ::= GPU_ARCH [ ',' GPU_ARCHS ]
GPU_ARCH     ::= 'sm_' ARCH_NUMBER
               | 'lto_' ARCH_NUMBER
               | VIRTUAL_ARCH
VIRTUAL_ARCH ::= 'compute_' ARCH_NUMBER
               | 'lto_' ARCH_NUMBER
ARCH_NUMBER  ::= (a string in predefined cuda_archs list)

E.g.:

  • compute_80:sm_80,sm_86: Use compute_80 PTX, generate cubin with sm_80 and sm_86, no PTX embedded
  • compute_80:compute_80,sm_80,sm_86: Use compute_80 PTX, generate cubin with sm_80 and sm_86, PTX embedded
  • compute_80:compute_80: Embed compute_80 PTX, fully relay on ptxas
  • sm_80,sm_86: Same as compute_80:sm_80,sm_86, the arch with minimum integer value will be automatically populated.
  • sm_80;sm_86: Two specs used.
  • compute_80: Same as compute_80:compute_80

Best Practices:

  • Library supports a full range of archs from xx to yy, you should embed the yy PTX
  • Library supports a sparse range of archs from xx to yy, you should embed the xx PTX

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required

cuda_library

load("@rules_cuda_docs//:user_docs.bzl", "cuda_library")

cuda_library(name, deps, srcs, hdrs, alwayslink, archs, copts, defines, host_copts, host_defines,
             host_linkopts, host_local_defines, includes, linkopts, local_defines, ptxasopts, rdc)

This rule compiles and creates static library for CUDA kernel code. The resulting targets can then be consumed by C/C++ Rules.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps - List of labels optional []
srcs - List of labels optional []
hdrs - List of labels optional []
alwayslink - Boolean optional False
archs Cuda arch specs for this target only. If specified, cuda archs passed from commandline will be ignored List of strings optional []
copts Add these options to the CUDA device compilation command. List of strings optional []
defines List of defines to add to the compile line. List of strings optional []
host_copts Add these options to the CUDA host compilation command. List of strings optional []
host_defines List of defines to add to the compile line. List of strings optional []
host_linkopts Add these flags to the host library link command. List of strings optional []
host_local_defines List of defines to add to the compile line, but only apply to this rule. List of strings optional []
includes List of include dirs to be added to the compile line. List of strings optional []
linkopts Add these flags to the CUDA device link command. List of strings optional []
local_defines List of defines to add to the compile line, but only apply to this rule. List of strings optional []
ptxasopts Add these flags to the ptxas command. List of strings optional []
rdc Whether to perform device linking for relocatable device code. Transitive deps that contain device code must all either be cuda_objects or cuda_library(rdc = True). Boolean optional False

cuda_objects

load("@rules_cuda_docs//:user_docs.bzl", "cuda_objects")

cuda_objects(name, deps, srcs, hdrs, archs, copts, defines, host_copts, host_defines,
             host_local_defines, includes, local_defines, ptxasopts)

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.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps - List of labels optional []
srcs - List of labels optional []
hdrs - List of labels optional []
archs Cuda arch specs for this target only. If specified, cuda archs passed from commandline will be ignored List of strings optional []
copts Add these options to the CUDA device compilation command. List of strings optional []
defines List of defines to add to the compile line. List of strings optional []
host_copts Add these options to the CUDA host compilation command. List of strings optional []
host_defines List of defines to add to the compile line. List of strings optional []
host_local_defines List of defines to add to the compile line, but only apply to this rule. List of strings optional []
includes List of include dirs to be added to the compile line. List of strings optional []
local_defines List of defines to add to the compile line, but only apply to this rule. List of strings optional []
ptxasopts Add these flags to the ptxas command. List of strings optional []

cuda_binary

load("@rules_cuda_docs//:user_docs.bzl", "cuda_binary")

cuda_binary(name, **attrs)

A macro wraps cuda_library and cc_binary to ensure the binary is compiled with the CUDA compiler.

Notes: host_copts, host_defines, host_local_defines and host_linkopts will be used for cc_binary and renamed without "host_" prefix

PARAMETERS

Name Description Default Value
name A unique name for this target (cc_binary). none
attrs attrs of cc_binary and cuda_library. none

cuda_test

load("@rules_cuda_docs//:user_docs.bzl", "cuda_test")

cuda_test(name, **attrs)

A macro wraps cuda_library and cc_test to ensure the test is compiled with the CUDA compiler.

Notes: host_copts, host_defines, host_local_defines and host_linkopts will be used for cc_test and renamed without "host_" prefix

PARAMETERS

Name Description Default Value
name A unique name for this target (cc_test). none
attrs attrs of cc_test and cuda_library. none

register_detected_cuda_toolchains

load("@rules_cuda_docs//:user_docs.bzl", "register_detected_cuda_toolchains")

register_detected_cuda_toolchains()

Helper to register the automatically detected CUDA toolchain(s).

User can setup their own toolchain if needed and ignore the detected ones by not calling this macro.

Recursive registration includes only toolchain rules, skipping implementations, config_settings, and aliases. Explicit labels must resolve to toolchain declarations.

rules_cuda_dependencies

load("@rules_cuda_docs//:user_docs.bzl", "rules_cuda_dependencies")

rules_cuda_dependencies()

Populate the dependencies for rules_cuda. This will setup other bazel rules as workspace dependencies

rules_cuda_toolchains

load("@rules_cuda_docs//:user_docs.bzl", "rules_cuda_toolchains")

rules_cuda_toolchains(toolkit_path, components_mapping, version, nvcc_version, register_toolchains)

Populate the @cuda repo.

PARAMETERS

Name Description Default Value
toolkit_path Optionally specify the path to CUDA toolkit. If not specified, it will be detected automatically. None
components_mapping dict mapping from component_name to its corresponding cuda_component's repo_name None
version str for cuda toolkit version. Required for deliverable toolkit only. None
nvcc_version str for nvcc version. Required for deliverable toolkit only. Fallback to version if omitted. None
register_toolchains Register the toolchains if enabled. False