Methods available in BUILD files. See also the Build Encyclopedia for extra functions and build rules, which can also be used in BUILD files.
Members
- depset
- existing_rule
- existing_rules
- exports_files
- glob
- module_name
- module_version
- package
- package_group
- package_name
- package_relative_label
- repo_name
- repository_name
- select
- subpackages
depset
depset depset(direct=None, order="default", *, transitive=None)
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. |
existing_rule
unknown existing_rule(name)
None
if no rule instance of that name exists.Here, an immutable dict-like object means a deeply immutable object x
supporting dict-like iteration, len(x)
, name in x
, x[name]
, x.get(name)
, x.items()
, x.keys()
, and x.values()
.
The result contains an entry for each attribute, with the exception of private ones (whose names do not start with a letter) and a few unrepresentable legacy attribute types. In addition, the dict contains entries for the rule instance's name
and kind
(for example, 'cc_binary'
).
The values of the result represent attribute values as follows:
- Attributes of type str, int, and bool are represented as is.
- Labels are converted to strings of the form
':foo'
for targets in the same package or'//pkg:name'
for targets in a different package. - Lists are represented as tuples, and dicts are converted to new, mutable dicts. Their elements are recursively converted in the same fashion.
select
values are returned with their contents transformed as described above.- Attributes for which no value was specified during rule instantiation and whose default value is computed are excluded from the result. (Computed defaults cannot be computed until the analysis phase.).
If possible, avoid using this function. It makes BUILD files brittle and order-dependent. Also, beware that it differs subtly from the two other conversions of rule attribute values from internal form to Starlark: one used by computed defaults, the other used by ctx.attr.foo
.
Parameters
Parameter | Description |
---|---|
name
|
string;
required The name of the target. |
existing_rules
unknown existing_rules()
existing_rule(name)
.Here, an immutable dict-like object means a deeply immutable object x
supporting dict-like iteration, len(x)
, name in x
, x[name]
, x.get(name)
, x.items()
, x.keys()
, and x.values()
.
Note: If possible, avoid using this function. It makes BUILD files brittle and order-dependent.
exports_files
None
exports_files(srcs, visibility=None, licenses=None)
Parameters
Parameter | Description |
---|---|
srcs
|
sequence of strings;
required The list of files to export. |
visibility
|
sequence; or None ;
default is None A visibility declaration can to be specified. The files will be visible to the targets specified. If no visibility is specified, the files will be visible to every package. |
licenses
|
sequence of strings; or None ;
default is None Licenses to be specified. |
glob
sequence glob(include=[], exclude=[], exclude_directories=1, allow_empty=unbound)
- Matches at least one pattern in
include
. - Does not match any of the patterns in
exclude
(default[]
).
exclude_directories
argument is enabled (set to 1
), files of type directory will be omitted from the results (default 1
).
Parameters
Parameter | Description |
---|---|
include
|
sequence of strings;
default is [] The list of glob patterns to include. |
exclude
|
sequence of strings;
default is [] The list of glob patterns to exclude. |
exclude_directories
|
int;
default is 1 A flag whether to exclude directories or not. |
allow_empty
|
default is unbound Whether we allow glob patterns to match nothing. If `allow_empty` is False, each individual include pattern must match something and also the final result must be non-empty (after the matches of the `exclude` patterns are excluded). |
module_name
string module_name()
module.name
field seen in module_ctx.modules
.
May return None
.
module_version
string module_version()
module.version
field seen in module_ctx.modules
.
May return None
.
package
unknown package(**kwargs)
load()
statements.
Parameters
Parameter | Description |
---|---|
kwargs
|
required See the package() function in the Build Encyclopedia for applicable arguments.
|
package_group
None
package_group(name, packages=[], includes=[])
visibility
attributes.
Parameters
Parameter | Description |
---|---|
name
|
string;
required The unique name for this rule. |
packages
|
sequence of strings;
default is [] A complete enumeration of packages in this group. |
includes
|
sequence of strings;
default is [] Other package groups that are included in this one. |
package_name
string package_name()
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.
package_relative_label
Label package_relative_label(input)
BUILD
file for which the current macro is executing). If the input is already a Label
, it is returned unchanged.This function may only be called while evaluating a BUILD file and the macros it directly or indirectly calls; it may not be called in (for instance) a rule implementation function.
The result of this function is the same Label
value as would be produced by passing the given string to a label-valued attribute of a target declared in the BUILD file.
Usage note: The difference between this function and Label() is that Label()
uses the context of the package of the .bzl
file that called it, not the package of the BUILD
file. Use Label()
when you need to refer to a fixed target that is hardcoded into the macro, such as a compiler. Use package_relative_label()
when you need to normalize a label string supplied by the BUILD file to a Label
object. (There is no way to convert a string to a Label
in the context of a package other than the BUILD file or the calling .bzl file. For that reason, outer macros should always prefer to pass Label objects to inner macros rather than label strings.)
Parameters
Parameter | Description |
---|---|
input
|
string; or Label;
required The input label string or Label object. If a Label object is passed, it's returned as is. |
repo_name
string repo_name()
repository_name
string repository_name()
--+incompatible_enable_deprecated_label_apis
Deprecated. Prefer to use
repo_name
instead, which doesn't contain the spurious leading at-sign, but behaves identically otherwise.The canonical name of the repository containing the package currently being evaluated, with a single at-sign (@
) prefixed. 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 @
.
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. |
subpackages
sequence subpackages(include, exclude=[], allow_empty=False)
Parameters
Parameter | Description |
---|---|
include
|
sequence of strings;
required The list of glob patterns to include in subpackages scan. |
exclude
|
sequence of strings;
default is [] The list of glob patterns to exclude from subpackages scan. |
allow_empty
|
bool;
default is False Whether we fail if the call returns an empty list. By default empty list indicates potential error in BUILD file where the call to subpackages() is superflous. Setting to true allows this function to succeed in that case. |