BUILD file generation

Bazel expects BUILD files to be checked into the source repository, but their contents are expected to match the sources. For example, typically import statements in the source code translate to entries in the deps attribute of the corresponding *_library target.

This page documents how Aspect Workflows ensures that BUILD files are up-to-date.

Workflows supports two tools:

1. Aspect configure is the simplest to setup.
2. Gazelle may already be installed in the repository as a pair of targets.

One or both of these tools may be used.

Aspect Configure

Verify that BUILD files are up-to-date using the configure task in the Aspect Workflows configuration. This is built-in to the Aspect CLI, so no other setup is required. Note that the settings in .aspect/cli/config.yaml govern the behavior, such as which languages are enabled.

A simple configuration:

.aspect/workflows/config.yaml

tasks:
    - configure:

This will run aspect configure and verify that no files are changed.

If BUILD file updates are needed, the task will fail, and recommend that developers remediate the failure by running aspect configure. It will also print the delta which developers could manually apply.

In addition, aspect configure supports custom logic to determine what should be generated. See Starlark Extensions for configure.

Gazelle

Verify that BUILD files are up-to-date using the gazelle task in the Aspect Workflows configuration. First, Gazelle must be setup following the steps in their README

A simple configuration:

.aspect/workflows/config.yaml

tasks:
    - gazelle:

This will run bazel run //:gazelle.check and verify that it produced a zero exit code.

If the command exits non-zero, then the task will fail, and it will recommend that developers run bazel run //:gazelle. It will also print the delta which developers could manually apply.

Customizing the Gazelle targets

The two targets above may be specified in the configuration:

.aspect/workflows/config.yaml

tasks:
    - gazelle:
        # Workflows will 'bazel run' this target to determine if the BUILD files are up-to-date
        target: //path/to:gazelle-check-target
        # Developers will be asked to 'bazel run' this target to update their BUILD files
        fix_target: //path/to:gazelle-target

Following the Gazelle documentation, note that the "check" target should use mode=diff, while the "fix" target should use mode=fix.