bazel-lib/docs/utils.md

Public API

default_timeout

default_timeout(size, 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.

PARAMETERS

Name	Description	Default Value
size	the size attribute of a test target	none
timeout	the timeout attribute of a test target	none

RETURNS

"short" if neither is set, otherwise timeout

file_exists

file_exists(path)

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.

PARAMETERS

Name	Description	Default Value
path	a label, or a string which is a path relative to this package	none

glob_directories

glob_directories(include, kwargs)

PARAMETERS

Name	Description	Default Value
include	-	none
kwargs	-	none

is_external_label

is_external_label(param)

Returns True if the given Label (or stringy version of a label) represents a target outside of the workspace

PARAMETERS

Name	Description	Default Value
param	a string or label	none

RETURNS

a bool

path_to_workspace_root

path_to_workspace_root()

Returns the path to the workspace root under bazel

RETURNS

Path to the workspace root

propagate_well_known_tags

propagate_well_known_tags(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

PARAMETERS

Name	Description	Default Value
tags	List of tags to filter	[]

RETURNS

List of tags that only contains the well known set

to_label

to_label(param)

Converts a string to a Label. If Label is supplied, the same label is returned.

PARAMETERS

Name	Description	Default Value
param	a string representing a label or a Label	none

RETURNS

a Label