Rule Authoring

actions.compile

actions.compile(ctx, cuda_toolchain, cc_toolchain, srcs, common, pic, rdc, _prefix)

Perform CUDA compilation, return compiled object files.

Notes:

If rdc is set to True, then an additional step of device link must be performed.
The rules should call this action only once in case srcs have non-unique basenames, say foo/kernel.cu and bar/kernel.cu.

PARAMETERS

Name	Description	Default Value
ctx	A context object.	none
cuda_toolchain	A `platform_common.ToolchainInfo` of a cuda toolchain, Can be obtained with `find_cuda_toolchain(ctx)`.	none
cc_toolchain	A `CcToolchainInfo`. Can be obtained with `find_cpp_toolchain(ctx)`.	none
srcs	A list of `File`s to be compiled.	none
common	A cuda common object. Can be obtained with `cuda_helper.create_common(ctx)`	none
pic	Whether the `srcs` are compiled for position independent code.	`False`
rdc	Whether the `srcs` are compiled for relocatable device code.	`False`
_prefix	DON'T USE IT! Prefix of the output dir. Exposed for device link to redirect the output.	`"_objs"`

RETURNS

An compiled object File.

actions.device_link

actions.device_link(ctx, cuda_toolchain, cc_toolchain, objects, common, pic, rdc, dlto)

Perform device link, return a dlink-ed object file.

Notes: Compilation is carried out during device linking, which involves the embeeding of the fatbin into the resulting object File.

PARAMETERS

Name	Description	Default Value
ctx	A context object.	none
cuda_toolchain	A `platform_common.ToolchainInfo` of a cuda toolchain, Can be obtained with `find_cuda_toolchain(ctx)`.	none
cc_toolchain	A `CcToolchainInfo`. Can be obtained with `find_cpp_toolchain(ctx)`.	none
objects	A `depset` of `File`s to be device linked.	none
common	A cuda common object. Can be obtained with `cuda_helper.create_common(ctx)`	none
pic	Whether the `objects` are compiled for position independent code.	`False`
rdc	Whether the `objects` are device linked for relocatable device code.	`False`
dlto	Whether the device link time optimization is enabled.	`False`

RETURNS

An deviced linked object File.

config_helper.action_is_enabled

config_helper.action_is_enabled(info, name)

Returns whether a selectable is enable or not.

PARAMETERS

Name	Description	Default Value
info	A `_FeatureConfigurationInfo`, returned by `configure_features`, to be queried.	none
name	Name of the selectable, that is, an `action_config` or a `feature`.	none

config_helper.collect_selectables_info

config_helper.collect_selectables_info(selectables)

Constructor of _SelectablesInfo.

PARAMETERS

Name	Description	Default Value
selectables	List of `action_config`s and/or `feature`s.	none

config_helper.configure_features

config_helper.configure_features(selectables, selectables_info, requested_features,
                                 unsupported_features, _debug)

Constructor of _FeatureConfigurationInfo.

PARAMETERS

Name	Description	Default Value
selectables	List of `action_config`s and/or `feature`s.	`None`
selectables_info	The `_SelectablesInfo` returned from `_collect_selectables_info`	`None`
requested_features	List of names of `action_config`s and/or `feature`s to be enabled.	`None`
unsupported_features	List of names of `action_config`s and/or `feature`s to be disabled.	`None`
_debug	-	`False`

config_helper.get_artifact_name

config_helper.get_artifact_name(artifact_name_patterns, category_name, basename)

Returns artifact_name in form of prefix + basename + extension.

PARAMETERS

Name	Description	Default Value
artifact_name_patterns	A list of `artifact_name_pattern`.	none
category_name	A string match the `category_name` field in `artifact_name_pattern`.	none
basename	A string.	none

config_helper.get_command_line

config_helper.get_command_line(info, action, value)

Returns flattened command line flags for given action, using given variables for expansion.

PARAMETERS

Name	Description	Default Value
info	A `_FeatureConfigurationInfo`, returned by `configure_features`, to be queried.	none
action	Name of the action.	none
value	Build variables to be used for template expansion.	none

config_helper.get_default_features_and_action_configs

config_helper.get_default_features_and_action_configs(info)

Get all default enabled features and action configs.

Notes: For testing purpose. Default enabled maybe disabled after configuration.

PARAMETERS

Name	Description	Default Value
info	A `_FeatureConfigurationInfo`, returned by `configure_features`, to be queried.	none

config_helper.get_enabled_feature

config_helper.get_enabled_feature(info)

Get all enabled features.

Notes: For testing purpose.

PARAMETERS

Name	Description	Default Value
info	A `_FeatureConfigurationInfo`, returned by `configure_features`, to be queried.	none

config_helper.get_environment_variables

config_helper.get_environment_variables(info, action, value)

Returns environment variables to be set for the given action.

PARAMETERS

Name	Description	Default Value
info	A `_FeatureConfigurationInfo`, returned by `configure_features`, to be queried.	none
action	Name of the action.	none
value	Build variables to be used for template expansion.	none

config_helper.get_tool_for_action

config_helper.get_tool_for_action(info, action_name)

Returns tool path for given action.

PARAMETERS

Name	Description	Default Value
info	A `_FeatureConfigurationInfo`, returned by `configure_features`, to be queried.	none
action_name	Name of the action.	none

config_helper.is_configured

config_helper.is_configured(selectables_info, name)

Whether an action or a feature exists

PARAMETERS

Name	Description	Default Value
selectables_info	The `_SelectablesInfo` returned from `_collect_selectables_info`	none
name	Name of the selectable, that is, an `action_config` or a `feature`.	none

config_helper.is_enabled

config_helper.is_enabled(info, name)

Returns whether a selectable is enable or not.

PARAMETERS

Name	Description	Default Value
info	A `_FeatureConfigurationInfo`, returned by `configure_features`, to be queried.	none
name	Name of the selectable, that is, an `action_config` or a `feature`.	none

cuda_helper.action_is_enabled

cuda_helper.action_is_enabled(info, name)

Returns whether a selectable is enable or not.

PARAMETERS

Name	Description	Default Value
info	A `_FeatureConfigurationInfo`, returned by `configure_features`, to be queried.	none
name	Name of the selectable, that is, an `action_config` or a `feature`.	none

cuda_helper.check_must_enforce_rdc

cuda_helper.check_must_enforce_rdc(arch_specs, cuda_archs_info)

Force enable rdc if dlto is enabled.

PARAMETERS

Name	Description	Default Value
arch_specs	-	`None`
cuda_archs_info	-	`None`

cuda_helper.check_srcs_extensions

cuda_helper.check_srcs_extensions(ctx, allowed_src_files, rule_name)

Ensure ctx.attr.srcs is valid.

PARAMETERS

Name	Description	Default Value
ctx	-	none
allowed_src_files	-	none
rule_name	-	none

cuda_helper.configure_features

cuda_helper.configure_features(ctx, cuda_toolchain, requested_features, unsupported_features,
                               _debug)

Creates a feature_configuration instance.

PARAMETERS

Name	Description	Default Value
ctx	The rule context.	none
cuda_toolchain	cuda_toolchain for which we configure features.	none
requested_features	List of features to be enabled.	`None`
unsupported_features	List of features that are unsupported by the current rule.	`None`
_debug	-	`False`

cuda_helper.create_common

cuda_helper.create_common(ctx)

Helper to gather and process various information from ctx object to ease the parameter passing for internal macros.

See cuda_helper.create_common_info what information a common object encapsulates.

PARAMETERS

Name	Description	Default Value
ctx	-	none

cuda_helper.create_common_info

cuda_helper.create_common_info(cuda_archs_info, includes, quote_includes, system_includes, headers,
                               transitive_headers, defines, local_defines, compile_flags, link_flags,
                               host_defines, host_local_defines, host_compile_flags, host_link_flags,
                               ptxas_flags, transitive_cc_info, transitive_linking_contexts)

Constructor of the common object.

PARAMETERS

Name	Description	Default Value
cuda_archs_info	`CudaArchsInfo`.	`None`
includes	include paths. Can be used with `#include <...>` and `#include "..."`.	`[]`
quote_includes	include paths. Can be used with `#include "..."`.	`[]`
system_includes	include paths. Can be used with `#include <...>`.	`[]`
headers	headers directly relate with this target.	`[]`
transitive_headers	headers transitively gather from `deps`.	`[]`
defines	public `#define`s. Pass to compiler driver directly. Will be seen by downstream targets.	`[]`
local_defines	private `#define`s. Pass to compiler driver directly. Will not be seen by downstream targets.	`[]`
compile_flags	flags pass to compiler driver directly.	`[]`
link_flags	flags pass to device linker.	`[]`
host_defines	public `#define`s. Pass to host compiler. Will be seen by downstream targets.	`[]`
host_local_defines	private `#define`s. Pass to host compiler. Will not be seen by downstream targets.	`[]`
host_compile_flags	flags pass to host compiler.	`[]`
host_link_flags	flags pass to host linker.	`[]`
ptxas_flags	flags pass to `ptxas`.	`[]`
transitive_cc_info	-	`None`
transitive_linking_contexts	`CcInfo.linking_context` extracted from `deps`	`[]`

cuda_helper.create_compile_variables

cuda_helper.create_compile_variables(cuda_toolchain, feature_configuration, cuda_archs_info,
                                     source_file, output_file, host_compiler, compile_flags,
                                     host_compile_flags, include_paths, quote_include_paths,
                                     system_include_paths, defines, host_defines, ptxas_flags,
                                     use_pic, use_rdc)

Returns variables used for compile actions.

PARAMETERS

Name	Description	Default Value
cuda_toolchain	cuda_toolchain for which we are creating build variables.	none
feature_configuration	Feature configuration to be queried.	none
cuda_archs_info	`CudaArchsInfo`	none
source_file	source file for the compilation.	`None`
output_file	output file of the compilation.	`None`
host_compiler	host compiler path.	`None`
compile_flags	flags pass to compiler driver directly.	`[]`
host_compile_flags	flags pass to host compiler.	`[]`
include_paths	include paths. Can be used with `#include <...>` and `#include "..."`.	`[]`
quote_include_paths	include paths. Can be used with `#include "..."`.	`[]`
system_include_paths	include paths. Can be used with `#include <...>`.	`[]`
defines	`#define`s. Pass to compiler driver directly.	`[]`
host_defines	`#define`s. Pass to host compiler.	`[]`
ptxas_flags	flags pass to `ptxas`.	`[]`
use_pic	whether to compile for position independent code.	`False`
use_rdc	whether to compile for relocatable device code.	`False`

cuda_helper.create_cuda_info

cuda_helper.create_cuda_info(defines, objects, rdc_objects, pic_objects, rdc_pic_objects,
                             archive_objects, archive_rdc_objects, archive_pic_objects,
                             archive_rdc_pic_objects, dlink_rdc_objects, dlink_rdc_pic_objects)

Constructor for CudaInfo. See the providers documentation for detail.

PARAMETERS

Name	Description	Default Value
defines	-	`None`
objects	-	`None`
rdc_objects	-	`None`
pic_objects	-	`None`
rdc_pic_objects	-	`None`
archive_objects	-	`None`
archive_rdc_objects	-	`None`
archive_pic_objects	-	`None`
archive_rdc_pic_objects	-	`None`
dlink_rdc_objects	-	`None`
dlink_rdc_pic_objects	-	`None`

cuda_helper.create_device_link_variables

cuda_helper.create_device_link_variables(cuda_toolchain, feature_configuration, cuda_archs_info,
                                         output_file, host_compiler, host_compile_flags,
                                         user_link_flags, use_pic)

Returns variables used for device_link actions.

PARAMETERS

Name	Description	Default Value
cuda_toolchain	cuda_toolchain for which we are creating build variables.	none
feature_configuration	Feature configuration to be queried.	none
cuda_archs_info	`CudaArchsInfo`	none
output_file	output file of the device linking.	`None`
host_compiler	host compiler path.	`None`
host_compile_flags	flags pass to host compiler.	`[]`
user_link_flags	flags for device linking.	`[]`
use_pic	whether to compile for position independent code.	`False`

cuda_helper.get_arch_specs

cuda_helper.get_arch_specs(specs_str)

Convert string into a list of ArchSpecInfo.

PARAMETERS

Name	Description	Default Value
specs_str	a string to be parsed, e.g., "compute_70:sm_70;compute_80:sm_80,sm_86".	none

RETURNS

A list of ArchSpecInfos

cuda_helper.get_artifact_category_from_action

cuda_helper.get_artifact_category_from_action(action_name, use_pic, use_rdc)

Query the canonical artifact category name.

PARAMETERS

Name	Description	Default Value
action_name	-	none
use_pic	-	`None`
use_rdc	-	`None`

cuda_helper.get_artifact_name

cuda_helper.get_artifact_name(cuda_toolchain, category_name, output_basename)

Create the artifact name that follow the toolchain configuration.

PARAMETERS

Name	Description	Default Value
cuda_toolchain	CUDA toolchain returned by `find_cuda_toolchain`.	none
category_name	The canonical artifact category name return by `cuda_helper.get_artifact_category_from_action`	none
output_basename	The basename.	none

cuda_helper.get_basename_without_ext

cuda_helper.get_basename_without_ext(basename, allow_exts, fail_if_not_match)

PARAMETERS

Name	Description	Default Value
basename	-	none
allow_exts	-	none
fail_if_not_match	-	`True`

cuda_helper.get_command_line

cuda_helper.get_command_line(info, action, value)

Returns flattened command line flags for given action, using given variables for expansion.

PARAMETERS

Name	Description	Default Value
info	A `_FeatureConfigurationInfo`, returned by `configure_features`, to be queried.	none
action	Name of the action.	none
value	Build variables to be used for template expansion.	none

cuda_helper.get_environment_variables

cuda_helper.get_environment_variables(info, action, value)

Returns environment variables to be set for the given action.

PARAMETERS

Name	Description	Default Value
info	A `_FeatureConfigurationInfo`, returned by `configure_features`, to be queried.	none
action	Name of the action.	none
value	Build variables to be used for template expansion.	none

cuda_helper.get_tool_for_action

cuda_helper.get_tool_for_action(info, action_name)

Returns tool path for given action.

PARAMETERS

Name	Description	Default Value
info	A `_FeatureConfigurationInfo`, returned by `configure_features`, to be queried.	none
action_name	Name of the action.	none

cuda_helper.is_enabled

cuda_helper.is_enabled(info, name)

Returns whether a selectable is enable or not.

PARAMETERS

Name	Description	Default Value
info	A `_FeatureConfigurationInfo`, returned by `configure_features`, to be queried.	none
name	Name of the selectable, that is, an `action_config` or a `feature`.	none

repositories.config_clang

repositories.config_clang(repository_ctx, cuda, clang_path)

Generate @local_cuda//toolchain/clang/BUILD

PARAMETERS

Name	Description	Default Value
repository_ctx	repository_ctx	none
cuda	The struct returned from `detect_cuda_toolkit`	none
clang_path	Path to clang executable returned from `detect_clang`	none

repositories.config_cuda_toolkit_and_nvcc

repositories.config_cuda_toolkit_and_nvcc(repository_ctx, cuda)

Generate @local_cuda//BUILD and @local_cuda//defs.bzl and @local_cuda//toolchain/BUILD

PARAMETERS

Name	Description	Default Value
repository_ctx	repository_ctx	none
cuda	The struct returned from detect_cuda_toolkit	none

repositories.detect_clang

repositories.detect_clang(repository_ctx)

Detect local clang installation.

The path to clang is determined by:

taken from CUDA_CLANG_PATH environment variable or
taken from BAZEL_LLVM environment variable as $BAZEL_LLVM/bin/clang or
determined through which clang or
treated as being not detected and not configured

PARAMETERS

Name	Description	Default Value
repository_ctx	repository_ctx	none

RETURNS

clang_path (str | None): Optionally return a string of path to clang executable if detected.

repositories.detect_cuda_toolkit

repositories.detect_cuda_toolkit(repository_ctx)

Detect CUDA Toolkit.

The path to CUDA Toolkit is determined as: - the value of toolkit_path passed to local_cuda as an attribute - taken from CUDA_PATH environment variable or - determined through 'which ptxas' or - defaults to '/usr/local/cuda'

PARAMETERS

Name	Description	Default Value
repository_ctx	repository_ctx	none

RETURNS

A struct contains the information of CUDA Toolkit.

toolchain.find_cuda_toolchain

toolchain.find_cuda_toolchain(ctx)

Helper to get the cuda toolchain from context object.

PARAMETERS

Name	Description	Default Value
ctx	The rule context for which to find a toolchain.	none

RETURNS

A platform_common.ToolchainInfo that wraps around the necessary information of a cuda toolchain.

toolchain.find_cuda_toolkit

toolchain.find_cuda_toolkit(ctx)

Finds the CUDA toolchain.

PARAMETERS

Name	Description	Default Value
ctx	The rule context for which to find a toolchain.	none

RETURNS

A CudaToolkitInfo.

toolchain.use_cpp_toolchain

toolchain.use_cpp_toolchain(mandatory)

Helper to depend on the C++ toolchain.

Notes: Copied from toolchain_utils.bzl

PARAMETERS

Name	Description	Default Value
mandatory	-	`True`

toolchain.use_cuda_toolchain

toolchain.use_cuda_toolchain()

Helper to depend on the CUDA toolchain.