Gazelle

Gazelle is a build file generator for Bazel projects. It can create new BUILD.bazel files for a project that follows language conventions, and it can update existing build files to include new sources, dependencies, and options.

An alternative wrapper for Gazelle is built into the Aspect CLI via the aspect configure command. If you are already using that Aspect CLI we recommend using the configure task.

Setup

To add the gazelle tool as a workspace dependency see the official documentation at their GitHub README.md

In your root build file, add the following targets:

BUILD.bazel

load("@bazel_gazelle//:def.bzl", "gazelle", "gazelle_binary", "gazelle_test")

gazelle_binary(
    name = "gazelle_bin",
)

gazelle(
    name = "gazelle",
    gazelle = ":gazelle_bin",
)

gazelle_test(
    name = "gazelle.check",
    workspace = "//:BUILD.bazel",
)

Finally, add the following to your aspect.yaml configuration file:

tasks:
    - gazelle:
      fix_target: //:gazelle
      target: //:gazelle.check

Note that target and fix_target are currently set to their default values and can be safely omitted if you prefer a more terse configuration.

The Workflows gazelle task runs bazel run //:gazelle.check. If it exits non-zero, then the task fails. In the case of a failure, the task prints suggested changes that the developer should apply, by running bazel run //:gazelle.

Optional: Setup a bash script to enforce other behaviors

The following bash script demonstrates how to enforce additional desirable characteristics when using Gazelle with rules_go. This script can serve as a template for creating custom enforcement scripts tailored to other rule sets.

gazelle.check.sh

#!/usr/bin/env bash

set -o errexit -o nounset -o pipefail

readonly runfiles_dir="${PWD}"

PATH="$(dirname "${runfiles_dir}/${GO}"):${PATH}"
export PATH

# Enforce that go mod tidy has been run
cd "${BUILD_WORKSPACE_DIRECTORY}"
"${runfiles_dir}/${GO}" mod tidy

# Enforce that go.mod changes are reflected in generated deps.bzl file.
cd "${runfiles_dir}"
"${runfiles_dir}/${GAZELLE}" update-repos \
    -build_file_proto_mode=disable_global \
    -from_file=go.mod \
    -to_macro=deps.bzl%go_dependencies \
    -prune=true
cd "${BUILD_WORKSPACE_DIRECTORY}"
git diff --exit-code go.{mod,sum} deps.bzl

# Enforce that gazelle has no pending changes.
cd "${runfiles_dir}"
"${runfiles_dir}/${GAZELLE}" -mode=fix
cd "${BUILD_WORKSPACE_DIRECTORY}"
git diff --exit-code

This script performs the following checks:

1. Enforce that go mod tidy has been run
2. Enforce that go.mod changes are reflected in generated deps.bzl file.
3. Enforce that gazelle has no pending changes.

To use this script in your project:

1. Save it as check_gazelle.sh in your project root.
2. Make it executable: chmod +x check_gazelle.sh
3. Add the following target to your root BUILD.bazel file

BUILD.bazel

sh_binary(
    name = "gazelle.check",
    srcs = ["gazelle.check.sh"],
    data = [
        ":gazelle_bin",
        "@go_sdk//:bin/go",
    ],
    env = {
        "GO": "$(rootpath @go_sdk//:bin/go)",
        "GAZELLE": "$(rootpath :gazelle_bin)",
    },
)