Gazelle is a build file generator for Go projects. It can create new BUILD.bazel files for a project that follows "go build" conventions, and it can update existing build files to include new files and options. Gazelle can be invoked directly in a project workspace, or it can be run on an external repository during the build as part of the go_repository rule.
Gazelle is under active development. Its interface and the rules it generates may change. Gazelle is not an official Google product.
Contents
See also:
To use Gazelle in a new project, add the bazel_gazelle repository and its
dependencies to your WORKSPACE file before go_rules_dependencies is called.
It should look like this:
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
name = "io_bazel_rules_go",
urls = ["https://github.com/bazelbuild/rules_go/releases/download/0.12.0/rules_go-0.12.0.tar.gz"],
sha256 = "c1f52b8789218bb1542ed362c4f7de7052abcf254d865d96fb7ba6d44bc15ee3",
)
http_archive(
name = "bazel_gazelle",
urls = ["https://github.com/bazelbuild/bazel-gazelle/releases/download/0.12.0/bazel-gazelle-0.12.0.tar.gz"],
sha256 = "ddedc7aaeb61f2654d7d7d4fd7940052ea992ccdb031b8f9797ed143ac7e8d43",
)
load("@io_bazel_rules_go//go:def.bzl", "go_rules_dependencies", "go_register_toolchains")
go_rules_dependencies()
go_register_toolchains()
load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies")
gazelle_dependencies()Add the code below to the BUILD or BUILD.bazel file in the root directory
of your repository. Replace the string in prefix with the portion of
your import path that corresponds to your repository.
load("@bazel_gazelle//:def.bzl", "gazelle")
gazelle(
name = "gazelle",
prefix = "github.com/example/project",
)After adding this code, you can run Gazelle with Bazel.
$ bazel run //:gazelle
This will generate new BUILD.bazel files for your project. You can run the same command in the future to update existing BUILD.bazel files to include new source files or options.
You can pass additional arguments to Gazelle after a -- argument. This
can be used to run alternate commands like update-repos that the gazelle
rule does not support directly.
$ bazel run //:gazelle -- update-repos -from_file=Gopkg.lock
If you have a Go SDK installed, you can install Gazelle in your GOPATH with
the command below:
go get -u github.com/bazelbuild/bazel-gazelle/cmd/gazelle
Make sure to re-run this command to upgrade Gazelle whenever you upgrade rules_go in your repository.
To generate BUILD.bazel files in a new project, run the command below, replacing the prefix with the portion of your import path that corresponds to your repository.
gazelle -go_prefix github.com/my/project
The prefix only needs to be specified the first time you run Gazelle. To update
existing BUILD.bazel files, you can just run gazelle without arguments.
Gazelle generates build files that require a minimum version of rules_go
to build. Check the table below to ensure that you're using compatible versions.
| Gazelle version | Minimum rules_go version | Maximum rules_go version |
|---|---|---|
| 0.8 | 0.8.0 | n/a |
| 0.9 | 0.9.0 | n/a |
| 0.10.0 | 0.9.0 | 0.11.0 |
| 0.11.0 | 0.11.0 | n/a |
| 0.12.0 | 0.11.0 | n/a |
gazelle <command> [flags...] [package-dirs...]
The first argument to Gazelle may be one of the commands below. If no command
is specified, update is assumed. The remaining arguments are specific
to each command and are documented below.
- update
- Scans sources files, then generates and updates build files.
- fix
- Same as the
updatecommand, but it also fixes deprecated usage of rules. - update-repos
- Updates repository rules in the WORKSPACE file.
Gazelle may be run via a rule. See Running Gazelle with Bazel for setup
instructions. This rule builds Gazelle and generates a wrapper script that
executes Gazelle with baked-in set of arguments. You can run this script
with bazel run, or you can copy it into your workspace and run it directly.
The following attributes are available on the gazelle rule.
| Name | Type | Default value |
|---|---|---|
| gazelle | label | @bazel_gazelle//cmd/gazelle |
The go_binary rule that builds Gazelle. You can substitute a modified
version of Gazelle with this. |
||
| external | string | external |
The method for resolving unknown imports to Bazel dependencies. May be
external or vendored. |
||
| build_tags | string_list | [] |
| The last of Go build tags that Gazelle should consider to always be true. | ||
| prefix | string | mandatory value |
| The import path that corresponds to the repository root directory. TODO(#26): this should be optional. | ||
| extra_args | string_list | [] |
| A list of extra command line arguments passed to Gazelle. | ||
| command | string | update |
The Gazelle command to use. May be fix or update. To run
a different command, e.g., update-repos, you'll need to copy the
invoke the generated wrapper script directly with explicit arguments. |
||
The update command is the most common way of running Gazelle. Gazelle will
scan sources in directories throughout the repository, then create and update
build files.
The fix command does everything update does, but it also fixes
deprecated usage of rules, analogous to go fix. For example, cgo_library
will be consolidated with go_library. This command may delete or rename
rules, so it's not on by default. See Fix command transformations
for details.
Both commands accept a list of directories to process as positional arguments. If no directories are specified, Gazelle will process the current directory. Subdirectories will be processed recursively.
The following flags are accepted:
| Name | Default value |
|---|---|
-build_file_name file1,file2,... |
BUILD.bazel,BUILD |
Comma-separated list of file names. Gazelle recognizes these files as Bazel
build files. New files will use the first name in this list. Use this if
your project contains non-Bazel files named BUILD (or build on
case-insensitive file systems). |
|
-build_tags tag1,tag2 |
|
List of Go build tags Gazelle will consider to be true. Gazelle applies
constraints when generating Go rules. It assumes certain tags are true on
certain platforms (for example, Bazel may still filter sources with these tags. Use
|
|
-external external|vendored |
external |
Determines how Gazelle resolves import paths. May be external or
vendored. Gazelle translates Go import paths to Bazel labels when
resolving library dependencies. Import paths that start with the
go_prefix are resolved to local labels, but other imports
are resolved based on this mode. In external mode, paths are
resolved using an external dependency in the WORKSPACE file (Gazelle does
not create or maintain these dependencies yet). In vendored mode,
paths are resolved to a library in the vendor directory. |
|
-go_prefix example.com/repo |
|
A prefix of import paths for libraries in the repository that corresponds to
the repository root. Gazelle infers this from the This prefix is used to determine whether an import path refers to a library in the current repository or an external dependency. |
|
-known_import example.com |
|
Skips import path resolution for a known domain. May be repeated. When Gazelle resolves an import path to an external dependency, it attempts to discover the remote repository root over HTTP. Gazelle skips this discovery step for a few well-known domains with predictable structure, like golang.org and github.com. This flag specifies additional domains to skip, which is useful in situations where the lookup would fail for some reason. |
|
-mode fix|print|diff |
fix |
Method for emitting merged build files. In |
|
-proto default|legacy|disable |
default |
| Determines how Gazelle should generate rules for .proto files. See details in Directives below. | |
-repo_root dir |
|
The root directory of the repository. Gazelle normally infers this to be the directory containing the WORKSPACE file. Gazelle will not process packages outside this directory. |
|
The update-repos command updates repository rules in the WORKSPACE file.
It can be used to add new repository rules or update existing rules to the
latest version. It can also import repository rules from a dep Gopkg.lock file.
# Add or update a repository by import path
$ gazelle update-repos example.com/new/repo
# Import repositories from Gopkg.lock
$ gazelle update-repos -from_file=Gopkg.lock| Note: |
$ bazel run //:gazelle -- update-repos example.com/new/repo
|
|---|
The following flags are accepted:
| Name | Default value |
|---|---|
-from_file lock-file |
|
Import repositories from a vendoring tool's lock file as go_repository rules. These rules will be added to the bottom of WORKSPACE or merged with existing rules. The lock file format is inferred from the file's base name. Currently, only Gopkg.lock is supported. |
|
-repo_root dir |
|
The root directory of the repository. Gazelle normally infers this to be the directory containing the WORKSPACE file. Gazelle will not process packages outside this directory. |
|
When Gazelle is run by Bazel, most of the flags above can be encoded in the
gazelle rule. For example:
load("@bazel_gazelle//:def.bzl", "gazelle")
gazelle(
name = "gazelle",
command = "fix",
prefix = "github.com/example/project",
external = "vendored",
build_tags = [
"integration",
"debug",
],
extra_args = [
"-build_file_name",
"BUILD,BUILD.bazel",
],
)Gazelle can be configured with directives, which are written as top-level comments in build files. Most options that can be set on the command line can also be set using directives. Some options can only be set with directives.
Directive comments have the form # gazelle:key value. For example:
load("@io_bazel_rules_go//go:def.bzl", "go_library")
# gazelle:prefix github.com/example/project
# gazelle:build_file_name BUILD,BUILD.bazel
go_library(
name = "go_default_library",
srcs = ["example.go"],
importpath = "github.com/example/project",
visibility = ["//visibility:public"],
)Directives apply in the directory where they are set and in subdirectories.
This means, for example, if you set # gazelle:prefix in the build file
in your project's root directory, it affects your whole project. If you
set it in a subdirectory, it only affects rules in that subtree.
The following directives are recognized:
| Directive | Default value |
|---|---|
# gazelle:build_file_name names |
BUILD.bazel,BUILD |
Comma-separated list of file names. Gazelle recognizes these files as Bazel
build files. New files will use the first name in this list. Use this if
your project contains non-Bazel files named BUILD (or build on
case-insensitive file systems). |
|
# gazelle:build_tags foo,bar |
none |
List of Go build tags Gazelle will consider to be true. Gazelle applies
constraints when generating Go rules. It assumes certain tags are true on
certain platforms (for example, Bazel may still filter sources with these tags. Use
|
|
# gazelle:exclude path |
n/a |
| Prevents Gazelle from processing a file or directory. If the path refers to a source file, Gazelle won't include it in any rules. If the path refers to a directory, Gazelle won't recurse into it. The path may refer to something withinin a subdirectory, for example, a testdata directory somewhere in a vendor tree. This directive may be repeated to exclude multiple paths, one per line. | |
# gazelle:ignore |
n/a |
| Prevents Gazelle from modifying the build file. Gazelle will still read rules in the build file and may modify build files in subdirectories. | |
# gazelle:importmap_prefix path |
See below |
A prefix for
As a special case, when Gazelle enters a directory named |
|
# gazelle:prefix path |
n/a |
A prefix for As a special case, when Gazelle enters a directory named |
|
proto |
default |
Tells Gazelle how to generate rules for .proto files. Valid values are:
This directive applies to the current directory and subdirectories. As a
special case, when Gazelle enters a directory named |
|
In addition to directives, Gazelle supports # keep comments that protect
parts of build files from being modified. # keep may be written before
a rule, before an attribute, or after a string within a list.
Suppose you have a library that includes a generated .go file. Gazelle won't
know what imports to resolve, so you may need to add dependencies manually with
# keep comments.
load("@io_bazel_rules_go//go:def.bzl", "go_library")
load("@com_github_example_gen//:gen.bzl", "gen_go_file")
gen_go_file(
name = "magic",
srcs = ["magic.go.in"],
outs = ["magic.go"],
)
go_library(
name = "go_default_library",
srcs = ["magic.go"],
visibility = ["//visibility:public"],
deps = [
"@com_github_example_gen//:go_default_library", # keep
],
)Gazelle will generate and update build files when invoked with either
gazelle update or gazelle fix (update is the default). Both commands
perform several transformations to fix deprecated usage of the Go rules.
update performs a safe set of tranformations, while fix performs some
additional transformations that may delete or rename rules.
The following transformations are performed:
Migrate library to embed (fix and update): Gazelle replaces library
attributes with embed attributes.
Migrate gRPC compilers (fix and update): Gazelle converts
go_grpc_library rules to go_proto_library rules with
compilers = ["@io_bazel_rules_go//proto:go_grpc"].
Flatten srcs (fix and update): Gazelle converts srcs attributes that
use OS and architecture-specific select expressions to flat lists.
rules_go filters these sources anyway.
Squash cgo libraries (fix only): Gazelle will remove cgo_library rules
named cgo_default_library and merge their attributes with a go_library
rule in the same package named go_default_library. If no such go_library
rule exists, a new one will be created. Other cgo_library rules will not be
removed.
Squash external tests (fix only): Gazelle will squash go_test rules
named go_default_xtest into go_default_test. Earlier versions of
rules_go required internal and external tests to be built separately, but
this is no longer needed.
Remove legacy protos (fix only): Gazelle will remove usage of
go_proto_library``rules loaded from
``@io_bazel_rules_go//proto:go_proto_library.bzl and filegroup rules named
go_default_library_protos. Newly generated proto rules will take their
place. Since filegroup isn't needed anymore and go_proto_library has
different attributes and was always written by hand, Gazelle will not attempt to
merge anything from these rules with the newly generated rules.
This transformation is only applied in the default proto mode. Since Gazelle
will run in legacy proto mode if go_proto_library.bzl is loaded, this
transformation is not usually applied. You can set the proto mode explicitly
using the directive # gazelle:proto default.