utils
General-purpose Starlark utility functions
Usage example
load("@aspect_bazel_lib//lib:utils.bzl", "utils")
out_label = utils.to_label(out_file)
Macros and Functions
utils.consistent_label_str
Generate a consistent label string for all Bazel versions.
Starting in Bazel 6, the workspace name is empty for the local workspace and there's no other way to determine it. This behavior differs from Bazel 5 where the local workspace name was fully qualified in str(label).
This utility function is meant for use in rules and requires the rule context to determine the
user's workspace name (ctx.workspace_name).
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "utils")
utils.consistent_label_str(
# The rule context.
ctx = None,
# A Label.
label = None,
)
ctx
Required.
The rule context.
label
Required.
A Label.
utils.default_timeout
Provide a sane default for *_test timeout attribute.
The test-encyclopedia says:
Tests may return arbitrarily fast regardless of timeout. A test is not penalized for an overgenerous timeout, although a warning may be issued: you should generally set your timeout as tight as you can without incurring any flakiness.
However Bazel's default for timeout is medium, which is dumb given this guidance.
It also says:
Tests which do not explicitly specify a timeout have one implied based on the test's size as follows
Therefore if size is specified, we should allow timeout to take its implied default.
If neither is set, then we can fix Bazel's wrong default here to avoid warnings under
--test_verbose_timeout_warnings.
This function can be used in a macro which wraps a testing rule.
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "utils")
utils.default_timeout(
# the size attribute of a test target
size = "",
# the timeout attribute of a test target
timeout = "",
)
size
Required.
the size attribute of a test target
timeout
Required.
the timeout attribute of a test target
utils.file_exists
Check whether a file exists.
Useful in macros to set defaults for a configuration file if it is present. This can only be called during the loading phase, not from a rule implementation.
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "utils")
utils.file_exists(
# a label, or a string which is a path relative to this package
path = None,
)
path
Required.
a label, or a string which is a path relative to this package
utils.glob_directories
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "utils")
utils.glob_directories(
include = [],
)
include
Required.
kwargs
Optional.
utils.is_bazel_6_or_greater
Detects if the Bazel version being used is greater than or equal to 6 (including Bazel 6 pre-releases and RCs).
Detecting Bazel 6 or greater is particularly useful in rules as slightly different code paths may be needed to support bzlmod which was added in Bazel 6.
Unlike the undocumented native.bazel_version, which only works in WORKSPACE and repository rules, this function can
be used in rules and BUILD files.
An alternate approach to make the Bazel version available in BUILD files and rules would be to
use the host_repo repository rule
which contains the bazel_version in the exported host struct:
WORKSPACE:
load("@aspect_bazel_lib//lib:host_repo.bzl", "host_repo")
host_repo(name = "aspect_bazel_lib_host")
BUILD.bazel:
load("@aspect_bazel_lib_host//:defs.bzl", "host")
print(host.bazel_version)
That approach, however, incurs a cost in the user's WORKSPACE.
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "utils")
utils.is_bazel_6_or_greater(
)
utils.is_bazel_7_or_greater
Detects if the Bazel version being used is greater than or equal to 7 (including Bazel 7 pre-releases and RCs).
Unlike the undocumented native.bazel_version, which only works in WORKSPACE and repository rules, this function can
be used in rules and BUILD files.
An alternate approach to make the Bazel version available in BUILD files and rules would be to
use the host_repo repository rule
which contains the bazel_version in the exported host struct:
WORKSPACE:
load("@aspect_bazel_lib//lib:host_repo.bzl", "host_repo")
host_repo(name = "aspect_bazel_lib_host")
BUILD.bazel:
load("@aspect_bazel_lib_host//:defs.bzl", "host")
print(host.bazel_version)
That approach, however, incurs a cost in the user's WORKSPACE.
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "utils")
utils.is_bazel_7_or_greater(
)
utils.is_bzlmod_enabled
Detect the value of the --enable_bzlmod flag
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "utils")
utils.is_bzlmod_enabled(
)
utils.is_external_label
Returns True if the given Label (or stringy version of a label) represents a target outside of the workspace
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "utils")
utils.is_external_label(
# a string or label
param = "",
)
param
Required.
a string or label
utils.maybe_http_archive
Adapts a maybe(http_archive, ...) to look like an http_archive.
This makes WORKSPACE dependencies easier to read and update.
Typical usage looks like,
load("//lib:utils.bzl", http_archive = "maybe_http_archive")
http_archive(
name = "aspect_rules_js",
sha256 = "5bb643d9e119832a383e67f946dc752b6d719d66d1df9b46d840509ceb53e1f1",
strip_prefix = "rules_js-1.6.2",
url = "https://github.com/aspect-build/rules_js/archive/refs/tags/v1.6.2.tar.gz",
)
instead of the classic maybe pattern of,
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
load("@bazel_tools//tools/build_defs/repo:utils.bzl", "maybe")
maybe(
http_archive,
name = "aspect_rules_js",
sha256 = "5bb643d9e119832a383e67f946dc752b6d719d66d1df9b46d840509ceb53e1f1",
strip_prefix = "rules_js-1.6.2",
url = "https://github.com/aspect-build/rules_js/archive/refs/tags/v1.6.2.tar.gz",
)
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "utils")
utils.maybe_http_archive(
)
kwargs
Optional.
all arguments to pass-forward to http_archive
utils.path_to_workspace_root
Returns the path to the workspace root under bazel
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "utils")
utils.path_to_workspace_root(
)
utils.propagate_common_binary_rule_attributes
Returns a dict of rule parameters filtered from the input dict that only contains the ones that are common to all binary rules
These are listed in Bazel's documentation: https://bazel.build/reference/be/common-definitions#common-attributes https://bazel.build/reference/be/common-definitions#common-attributes-binary
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "utils")
utils.propagate_common_binary_rule_attributes(
# Dict of parameters to filter
attrs = None,
)
attrs
Required.
Dict of parameters to filter
utils.propagate_common_rule_attributes
Returns a dict of rule parameters filtered from the input dict that only contains the ones that are common to all rules
These are listed in Bazel's documentation: https://bazel.build/reference/be/common-definitions#common-attributes
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "utils")
utils.propagate_common_rule_attributes(
# Dict of parameters to filter
attrs = None,
)
attrs
Required.
Dict of parameters to filter
utils.propagate_common_test_rule_attributes
Returns a dict of rule parameters filtered from the input dict that only contains the ones that are common to all test rules
These are listed in Bazel's documentation: https://bazel.build/reference/be/common-definitions#common-attributes https://bazel.build/reference/be/common-definitions#common-attributes-tests
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "utils")
utils.propagate_common_test_rule_attributes(
# Dict of parameters to filter
attrs = None,
)
attrs
Required.
Dict of parameters to filter
utils.propagate_well_known_tags
Returns a list of tags filtered from the input set that only contains the ones that are considered "well known"
These are listed in Bazel's documentation: https://docs.bazel.build/versions/main/test-encyclopedia.html#tag-conventions https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "utils")
utils.propagate_well_known_tags(
)
tags
Optional. Default: []
List of tags to filter
utils.to_label
Converts a string to a Label. If Label is supplied, the same label is returned.
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "utils")
utils.to_label(
# a string representing a label or a Label
param = "",
)
param
Required.
a string representing a label or a Label
default_timeout
Provide a sane default for *_test timeout attribute.
The test-encyclopedia says:
Tests may return arbitrarily fast regardless of timeout. A test is not penalized for an overgenerous timeout, although a warning may be issued: you should generally set your timeout as tight as you can without incurring any flakiness.
However Bazel's default for timeout is medium, which is dumb given this guidance.
It also says:
Tests which do not explicitly specify a timeout have one implied based on the test's size as follows
Therefore if size is specified, we should allow timeout to take its implied default.
If neither is set, then we can fix Bazel's wrong default here to avoid warnings under
--test_verbose_timeout_warnings.
This function can be used in a macro which wraps a testing rule.
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "default_timeout")
default_timeout(
# the size attribute of a test target
size = "",
# the timeout attribute of a test target
timeout = "",
)
size
Required.
the size attribute of a test target
timeout
Required.
the timeout attribute of a test target
file_exists
Check whether a file exists.
Useful in macros to set defaults for a configuration file if it is present. This can only be called during the loading phase, not from a rule implementation.
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "file_exists")
file_exists(
# a label, or a string which is a path relative to this package
path = None,
)
path
Required.
a label, or a string which is a path relative to this package
glob_directories
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "glob_directories")
glob_directories(
include = [],
)
include
Required.
kwargs
Optional.
is_bazel_6_or_greater
Detects if the Bazel version being used is greater than or equal to 6 (including Bazel 6 pre-releases and RCs).
Detecting Bazel 6 or greater is particularly useful in rules as slightly different code paths may be needed to support bzlmod which was added in Bazel 6.
Unlike the undocumented native.bazel_version, which only works in WORKSPACE and repository rules, this function can
be used in rules and BUILD files.
An alternate approach to make the Bazel version available in BUILD files and rules would be to
use the host_repo repository rule
which contains the bazel_version in the exported host struct:
WORKSPACE:
load("@aspect_bazel_lib//lib:host_repo.bzl", "host_repo")
host_repo(name = "aspect_bazel_lib_host")
BUILD.bazel:
load("@aspect_bazel_lib_host//:defs.bzl", "host")
print(host.bazel_version)
That approach, however, incurs a cost in the user's WORKSPACE.
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "is_bazel_6_or_greater")
is_bazel_6_or_greater(
)
is_bazel_7_or_greater
Detects if the Bazel version being used is greater than or equal to 7 (including Bazel 7 pre-releases and RCs).
Unlike the undocumented native.bazel_version, which only works in WORKSPACE and repository rules, this function can
be used in rules and BUILD files.
An alternate approach to make the Bazel version available in BUILD files and rules would be to
use the host_repo repository rule
which contains the bazel_version in the exported host struct:
WORKSPACE:
load("@aspect_bazel_lib//lib:host_repo.bzl", "host_repo")
host_repo(name = "aspect_bazel_lib_host")
BUILD.bazel:
load("@aspect_bazel_lib_host//:defs.bzl", "host")
print(host.bazel_version)
That approach, however, incurs a cost in the user's WORKSPACE.
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "is_bazel_7_or_greater")
is_bazel_7_or_greater(
)
is_bzlmod_enabled
Detect the value of the --enable_bzlmod flag
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "is_bzlmod_enabled")
is_bzlmod_enabled(
)
is_external_label
Returns True if the given Label (or stringy version of a label) represents a target outside of the workspace
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "is_external_label")
is_external_label(
# a string or label
param = "",
)
param
Required.
a string or label
maybe_http_archive
Adapts a maybe(http_archive, ...) to look like an http_archive.
This makes WORKSPACE dependencies easier to read and update.
Typical usage looks like,
load("//lib:utils.bzl", http_archive = "maybe_http_archive")
http_archive(
name = "aspect_rules_js",
sha256 = "5bb643d9e119832a383e67f946dc752b6d719d66d1df9b46d840509ceb53e1f1",
strip_prefix = "rules_js-1.6.2",
url = "https://github.com/aspect-build/rules_js/archive/refs/tags/v1.6.2.tar.gz",
)
instead of the classic maybe pattern of,
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
load("@bazel_tools//tools/build_defs/repo:utils.bzl", "maybe")
maybe(
http_archive,
name = "aspect_rules_js",
sha256 = "5bb643d9e119832a383e67f946dc752b6d719d66d1df9b46d840509ceb53e1f1",
strip_prefix = "rules_js-1.6.2",
url = "https://github.com/aspect-build/rules_js/archive/refs/tags/v1.6.2.tar.gz",
)
kwargs
Optional.
all arguments to pass-forward to http_archive
path_to_workspace_root
Returns the path to the workspace root under bazel
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "path_to_workspace_root")
path_to_workspace_root(
)
propagate_well_known_tags
Returns a list of tags filtered from the input set that only contains the ones that are considered "well known"
These are listed in Bazel's documentation: https://docs.bazel.build/versions/main/test-encyclopedia.html#tag-conventions https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "propagate_well_known_tags")
propagate_well_known_tags(
)
tags
Optional. Default: []
List of tags to filter
propagate_common_rule_attributes
Returns a dict of rule parameters filtered from the input dict that only contains the ones that are common to all rules
These are listed in Bazel's documentation: https://bazel.build/reference/be/common-definitions#common-attributes
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "propagate_common_rule_attributes")
propagate_common_rule_attributes(
# Dict of parameters to filter
attrs = None,
)
attrs
Required.
Dict of parameters to filter
propagate_common_test_rule_attributes
Returns a dict of rule parameters filtered from the input dict that only contains the ones that are common to all test rules
These are listed in Bazel's documentation: https://bazel.build/reference/be/common-definitions#common-attributes https://bazel.build/reference/be/common-definitions#common-attributes-tests
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "propagate_common_test_rule_attributes")
propagate_common_test_rule_attributes(
# Dict of parameters to filter
attrs = None,
)
attrs
Required.
Dict of parameters to filter
propagate_common_binary_rule_attributes
Returns a dict of rule parameters filtered from the input dict that only contains the ones that are common to all binary rules
These are listed in Bazel's documentation: https://bazel.build/reference/be/common-definitions#common-attributes https://bazel.build/reference/be/common-definitions#common-attributes-binary
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "propagate_common_binary_rule_attributes")
propagate_common_binary_rule_attributes(
# Dict of parameters to filter
attrs = None,
)
attrs
Required.
Dict of parameters to filter
to_label
Converts a string to a Label. If Label is supplied, the same label is returned.
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "to_label")
to_label(
# a string representing a label or a Label
param = "",
)
param
Required.
a string representing a label or a Label
consistent_label_str
Generate a consistent label string for all Bazel versions.
Starting in Bazel 6, the workspace name is empty for the local workspace and there's no other way to determine it. This behavior differs from Bazel 5 where the local workspace name was fully qualified in str(label).
This utility function is meant for use in rules and requires the rule context to determine the
user's workspace name (ctx.workspace_name).
Example usage (generated):
load("@aspect_bazel_lib//lib:utils.bzl", "consistent_label_str")
consistent_label_str(
# The rule context.
ctx = None,
# A Label.
label = None,
)
ctx
Required.
The rule context.
label
Required.
A Label.