Skip to main content
Version: 1.24.x

utils

Public API

Macros and Functions

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_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

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