Members
- analysis_test_transition
- aspect
- configuration_field
- depset
- exec_group
- exec_transition
- macro
- module_extension
- provider
- repository_rule
- rule
- select
- subrule
- tag_class
- visibility
analysis_test_transition
transition analysis_test_transition(settings)
Creates a configuration transition to be applied on an analysis-test rule's dependencies. This transition may only be applied on attributes of rules with analysis_test = True
. Such rules are restricted in capabilities (for example, the size of their dependency tree is limited), so transitions created using this function are limited in potential scope as compared to transitions created using transition()
.
This function is primarily designed to facilitate the Analysis Test Framework core library. See its documentation (or its implementation) for best practices.
Parameters
Parameter | Description |
---|---|
settings
|
dict;
required A dictionary containing information about configuration settings which should be set by this configuration transition. Keys are build setting labels and values are their new post-transition values. All other settings are unchanged. Use this to declare specific configuration settings that an analysis test requires to be set in order to pass. |
aspect
Aspect aspect(implementation, attr_aspects=[], toolchains_aspects=[], attrs={}, required_providers=[], required_aspect_providers=[], provides=[], requires=[], fragments=[], host_fragments=[], toolchains=[], incompatible_use_toolchain_transition=False, doc=None, *, apply_to_generating_rules=False, exec_compatible_with=[], exec_groups=None, subrules=[])Creates a new aspect. The result of this function must be stored in a global value. Please see the introduction to Aspects for more details.
Parameters
Parameter | Description |
---|---|
implementation
|
function;
required A Starlark function that implements this aspect, with exactly two parameters: Target (the target to which the aspect is applied) and ctx (the rule context which the target is created from). Attributes of the target are available via the ctx.rule field. This function is evaluated during the analysis phase for each application of an aspect to a target.
|
attr_aspects
|
sequence of strings;
default is [] List of attribute names. The aspect propagates along dependencies specified in the attributes of a target with these names. Common values here include deps and exports . The list can also contain a single string "*" to propagate along all dependencies of a target.
|
toolchains_aspects
|
sequence;
default is [] List of toolchain types. The aspect propagates to target toolchains which match these toolchain types. |
attrs
|
dict;
default is {} A dictionary declaring all the attributes of the aspect. It maps from an attribute name to an attribute object, like attr.label or attr.string (see attr module). Aspect attributes are available to implementation function as fields of ctx parameter. Implicit attributes starting with Explicit attributes must have type Declared attributes will convert |
required_providers
|
sequence;
default is [] This attribute allows the aspect to limit its propagation to only the targets whose rules advertise its required providers. The value must be a list containing either individual providers or lists of providers but not both. For example, [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] is a valid value while [FooInfo, BarInfo, [BazInfo, QuxInfo]] is not valid.An unnested list of providers will automatically be converted to a list containing one list of providers. That is, To make some rule (e.g. |
required_aspect_providers
|
sequence;
default is [] This attribute allows this aspect to inspect other aspects. The value must be a list containing either individual providers or lists of providers but not both. For example, [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] is a valid value while [FooInfo, BarInfo, [BazInfo, QuxInfo]] is not valid.An unnested list of providers will automatically be converted to a list containing one list of providers. That is, To make another aspect (e.g. |
provides
|
sequence;
default is [] A list of providers that the implementation function must return. It is an error if the implementation function omits any of the types of providers listed here from its return value. However, the implementation function may return additional providers not listed here. Each element of the list is an |
requires
|
sequence of Aspects;
default is [] List of aspects required to be propagated before this aspect. |
fragments
|
sequence of strings;
default is [] List of names of configuration fragments that the aspect requires in target configuration. |
host_fragments
|
sequence of strings;
default is [] List of names of configuration fragments that the aspect requires in host configuration. |
toolchains
|
sequence;
default is [] If set, the set of toolchains this aspect requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. Toolchains will be found by checking the current platform, and provided to the aspect implementation via ctx.toolchain .
|
incompatible_use_toolchain_transition
|
bool;
default is False Deprecated, this is no longer in use and should be removed. |
doc
|
string; or None ;
default is None A description of the aspect that can be extracted by documentation generating tools. |
apply_to_generating_rules
|
bool;
default is False If true, the aspect will, when applied to an output file, instead apply to the output file's generating rule. For example, suppose an aspect propagates transitively through attribute `deps` and it is applied to target `alpha`. Suppose `alpha` has `deps = [':beta_output']`, where `beta_output` is a declared output of a target `beta`. Suppose `beta` has a target `charlie` as one of its `deps`. If `apply_to_generating_rules=True` for the aspect, then the aspect will propagate through `alpha`, `beta`, and `charlie`. If False, then the aspect will propagate only to `alpha`. False by default. |
exec_compatible_with
|
sequence of strings;
default is [] A list of constraints on the execution platform that apply to all instances of this aspect. |
exec_groups
|
dict; or None ;
default is None Dict of execution group name (string) to exec_group s. If set, allows aspects to run actions on multiple execution platforms within a single instance. See execution groups documentation for more info.
|
subrules
|
sequence of Subrules;
default is [] Experimental: list of subrules used by this aspect. |
configuration_field
LateBoundDefault configuration_field(fragment, name)References a late-bound default value for an attribute of type label. A value is 'late-bound' if it requires the configuration to be built before determining the value. Any attribute using this as a value must be private.
Example usage:
Defining a rule attribute:
'_foo': attr.label(default=configuration_field(fragment='java', name='toolchain'))
Accessing in rule implementation:
def _rule_impl(ctx): foo_info = ctx.attr._foo ...
Parameters
Parameter | Description |
---|---|
fragment
|
string;
required The name of a configuration fragment which contains the late-bound value. |
name
|
string;
required The name of the value to obtain from the configuration fragment. |
depset
depset depset(direct=None, order="default", *, transitive=None)Creates a depset. The
direct
parameter is a list of direct elements of the depset, and transitive
parameter is a list of depsets whose elements become indirect elements of the created depset. The order in which elements are returned when the depset is converted to a list is specified by the order
parameter. See the Depsets overview for more information.
All elements (direct and indirect) of a depset must be of the same type, as obtained by the expression type(x)
.
Because a hash-based set is used to eliminate duplicates during iteration, all elements of a depset should be hashable. However, this invariant is not currently checked consistently in all constructors. Use the --incompatible_always_check_depset_elements flag to enable consistent checking; this will be the default behavior in future releases; see Issue 10313.
In addition, elements must currently be immutable, though this restriction will be relaxed in future.
The order of the created depset should be compatible with the order of its transitive
depsets. "default"
order is compatible with any other order, all other orders are only compatible with themselves.
Parameters
Parameter | Description |
---|---|
direct
|
sequence; or None ;
default is None A list of direct elements of a depset. |
order
|
string;
default is "default" The traversal strategy for the new depset. See here for the possible values. |
transitive
|
sequence of depsets; or None ;
default is None A list of depsets whose elements will become indirect elements of the depset. |
exec_group
exec_group exec_group(toolchains=[], exec_compatible_with=[])Creates an execution group which can be used to create actions for a specific execution platform during rule implementation.
Parameters
Parameter | Description |
---|---|
toolchains
|
sequence;
default is [] The set of toolchains this execution group requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. |
exec_compatible_with
|
sequence of strings;
default is [] A list of constraints on the execution platform. |
exec_transition
transition exec_transition(implementation, inputs, outputs)A specialized version of
transition()
used to define the exec transition. See its documentation (or its implementation) for best practices. Only usable from the Bazel builtins.
Parameters
Parameter | Description |
---|---|
implementation
|
callable;
required |
inputs
|
sequence of strings;
required |
outputs
|
sequence of strings;
required |
macro
macro macro(implementation, attrs={}, inherit_attrs=None, finalizer=False, doc=None)Defines a symbolic macro, which may be called in
BUILD
files or macros (legacy or
symbolic) to define targets – possibly multiple ones.
The value returned by macro(...)
must be assigned to a global variable in a .bzl
file; the name of the global variable will be the macro symbol's name.
See Macros for a comprehensive guide on how to use symbolic macros.
Parameters
Parameter | Description |
---|---|
implementation
|
function;
required The Starlark function implementing this macro. The values of the macro's attributes are passed to the implementation function as keyword arguments. The implementation function must have at least two named parameters, name and visibility , and if the macro inherits
attributes (see inherit_attrs below), it must have a **kwargs residual
keyword parameter.
By convention, the implementation function should have a named parameter for any attribute that
the macro needs to examine, modify, or pass to non-"main" targets, while the "bulk" inherited
attributes which will be passed to the "main" target unchanged are passed as The implementation function must not return a value. Instead, the implementation function declares targets by calling rule or macro symbols. The name of any target or inner symbolic macro declared by a symbolic macro (including by any
Starlark function that the macro's implementation function transitively calls) must either equal
By default, targets declared by a symbolic macro (including by any Starlark function that the
macro's implementation function transitively calls) are visible only in the package containing the
.bzl file defining the macro. To declare targets visible externally, including to the caller of
the symbolic macro, the implementation function must set The following APIs are unavailable within a macro implementation function and any Starlark function it transitively calls:
|
attrs
|
dict;
default is {} A dictionary of the attributes this macro supports, analogous to rule.attrs. Keys are attribute names, and values are either attribute objects like attr.label_list(...) (see the attr
module), or None . A None entry means that the macro does not have an
attribute by that name, even if it would have otherwise inherited one via inherit_attrs
(see below).
The special Attributes whose names start with To limit memory usage, there is a cap on the number of attributes that may be declared. |
inherit_attrs
|
rule; or macro; or string; or None ;
default is None A rule symbol, macro symbol, or the name of a built-in common attribute list (see below) from which the macro should inherit attributes. If Note that if the return value of The inheritance mechanism works as follows:
When a non-mandatory attribute is inherited, the default value of the attribute is overridden
to be For example, the following macro inherits all attributes from def _my_cc_library_impl(name, visibility, tags, **kwargs): # Append a tag; tags attr was inherited from native.cc_library, and # therefore is None unless explicitly set by the caller of my_cc_library() my_tags = (tags or []) + ["my_custom_tag"] native.cc_library( name = name, visibility = visibility, tags = my_tags, **kwargs ) my_cc_library = macro( implementation = _my_cc_library_impl, inherit_attrs = native.cc_library, attrs = { "cxxopts": None, "copts": attr.string_list(default = ["-D_FOO"]), }, ) If By convention, a macro should pass inherited, non-overridden attributes unchanged to the "main"
rule or macro symbol which the macro is wrapping. Typically, most inherited attributes will not have
a parameter in the implementation function's parameter list, and will simply be passed via
|
finalizer
|
bool;
default is False Whether this macro is a rule finalizer, which is a macro that, regardless of its position in a BUILD file, is evaluated at the end of package loading, after all non-finalizer targets
have been defined.
Unlike ordinary symbolic macros, rule finalizers may call
|
doc
|
string; or None ;
default is None A description of the macro that can be extracted by documentation generating tools. |
module_extension
unknown module_extension(implementation, *, tag_classes={}, doc=None, environ=[], os_dependent=False, arch_dependent=False)Creates a new module extension. Store it in a global value, so that it can be exported and used in a MODULE.bazel file with
use_extension
.
Parameters
Parameter | Description |
---|---|
implementation
|
callable;
required The function that implements this module extension. Must take a single parameter, module_ctx . The function is called once at the beginning of a build to determine the set of available repos.
|
tag_classes
|
dict;
default is {} A dictionary to declare all the tag classes used by the extension. It maps from the name of the tag class to a tag_class object.
|
doc
|
string; or None ;
default is None A description of the module extension that can be extracted by documentation generating tools. |
environ
|
sequence of strings;
default is [] Provides a list of environment variable that this module extension depends on. If an environment variable in that list changes, the extension will be re-evaluated. |
os_dependent
|
bool;
default is False Indicates whether this extension is OS-dependent or not |
arch_dependent
|
bool;
default is False Indicates whether this extension is architecture-dependent or not |
provider
unknown provider(doc=None, *, fields=None, init=None)Defines a provider symbol. The resulting value of this function must be stored in a global value to be usable in a rule or aspect implementation. Providers can be instantiated by calling the resulting value as a function, or used directly as an index key for retrieving an instance of that provider from a target. Example:
MyInfo = provider() ... def _my_library_impl(ctx): ... my_info = MyInfo(x = 2, y = 3) # my_info.x == 2 # my_info.y == 3 ...
See Rules (Providers) for a comprehensive guide on how to use providers.
Returns a Provider
callable value if init
is not specified.
If init
is specified, returns a tuple of 2 elements: a Provider
callable value and a raw constructor callable value. See Rules (Custom initialization of custom providers) and the discussion of the init
parameter below for details.
Parameters
Parameter | Description |
---|---|
doc
|
string; or None ;
default is None A description of the provider that can be extracted by documentation generating tools. |
fields
|
sequence of strings; or dict; or None ;
default is None If specified, restricts the set of allowed fields. Possible values are:
|
init
|
callable; or None ;
default is None An optional callback for preprocessing and validating the provider's field values during instantiation. If init is specified, provider() returns a tuple of 2 elements: the normal provider symbol and a raw constructor.A precise description follows; see Rules (Custom initialization of providers) for an intuitive discussion and use cases. Let
init callback is not given, a call to the symbol P itself acts as a call to the default constructor function c ; in other words, P(*args, **kwargs) returns c(*args, **kwargs) . For example,MyInfo = provider() m = MyInfo(foo = 1)will straightforwardly make it so that m is a MyInfo instance with m.foo == 1 .But in the case where
NB: the above steps imply that an error occurs if In this way, the When MyInfo, _new_myinfo = provider(init = ...) |
repository_rule
callable repository_rule(implementation, *, attrs=None, local=False, environ=[], configure=False, remotable=False, doc=None)Creates a new repository rule. Store it in a global value, so that it can be loaded and called from a
module_extension()
implementation function, or used by use_repo_rule()
.
Parameters
Parameter | Description |
---|---|
implementation
|
callable;
required the function that implements this rule. Must have a single parameter, repository_ctx . The function is called during the loading phase for each instance of the rule.
|
attrs
|
dict; or None ;
default is None A dictionary to declare all the attributes of the repository rule. It maps from an attribute name to an attribute object (see attr module). Attributes starting with _ are private, and can be used to add an implicit dependency on a label to a file (a repository rule cannot depend on a generated artifact). The attribute name is implicitly added and must not be specified.
Declared attributes will convert |
local
|
bool;
default is False Indicate that this rule fetches everything from the local system and should be reevaluated at every fetch. |
environ
|
sequence of strings;
default is [] Deprecated. This parameter has been deprecated. Migrate to repository_ctx.getenv instead.Provides a list of environment variable that this repository rule depends on. If an environment variable in that list change, the repository will be refetched. |
configure
|
bool;
default is False Indicate that the repository inspects the system for configuration purpose |
remotable
|
bool;
default is False Experimental. This parameter is experimental and may change at any time. Please do not depend on it. It may be enabled on an experimental basis by setting --experimental_repo_remote_exec Compatible with remote execution |
doc
|
string; or None ;
default is None A description of the repository rule that can be extracted by documentation generating tools. |
rule
callable rule(implementation, *, test=unbound, attrs={}, outputs=None, executable=unbound, output_to_genfiles=False, fragments=[], host_fragments=[], _skylark_testable=False, toolchains=[], incompatible_use_toolchain_transition=False, doc=None, provides=[], dependency_resolution_rule=False, exec_compatible_with=[], analysis_test=False, build_setting=None, cfg=None, exec_groups=None, initializer=None, parent=None, extendable=None, subrules=[])Creates a new rule, which can be called from a BUILD file or a macro to create targets.
Rules must be assigned to global variables in a .bzl file; the name of the global variable is the rule's name.
Test rules are required to have a name ending in _test
, while all other rules must not have this suffix. (This restriction applies only to rules, not to their targets.)
Parameters
Parameter | Description |
---|---|
implementation
|
function;
required the Starlark function implementing this rule, must have exactly one parameter: ctx. The function is called during the analysis phase for each instance of the rule. It can access the attributes provided by the user. It must create actions to generate all the declared outputs. |
test
|
bool;
default is unbound Whether this rule is a test rule, that is, whether it may be the subject of a blaze test command. All test rules are automatically considered executable; it is unnecessary (and discouraged) to explicitly set executable = True for a test rule. The value defaults to False . See the Rules page for more information.
|
attrs
|
dict;
default is {} A dictionary to declare all the attributes of the rule. It maps from an attribute name to an attribute object (see attr module). Attributes starting with _ are private, and can be used to add an implicit dependency on a label. The attribute name is implicitly added and must not be specified. Attributes visibility , deprecation , tags , testonly , and features are implicitly added and cannot be overridden. Most rules need only a handful of attributes. To limit memory usage, there is a cap on the number of attributes that may be declared.
Declared attributes will convert |
outputs
|
dict; or None ; or function;
default is None Deprecated. This parameter is deprecated and will be removed soon. Please do not depend on it. It is disabled with --incompatible_no_rule_outputs_param . Use this flag to verify your code is compatible with its imminent removal. This parameter has been deprecated. Migrate rules to use OutputGroupInfo or attr.output instead. A schema for defining predeclared outputs. Unlike The value of this argument is either a dictionary or a callback function that produces a dictionary. The callback works similar to computed dependency attributes: The function's parameter names are matched against the rule's attributes, so for example if you pass Each entry in the dictionary creates a predeclared output where the key is an identifier and the value is a string template that determines the output's label. In the rule's implementation function, the identifier becomes the field name used to access the output's
In practice, the most common substitution placeholder is |
executable
|
bool;
default is unbound Whether this rule is considered executable, that is, whether it may be the subject of a blaze run command. It defaults to False . See the Rules page for more information.
|
output_to_genfiles
|
bool;
default is False If true, the files will be generated in the genfiles directory instead of the bin directory. Unless you need it for compatibility with existing rules (e.g. when generating header files for C++), do not set this flag. |
fragments
|
sequence of strings;
default is [] List of names of configuration fragments that the rule requires in target configuration. |
host_fragments
|
sequence of strings;
default is [] List of names of configuration fragments that the rule requires in host configuration. |
_skylark_testable
|
bool;
default is False (Experimental) If true, this rule will expose its actions for inspection by rules that depend on it via an Actions provider. The provider is also available to the rule itself by calling ctx.created_actions().This should only be used for testing the analysis-time behavior of Starlark rules. This flag may be removed in the future. |
toolchains
|
sequence;
default is [] If set, the set of toolchains this rule requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. Toolchains will be found by checking the current platform, and provided to the rule implementation via ctx.toolchain .
|
incompatible_use_toolchain_transition
|
bool;
default is False Deprecated, this is no longer in use and should be removed. |
doc
|
string; or None ;
default is None A description of the rule that can be extracted by documentation generating tools. |
provides
|
sequence;
default is [] A list of providers that the implementation function must return. It is an error if the implementation function omits any of the types of providers listed here from its return value. However, the implementation function may return additional providers not listed here. Each element of the list is an |
dependency_resolution_rule
|
bool;
default is False If set, the rule can be a dependency through attributes also marked as available in materializers. Every attribute of rules with this flag set must be marked as available in materializers also. This is so that rules so marked cannot depend on rules that are not so marked. |
exec_compatible_with
|
sequence of strings;
default is [] A list of constraints on the execution platform that apply to all targets of this rule type. |
analysis_test
|
bool;
default is False If true, then this rule is treated as an analysis test. Note: Analysis test rules are primarily defined using infrastructure provided in core Starlark libraries. See Testing for guidance. If a rule is defined as an analysis test rule, it becomes allowed to use configuration transitions defined using analysis_test_transition on its attributes, but opts into some restrictions:
|
build_setting
|
BuildSetting; or None ;
default is None If set, describes what kind of build setting this rule is. See the config module. If this is set, a mandatory attribute named "build_setting_default" is automatically added to this rule, with a type corresponding to the value passed in here.
|
cfg
|
default is None If set, points to the configuration transition the rule will apply to its own configuration before analysis. |
exec_groups
|
dict; or None ;
default is None Dict of execution group name (string) to exec_group s. If set, allows rules to run actions on multiple execution platforms within a single target. See execution groups documentation for more info.
|
initializer
|
default is None Experimental: the Stalark function initializing the attributes of the rule. The function is called at load time for each instance of the rule. It's called with It has to return a dictionary from the attribute names to the desired values. The attributes that are not returned are unaffected. Returning Initializers are evaluated before the default values specified in an attribute definition. Consequently, if a parameter in the initializer's signature contains a default values, it overwrites the default from the attribute definition (except if returning Similarly, if a parameter in the initializer's signature doesn't have a default, the parameter will become mandatory. It's a good practice to omit default/mandatory settings on an attribute definition in such cases. It's a good practice to use In case of extended rules, all initializers are called proceeding from child to ancestors. Each initializer is passed only the public attributes it knows about. |
parent
|
default is None Experimental: the Stalark rule that is extended. When set the public attributes are merged as well as advertised providers. The rule matches executable and test from the parent. Values of fragments , toolchains , exec_compatible_with , and exec_groups are merged. Legacy or deprecated parameters may not be set. Incoming configuration transition cfg of parent is applied after thisrule's incoming configuration.
|
extendable
|
bool; or Label; or string; or None ;
default is None Experimental: A label of an allowlist defining which rules can extending this rule. It can be set also to True/False to always allow/disallow extending. Bazel defaults to always allowing extensions. |
subrules
|
sequence of Subrules;
default is [] Experimental: List of subrules used by this rule. |
select
unknown select(x, no_match_error='')
select()
is the helper function that makes a rule attribute configurable. See build encyclopedia for details.
Parameters
Parameter | Description |
---|---|
x
|
dict;
required A dict that maps configuration conditions to values. Each key is a Label or a label string that identifies a config_setting or constraint_value instance. See the documentation on macros for when to use a Label instead of a string. |
no_match_error
|
string;
default is '' Optional custom error to report if no condition matches. |
subrule
Subrule subrule(implementation, attrs={}, toolchains=[], fragments=[], subrules=[])Constructs a new instance of a subrule. The result of this function must be stored in a global variable before it can be used.
Parameters
Parameter | Description |
---|---|
implementation
|
function;
required The Starlark function implementing this subrule |
attrs
|
dict;
default is {} A dictionary to declare all the (private) attributes of the subrule. Subrules may only have private attributes that are label-typed (i.e. label or label-list). The resolved values corresponding to these labels are automatically passed by Bazel to the subrule's implementation function as named arguments (thus the implementation function is required to accept named parameters matching the attribute names). The types of these values will be:
|
toolchains
|
sequence;
default is [] If set, the set of toolchains this subrule requires. The list can contain String, Label, or StarlarkToolchainTypeApi objects, in any combination. Toolchains will be found by checking the current platform, and provided to the subrule implementation via ctx.toolchains . Note that AEGs need to be enabled on the consuming rule(s) if this parameter is set. In case you haven't migrated to AEGs yet, see https://bazel.build/extending/auto-exec-groups#migration-aegs.
|
fragments
|
sequence of strings;
default is [] List of names of configuration fragments that the subrule requires in target configuration. |
subrules
|
sequence of Subrules;
default is [] List of other subrules needed by this subrule. |
tag_class
tag_class tag_class(attrs={}, *, doc=None)Creates a new tag_class object, which defines an attribute schema for a class of tags, which are data objects usable by a module extension.
Parameters
Parameter | Description |
---|---|
attrs
|
dict;
default is {} A dictionary to declare all the attributes of this tag class. It maps from an attribute name to an attribute object (see attr module). Note that unlike |
doc
|
string; or None ;
default is None A description of the tag class that can be extracted by documentation generating tools. |
visibility
None
visibility(value)
Sets the load visibility of the .bzl module currently being initialized.
The load visibility of a module governs whether or not other BUILD and .bzl files may load it. (This is distinct from the target visibility of the underlying .bzl source file, which governs whether the file may appear as a dependency of other targets.) Load visibility works at the level of packages: To load a module the file doing the loading must live in a package that has been granted visibility to the module. A module can always be loaded within its own package, regardless of its visibility.
visibility()
may only be called once per .bzl file, and only at the top level, not inside a function. The preferred style is to put this call immediately below the load()
statements and any brief logic needed to determine the argument.
If the flag --check_bzl_visibility
is set to false, load visibility violations will emit warnings but not fail the build.
Parameters
Parameter | Description |
---|---|
value
|
required A list of package specification strings, or a single package specification string. Package specifications follow the same format as for
The "@" syntax is not allowed; all specifications are interpreted relative to the current module's repository. If Note that the flags |