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:
http_archive(
name = "io_bazel_rules_go",
url = "https://github.com/bazelbuild/rules_go/releases/download/0.10.3/rules_go-0.10.3.tar.gz",
sha256 = "feba3278c13cde8d67e341a837f69a029f698d7a27ddbb2a202be7a10b22142a",
)
http_archive(
name = "bazel_gazelle",
url = "https://github.com/bazelbuild/bazel-gazelle/releases/download/0.10.1/bazel-gazelle-0.10.1.tar.gz",
sha256 = "d03625db67e9fb0905bbd206fa97e32ae9da894fe234a493e7517fd25faec914",
)
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 | 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
update
command, 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 version of Gazelle wit |
h this. |
You can substitute a modified |
external |
string | external |
The method for resolvi external or : |
ng unknown imports to value:vendored. | Bazel dependencies. May be |
build_tags |
string_list | [] |
The last of Go build t | ags that Gazelle shoul | d consider to always be true. |
prefix |
string | mandatory value |
The import path that c TODO(#26): this should |
|
sitory root directory. |
extra_args |
string_list | [] |
A list of extra comman | d line arguments passe | d to Gazelle. |
command |
string | update |
The Gazelle command to a different command, e invoke the generated w | .g., :value:`update-re rapper script directly |
ix` or update . To run pos`, you'll need to copy the 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. Gazell build files. New files will use the first your project contains non-Bazel files name case-insensitive file systems). | e recognizes these files as Bazel name in this list. Use this if d BUILD (or build on |
-build_tags tag1,tag2 |
|
List of Go build tags Gazelle will conside constraints when generating Go rules. It a certain platforms (for example, amd64,li tags are true (for example, go1.8). It (for example, ignore``). This flag overr |
r to be true. Gazelle applies ssumes certain tags are true on nux``). It assumes all Go release considers other tags to be false ides that behavior. |
-external external|vendored |
external |
Determines how Gazelle resolves import pat vendored . Gazelle translates Go i resolving library dependencies. Import pat go_prefix are resolved to local labels are resolved based on this mode. In :value resolved using an external dependency in t not create or maintain these dependencies paths are resolved to a library in the ven |
hs. May be external or mport paths to Bazel labels when hs that start with the , but other imports :external mode, paths are he WORKSPACE file (Gazelle does yet). In vendored mode, dor directory. |
-go_prefix example.com/repo |
|
A prefix of import paths for libraries in the repository root. Gazelle infers this f root BUILD.bazel file, if it exists. If no This prefix is used to determine whether a in the current repository or an external d |
the repository that corresponds to rom the n import path refers to a library ependency. |
-known_import example.com |
|
Skips import path resolution for a known d When Gazelle resolves an import path to an to discover the remote repository root ove discovery step for a few well-known domain golang.org and github.com. This flag speci which is useful in situations where the lo |
omain. May be repeated.
r HTTP. Gazelle skips this s with predictable structure, like fies additional domains to skip, okup would fail for some reason. |
-mode fix|print|diff |
fix |
Method for emitting merged build files. In |
and merged files to disk. In In diff mode, it prints a |
-proto default|legacy|disable |
default |
Determines how Gazelle should generate rul in Directives below. | es for .proto files. See details |
-repo_root dir |
|
The root directory of the repository. Gaze directory containing the WORKSPACE file. Gazelle will not process packages outside |
lle normally infers this to be the 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.
- Note
update-repos
is not directly supported by thegazelle
rule. You can run it through thegazelle
rule by passing extra arguments after--
. For example:$ 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 ven rules. These rules will be add existing rules. The lock file format is inferr Gopkg.lock is supported. |
doring tool's lock file as go_repository ed to the bottom of WORKSPACE or merged with ed from the file's base name. Currently, only |
-repo_root dir |
|
The root directory of the repo directory containing the WORKS Gazelle will not process packa |
sitory. Gazelle normally infers this to be the PACE file. ges 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 supports several directives, written as top-level comments in build files. These are of the form # gazelle:key value
. Most directories apply in both the current directory and in subdirectories.
# gazelle:build_file_name BUILD.bazel,BUILD
: a comma-separated list of file names that Gazelle will recognize as Bazel build files. When Gazelle creates a new file, it will use the first name in this list.# gazelle:build_tags foo,bar,baz
: a comma-separated list of build tags that Gazelle will consider as always true.# gazelle:exclude path
: 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 in 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
: prevents Gazelle from updating the build file. Gazelle will still read rules in the build file and may modify build files in subdirectories. Use# gazelle:exclude
to ignore a subdirectory.# gazelle:importmap_prefix path
: a prefix forimportmap
attributes on library rules. The fullimportmap
for a package is determined by concatenating this prefix with the relative path from the directory where the prefix is set to the package directory. This is set automatically in vendor directories.# gazelle:prefix example.com/repo
: a prefix forimportpath
attributes on library rules. The fullimportpath
for a package is determined by concatenating this prefix with the relative path from the directory where the prefix is set to the package directory. This may also be set with the-go_prefix
parameter.# gazelle:proto <mode>
: Tells Gazelle how to generate rules for .proto files. Applies to the current directory and subdirectories. Valid values formode
are:default
:proto_library
,go_proto_library
,go_grpc_library
, andgo_library
rules are generated using@io_bazel_rules_go//proto:def.bzl
. This is the default mode.legacy
:filegroup
rules are generated for use by@io_bazel_rules_go//proto:go_proto_library.bzl
.go_proto_library
rules must be written by hand. Gazelle will run in this mode automatically ifgo_proto_library.bzl
is loaded to avoid disrupting existing projects, but this can be overridden with a directive.disable
: .proto files are ignored. Gazelle will run in this mode automatically ifgo_proto_library
is loaded from any other source, but this can be overridden with a directive.
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
],
)
When Gazelle is invoked with the fix
command, in addition to updating source files and dependencies of existing rules, Gazelle will remove deprecated usage of the Go rules, analogous to go fix
. The following transformations are performed.
Squash cgo libraries: 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.
cgo_library(
name = "cgo_default_library",
srcs = ["cgo.go"],
)
# AFTER
go_library(
name = "go_default_library",
srcs = [
"cgo.go",
"pure.go",
],
cgo = True,
)
Remove legacy protos: 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
.
go_proto_library(
name = "go_default_library",
srcs = [":go_default_library_protos"],
)
filegroup(
name = "go_default_library_protos",
srcs = ["foo.proto"],
)
# AFTER
# The above rules are deleted. New proto_library, go_proto_library, and
# go_library rules will be generated automatically.