Globals

Objects, functions and modules registered in the global environment.

Methods

all

bool all(elements)

Returns true if all elements evaluate to True or if the collection is empty. Elements are converted to boolean using the bool function.
all(["hello", 3, True]) == True
all([-1, 0, 1]) == False

Parameters

Parameter Description
elements

A string or a collection of elements.

analysis_test_transition

transition analysis_test_transition(settings)

Experimental. This type is experimental and subject to change at any time. Do not depend on it.

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.

Parameters

Parameter Description
settings

dict

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.

any

bool any(elements)

Returns true if at least one element evaluates to True. Elements are converted to boolean using the bool function.
any([-1, 0, 1]) == True
any([False, 0, ""]) == False

Parameters

Parameter Description
elements

A string or a collection of elements.

aspect

Aspect aspect(implementation, attr_aspects=[], attrs=None, required_aspect_providers=[], provides=[], fragments=[], host_fragments=[], toolchains=[], doc='')

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

the function implementing this aspect. Must have two parameters: Target (the target to which the aspect is applied) and ctx. Attributes of the target are available via ctx.rule field. The function is called during the analysis phase for each application of an aspect to a target.
attr_aspects

sequence of strings

List of attribute names. The aspect propagates along dependencies specified by attributes of a target with this name. The list can also contain a single string '*': in that case aspect propagates along all dependencies of a target.
attrs

dict

dictionary to declare all the attributes of the aspect. It maps from an attribute name to an attribute object (see attr module). Aspect attributes are available to implementation function as fields of ctx parameter. Implicit attributes starting with _ must have default values, and have type label or label_list. Explicit attributes must have type string, and must use the values restriction. If explicit attributes are present, the aspect can only be used with rules that have attributes of the same name and type, with valid values.
required_aspect_providers

sequence

Allow the aspect to inspect other aspects. If the aspect propagates along a dependency, and the underlying rule sends a different aspect along that dependency, and that aspect provides one of the providers listed here, this aspect will see the providers provided by that aspect.

The value should be either a list of providers, or a list of lists of providers. This aspect will 'see' the underlying aspects that provide ALL providers from at least ONE of these lists. A single list of providers will be automatically converted to a list containing one list of providers.
provides

sequence

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 *Info object returned by provider(), except that a legacy provider is represented by its string name instead.
fragments

sequence of strings

List of names of configuration fragments that the aspect requires in target configuration.
host_fragments

sequence of strings

List of names of configuration fragments that the aspect requires in host configuration.
toolchains

sequence of strings

(Experimental)

If set, the set of toolchains this rule requires. Toolchains will be found by checking the current platform, and provided to the rule implementation via ctx.toolchain.
doc

string

A description of the aspect that can be extracted by documentation generating tools.

bool

bool bool(x)

Constructor for the bool type. It returns False if the object is None, False, an empty string (""), the number 0, or an empty collection (e.g. (), []). Otherwise, it returns True.

Parameters

Parameter Description
x

The variable to convert.

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

The name of a configuration fragment which contains the late-bound value.
name

string

The name of the value to obtain from the configuration fragment.

depset

depset depset(items=[], order="default", *, direct=None, 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.

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.

Note on backward/forward compatibility. This function currently accepts a positional items parameter. It is deprecated and will be removed in the future, and after its removal direct will become a sole positional parameter of the depset function. Thus, both of the following calls are equivalent and future-proof:

depset(['a', 'b'], transitive = [...])
depset(direct = ['a', 'b'], transitive = [...])

Parameters

Parameter Description
items

Deprecated: Either an iterable whose items become the direct elements of the new depset, in left-to-right order, or else a depset that becomes a transitive element of the new depset. In the latter case, transitive cannot be specified.
order

string

The traversal strategy for the new depset. See here for the possible values.
direct

sequence

A list of direct elements of a depset.
transitive

sequence of depsets

A list of depsets whose elements will become indirect elements of the depset.

dict

dict dict(args=[], **kwargs)

Creates a dictionary from an optional positional argument and an optional set of keyword arguments. In the case where the same key is given multiple times, the last value will be used. Entries supplied via keyword arguments are considered to come after entries supplied via the positional argument.

Parameters

Parameter Description
args

Either a dictionary or a list of entries. Entries must be tuples or lists with exactly two elements: key, value.
kwargs

Dictionary of additional entries.

dir

list dir(x)

Returns a list of strings: the names of the attributes and methods of the parameter object.

Parameters

Parameter Description
x

The object to check.

enumerate

list enumerate(list)

Returns a list of pairs (two-element tuples), with the index (int) and the item from the input list. 
enumerate([24, 21, 84]) == [(0, 24), (1, 21), (2, 84)]

Parameters

Parameter Description
list

sequence

input list.

fail

None fail(msg, attr=None)

Raises an error that cannot be intercepted. It can be used anywhere, both in the loading phase and in the analysis phase.

Parameters

Parameter Description
msg

Error to display for the user. The object is converted to a string.
attr

string

The name of the attribute that caused the error. This is used only for error reporting.

False

bool

Literal for the boolean false.

getattr

unknown getattr(x, name, default=unbound)

Returns the struct's field of the given name if it exists. If not, it either returns default (if specified) or raises an error. Built-in methods cannot currently be retrieved in this way; doing so will result in an error if a default is not given. getattr(x, "foobar") is equivalent to x.foobar.
getattr(ctx.attr, "myattr")
getattr(ctx.attr, "myattr", "mydefault")

Parameters

Parameter Description
x

The struct whose attribute is accessed.
name

The name of the struct attribute.
default

The default value to return in case the struct doesn't have an attribute of the given name.

hasattr

bool hasattr(x, name)

Returns True if the object x has an attribute or method of the given name, otherwise False. Example:
hasattr(ctx.attr, "myattr")

Parameters

Parameter Description
x

The object to check.
name

string

The name of the attribute.

hash

int hash(value)

Return a hash value for a string. This is computed deterministically using the same algorithm as Java's String.hashCode(), namely: 
s[0] * (31^(n-1)) + s[1] * (31^(n-2)) + ... + s[n-1]
Hashing of values besides strings is not currently supported.

Parameters

Parameter Description
value

string

String value to hash.

int

int int(x, base=unbound)

Returns x as an int value.
  • If x is already an int, it is returned as-is.
  • If x is a boolean, a true value returns 1 and a false value returns 0.
  • If x is a string, it must have the format <sign><prefix><digits>. <sign> is either "+", "-", or empty (interpreted as positive). <digits> are a sequence of digits from 0 up to base - 1, where the letters a-z (or equivalently, A-Z) are used as digits for 10-35. In the case where base is 2/8/16, <prefix> is optional and may be 0b/0o/0x (or equivalently, 0B/0O/0X) respectively; if the base is any other value besides these bases or the special value 0, the prefix must be empty. In the case where base is 0, the string is interpreted as an integer literal, in the sense that one of the bases 2/8/10/16 is chosen depending on which prefix if any is used. If base is 0, no prefix is used, and there is more than one digit, the leading digit cannot be 0; this is to avoid confusion between octal and decimal. The magnitude of the number represented by the string must be within the allowed range for the int type.
This function fails if x is any other type, or if the value is a string not satisfying the above format. Unlike Python's int() function, this function does not allow zero arguments, and does not allow extraneous whitespace for string arguments.

Examples:

int("123") == 123
int("-123") == -123
int("+123") == 123
int("FF", 16) == 255
int("0xFF", 16) == 255
int("10", 0) == 10
int("-0x10", 0) == -16

Parameters

Parameter Description
x

The string to convert.
base

The base used to interpret a string value; defaults to 10. Must be between 2 and 36 (inclusive), or 0 to detect the base as if x were an integer literal. This parameter must not be supplied if the value is not a string.

len

int len(x)

Returns the length of a string, list, tuple, depset, or dictionary.

Parameters

Parameter Description
x

The object to check length of.

list

list list(x)

Converts a collection (e.g. list, tuple or dictionary) to a list.
list([1, 2]) == [1, 2]
list((2, 3, 2)) == [2, 3, 2]
list({5: "a", 2: "b", 4: "c"}) == [5, 2, 4]

Parameters

Parameter Description
x

The object to convert.

max

unknown max(*args)

Returns the largest one of all given arguments. If only one argument is provided, it must be a non-empty iterable.It is an error if elements are not comparable (for example int with string). 
max(2, 5, 4) == 5
max([5, 6, 3]) == 6

Parameters

Parameter Description
args

sequence

The elements to be checked.

min

unknown min(*args)

Returns the smallest one of all given arguments. If only one argument is provided, it must be a non-empty iterable. It is an error if elements are not comparable (for example int with string). 
min(2, 5, 4) == 2
min([5, 6, 3]) == 3

Parameters

Parameter Description
args

sequence

The elements to be checked.

None

None

Literal for the None value.

PACKAGE_NAME

string

Deprecated. Use package_name() instead. The name of the package being evaluated. For example, in the BUILD file some/package/BUILD, its value will be some/package. If the BUILD file calls a function defined in a .bzl file, PACKAGE_NAME will match the caller BUILD file package. In .bzl files, do not access PACKAGE_NAME at the file-level (outside of functions), either directly or by calling a function at the file-level that accesses PACKAGE_NAME (PACKAGE_NAME is only defined during BUILD file evaluation).Here is an example of a .bzl file:
# a = PACKAGE_NAME  # not allowed outside functions
def extension():
  return PACKAGE_NAME
In this case, extension() can be called from a BUILD file (even indirectly), but not in a file-level expression in the .bzl file. When implementing a rule, use ctx.label to know where the rule comes from.

print

None print(*args, *, sep=" ")

Prints args as debug output. It will be prefixed with the string "DEBUG" and the location (file and line number) of this call. The exact way in which the arguments are converted to strings is unspecified and may change at any time. In particular, it may be different from (and more detailed than) the formatting done by str() and repr().

Using print in production code is discouraged due to the spam it creates for users. For deprecations, prefer a hard error using fail() whenever possible.

Parameters

Parameter Description
sep

string

The separator string between the objects, default is space (" ").
args

The objects to print.

provider

Provider provider(doc='', *, fields=None)

Creates a declared provider 'constructor'. The return value of this function can be used to create "struct-like" values. Example:
data = provider()
d = data(x = 2, y = 3)
print(d.x + d.y) # prints 5

Parameters

Parameter Description
doc

string

A description of the provider that can be extracted by documentation generating tools.
fields

sequence of strings; or dict

If specified, restricts the set of allowed fields.
Possible values are:

  • list of fields:
    provider(fields = ['a', 'b'])

  • dictionary field name -> documentation:
    provider(
       fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' })
All fields are optional.

range

sequence range(start_or_stop, stop_or_none=None, step=1)

Creates a list where items go from start to stop, using a step increment. If a single argument is provided, items will range from 0 to that element.
range(4) == [0, 1, 2, 3]
range(3, 9, 2) == [3, 5, 7]
range(3, 0, -1) == [3, 2, 1]

Parameters

Parameter Description
start_or_stop

int

Value of the start element if stop is provided, otherwise value of stop and the actual start is 0
stop_or_none

int

optional index of the first item not to be included in the resulting list; generation of the list stops before stop is reached.
step

int

The increment (default is 1). It may be negative.

register_execution_platforms

None register_execution_platforms(*platform_labels)

Registers a platform so that it is available to execute actions.

Parameters

Parameter Description
platform_labels

sequence of strings

The labels of the platforms to register.

register_toolchains

None register_toolchains(*toolchain_labels)

Registers a toolchain created with the toolchain() rule so that it is available for toolchain resolution.

Parameters

Parameter Description
toolchain_labels

sequence of strings

The labels of the toolchains to register.

REPOSITORY_NAME

string

Deprecated. Use repository_name() instead. The name of the repository the rule or build extension is called from. For example, in packages that are called into existence by the WORKSPACE stanza local_repository(name='local', path=...) it will be set to @local. In packages in the main repository, it will be set to @. It can only be accessed in functions (transitively) called from BUILD files, i.e. it follows the same restrictions as PACKAGE_NAME.

repository_rule

function repository_rule(implementation, *, attrs=None, local=False, environ=[])

Creates a new repository rule. Store it in a global value, so that it can be loaded and called from the WORKSPACE file.

Parameters

Parameter Description
implementation

function

the function implementing this rule, has to have exactly one parameter: repository_ctx. The function is called during loading phase for each instance of the rule.
attrs

dict

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 to a file (a repository rule cannot depend on a generated artifact). The attribute name is implicitly added and must not be specified.
local

bool

Indicate that this rule fetches everything from the local system and should be reevaluated at every fetch.
environ

sequence of strings

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.

repr

string repr(x)

Converts any object to a string representation. This is useful for debugging.
repr("ab") == '"ab"'

Parameters

Parameter Description
x

The object to convert.

reversed

list reversed(sequence)

Returns a list that contains the elements of the original sequence in reversed order.
reversed([3, 5, 4]) == [4, 5, 3]

Parameters

Parameter Description
sequence

The sequence to be reversed (string, list or tuple).

rule

function rule(implementation, test=False, attrs=None, outputs=None, executable=False, output_to_genfiles=False, fragments=[], host_fragments=[], _skylark_testable=False, toolchains=[], doc='', *, provides=[], execution_platform_constraints_allowed=False, exec_compatible_with=[], analysis_test=unbound, build_setting=None, cfg=None)

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

the 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

Whether this rule is a test rule, that is, whether it may be the subject of a bazel test command. All test rules are automatically considered executable; it is unnecessary (and discouraged) to explicitly set executable = True for a test rule. See the Rules page for more information.
attrs

dict

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.
outputs

dict; or None; or function

Experimental: This API is in the process of being redesigned.

A schema for defining predeclared outputs. Unlike output and output_list attributes, the user does not specify the labels for these files. See the Rules page for more on predeclared outputs.

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 outputs = _my_func with the definition def _my_func(srcs, deps): ..., the function has access to the attributes srcs and deps. Whether the dictionary is specified directly or via a function, it is interpreted as follows.

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 File in ctx.outputs. The output's label has the same package as the rule, and the part after the package is produced by substituting each placeholder of the form "%{ATTR}" with a string formed from the value of the attribute ATTR:

  • String-typed attributes are substituted verbatim.
  • Label-typed attributes become the part of the label after the package, minus the file extension. For example, the label "//pkg:a/b.c" becomes "a/b".
  • Output-typed attributes become the part of the label after the package, including the file extension (for the above example, "a/b.c").
  • All list-typed attributes (for example, attr.label_list) used in placeholders are required to have exactly one element. Their conversion is the same as their non-list version (attr.label).
  • Other attribute types may not appear in placeholders.
  • The special non-attribute placeholders %{dirname} and %{basename} expand to those parts of the rule's label, excluding its package. For example, in "//pkg:a/b.c", the dirname is a and the basename is b.c.

In practice, the most common substitution placeholder is "%{name}". For example, for a target named "foo", the outputs dict {"bin": "%{name}.exe"} predeclares an output named foo.exe that is accessible in the implementation function as ctx.outputs.bin.
executable

bool

Whether this rule is considered executable, that is, whether it may be the subject of a bazel run command. See the Rules page for more information.
output_to_genfiles

bool

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

List of names of configuration fragments that the rule requires in target configuration.
host_fragments

sequence of strings

List of names of configuration fragments that the rule requires in host configuration.
_skylark_testable

bool

(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 of strings

(Experimental)

If set, the set of toolchains this rule requires. Toolchains will be found by checking the current platform, and provided to the rule implementation via ctx.toolchain.
doc

string

A description of the rule that can be extracted by documentation generating tools.
provides

sequence

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 *Info object returned by provider(), except that a legacy provider is represented by its string name instead.
execution_platform_constraints_allowed

bool

If true, a special attribute named exec_compatible_with of label-list type is added, which must not already exist in attrs. Targets may use this attribute to specify additional constraints on the execution platform beyond those given in the exec_compatible_with argument to rule().
exec_compatible_with

sequence of strings

A list of constraints on the execution platform that apply to all targets of this rule type.
analysis_test

bool; or UnboundMarker

Experimental: This parameter is experimental and subject to change at any time.

If true, then this rule is treated as an analysis test.
build_setting

BuildSetting

Experimental: This parameter is experimental and subject to change at any time.

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 automaticallyadded to this rule, with a type corresponding to the value passed in here.
cfg

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_starlark_config_transition
If set, points to the configuration transition the rule will apply to its own configuration before analysis.

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

The parameter to convert.
no_match_error

string

Optional custom error to report if no condition matches.

sorted

list sorted(self)

Sort a collection. Elements should all belong to the same orderable type, they are sorted by their value (in ascending order). It is an error if elements are not comparable (for example int with string).
sorted([3, 5, 4]) == [3, 4, 5]

Parameters

Parameter Description
self

This collection.

str

string str(x)

Converts any object to string. This is useful for debugging.
str("ab") == "ab"
str(8) == "8"

Parameters

Parameter Description
x

The object to convert.

True

bool

Literal for the boolean true.

tuple

tuple tuple(x)

Converts a collection (e.g. list, tuple or dictionary) to a tuple.
tuple([1, 2]) == (1, 2)
tuple((2, 3, 2)) == (2, 3, 2)
tuple({5: "a", 2: "b", 4: "c"}) == (5, 2, 4)

Parameters

Parameter Description
x

The object to convert.

type

string type(x)

Returns the type name of its argument. This is useful for debugging and type-checking. Examples:
type(2) == "int"
type([1]) == "list"
type(struct(a = 2)) == "struct"
This function might change in the future. To write Python-compatible code and be future-proof, use it only to compare return values: 
if type(x) == type([]):  # if x is a list

Parameters

Parameter Description
x

The object to check type of.

workspace

sequence workspace(name)

Sets the name for this workspace. Workspace names should be a Java-package-style description of the project, using underscores as separators, e.g., github.com/bazelbuild/bazel should use com_github_bazelbuild_bazel. Names must start with a letter and can only contain letters, numbers, and underscores.

Parameters

Parameter Description
name

string

the name of the workspace.

zip

list zip(*args)

Returns a list of tuples, where the i-th tuple contains the i-th element from each of the argument sequences or iterables. The list has the size of the shortest input. With a single iterable argument, it returns a list of 1-tuples. With no arguments, it returns an empty list. Examples:
zip()  # == []
zip([1, 2])  # == [(1,), (2,)]
zip([1, 2], [3, 4])  # == [(1, 3), (2, 4)]
zip([1, 2], [3, 4, 5])  # == [(1, 3), (2, 4)]

Parameters

Parameter Description
args

lists to zip.