In the following, a host machine is the machine where Bazel runs.
When using remote execution, the actual build and/or test steps are not happening on the host machine, but are instead sent off to the remote execution system. However, the steps involved in resolving workspace rules are happening on the host machine. If your workspace rules access information about the host machine for use during execution, your build is likely to break due to incompatibilities between the environments.
As part of adapting Bazel rules for remote execution, you need to find such workspace rules and fix them. This page describes how to find potentially problematic workspace rules using the workspace log.
Finding non-hermetic rules
Workspace rules allow the developer to add dependencies to
external workspaces, but they are rich enough to allow arbitrary processing to
happen in the process. All related commands are happening locally and can be a
potential source of non-hermeticity. Usually non-hermetic behavior is
repository_ctx which allows interacting
with the host machine.
Starting with Bazel 0.18, you can get a log of some potentially non-hermetic
actions by adding the flag
your Bazel command. Here
[PATH] is a filename under which the log will be
Things to note:
the log captures the events as they are executed. If some steps are cached, they will not show up in the log, so to get a full result, don't forget to run
bazel clean --expungebeforehand.
Sometimes functions might be re-executed, in which case the related events will show up in the log multiple times.
Workspace rules currently only log Starlark events.
To find what was executed during workspace initialization:
bazel clean --expunge. This command will clean your local cache and any cached repositories, ensuring that all initialization will be re-run.
--experimental_workspace_rules_log_file=/tmp/workspacelogto your Bazel command and run the build.
This produces a binary proto file listing messages of type WorkspaceEvent
Download the Bazel source code and navigate to the Bazel folder by using the command below. You need the source code to be able to parse the workspace log with the workspacelog parser.
git clone https://github.com/bazelbuild/bazel.git
In the Bazel source code repo, convert the whole workspace log to text.
bazel build src/tools/workspacelog:parser
bazel-bin/src/tools/workspacelog/parser --log_path=/tmp/workspacelog > /tmp/workspacelog.txt
The output may be quite verbose and include output from built in Bazel rules.
To exclude specific rules from the output, use
--exclude_ruleoption. For example:
bazel build src/tools/workspacelog:parser
bazel-bin/src/tools/workspacelog/parser --log_path=/tmp/workspacelog \ --exclude_rule "//external:local_config_cc" \ --exclude_rule "//external:dep" > /tmp/workspacelog.txt
/tmp/workspacelog.txtand check for unsafe operations.
The actions that have been highlighted as potentially non-hermetic are as follows:
execute: executes an arbitrary command on the host environment. Check if these may introduce any dependencies on the host environment.
download_and_extract: to ensure hermetic builds, make sure that sha256 is specified
template: this is not non-hermetic in itself, but may be a mechanism for introducing dependencies on the host environment into the repository. Ensure that you understand where the input comes from, and that it does not depend on the host environment.
os: this is not non-hermetic in itself, but an easy way to get dependencies on the host environment. A hermetic build would generally not call this. In evaluating whether your usage is hermetic, keep in mind that this is running on the host and not on the workers. Getting environment specifics from the host is generally not a good idea for remote builds.
symlink: this is normally safe, but look for red flags. Any symlinks to outside the repository or to an absolute path would cause problems on the remote worker. If the symlink is created based on host machine properties it would probably be problematic as well.
which: checking for programs installed on the host is usually problematic since the workers may have different configurations.