Gazelle build file generator

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 sources, dependencies, and options. Gazelle may be run by Bazel using the gazelle rule, or it can be run as a command line tool. Gazelle can also be run in an external repository 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:

• Architecture of Gazelle
• Repository rules
  • go_repository
  • git_repository
  • http_archive
• Avoiding conflicts with proto rules

Setup

Running Gazelle with Bazel

To use Gazelle in a new project, add the bazel_gazelle repository and its dependencies to your WORKSPACE file and call gazelle_dependencies. 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.15.3/rules_go-0.15.3.tar.gz"],
    sha256 = "97cf62bdef33519412167fd1e4b0810a318a7c234f5f8dc4f53e2da86241c492",
)
http_archive(
    name = "bazel_gazelle",
    urls = ["https://github.com/bazelbuild/bazel-gazelle/releases/download/0.14.0/bazel-gazelle-0.14.0.tar.gz"],
    sha256 = "c0a5739d12c6d05b6c1ad56f2200cb0b57c5a70e03ebd2f7b87ce88cabf09c7b",
)
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 after prefix with the portion of your import path that corresponds to your repository.

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

# gazelle:prefix github.com/example/project
gazelle(name = "gazelle")

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 cannot run directly.

$ bazel run //:gazelle -- update-repos -from_file=Gopkg.lock

Running Gazelle with Go

If you have a Go SDK installed, you can install Gazelle 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/example/project

Most of Gazelle's command-line arguments can be expressed as special comments in build files. See Directives below. You may want to copy this line into your root build files to avoid having to type -go_prefix every time.

# gazelle:prefix github.com/example/project

Compatibility

Gazelle generates build files that use features in newer versions of rules_go. Newer versions of Gazelle may generate build files that work with older versions of rules_go, but check the table below to ensure you're using a compatible version.

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
0.13.0	0.13.0	n/a
0.14.0	0.13.0	n/a

Usage

Command line

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

Adds and updates repository rules in the WORKSPACE file.

Bazel rule

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	that builds Gazelle. h this.	You can substitute a modified
external	string	external
The method for resolvi external or :	ng unknown imports to value:vendored. See	Bazel dependencies. May be Dependency resolution.
build_tags	string_list	[]
The last of Go build t	ags that Gazelle shoul	d consider to always be true.
prefix	string	""
The import path that c Note: It's usually bet ``# gazelle:prefix exa this attribute.	orresponds to the repo ter to write a directi mple.com/repo`` in you	sitory root directory. ve like r build file instead of setting
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	use. May be :value:`f .g., :value:`update-re rapper script directly	ix` or update. To run pos`, you'll need to copy the with explicit arguments.

fix and update

The update command is the most common way of running Gazelle. Gazelle scans sources in directories throughout the repository, then creates and updates 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 f build files. New files will use the first name in this list. U your project contains non-Bazel files named BUILD (or ``bu case-insensitive file systems).	iles as Bazel se this if ild`` on
-build_tags tag1,tag2
List of Go build tags Gazelle will consider to be true. Gazell constraints when generating Go rules. It assumes certain tags certain platforms (for example, amd64,linux). It assumes a tags are true (for example, go1.8). It considers other tag (for example, ignore). This flag overrides that behavior. Bazel may still filter sources with these tags. Use bazel build --features gotags=foo,bar to set tags at build	e applies are true on ll Go release s to be false time.
-external external|vendored	external
Determines how Gazelle resolves import paths that cannot be re current repository. May be external or vendor `Dependency resolution_.	solve in the ed`. See
-go_prefix example.com/repo
A prefix of import paths for libraries in the repository that the repository root. Gazelle infers this from the `go_prefix root BUILD.bazel file, if it exists. If not, this option is ma This prefix is used to determine whether an import path refers in the current repository or an external dependency.	corresponds to ` rule in the ndatory. to a library
-known_import example.com
Skips import path resolution for a known domain. May be repeat When Gazelle resolves an import path to an external dependency to discover the remote repository root over HTTP. Gazelle skip discovery step for a few well-known domains with predictable s golang.org and github.com. This flag specifies additional doma which is useful in situations where the lookup would fail for	ed. , it attempts s this tructure, like ins to skip, some reason.
-mode fix|print|diff	fix
Method for emitting merged build files. In fix mode, Gazelle writes generated and merged files to print mode, it prints them to stdout. In diff mode, it unified diff.	disk. In prints a
-proto default|package|legacy|disable|disable_global	default
Determines how Gazelle should generate rules for .proto files. in Directives below.	See details
-proto_group group	""
Determines the proto option Gazelle uses to group .proto files when in package mode. See details in Directives below.	into rules
-repo_root dir
The root directory of the repository. Gazelle normally infers directory containing the WORKSPACE file. Gazelle will not process packages outside this directory.	this to be the

update-repos

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

update-repos is not directly supported by the gazelle rule. You can run it through the gazelle 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.

Directives

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. 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
# gazelle:build_tags foo,bar	none
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 Bazel may still filter sources with thesebazel build --features gotags=foo,bar``	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. tags. Use to set tags at build time.
# gazelle:exclude path	n/a
Prevents Gazelle from processing a file or a source file, Gazelle won't include it in a directory, Gazelle won't recurse into it withinin a subdirectory, for example, a te vendor tree. This directive may be repeate per line.	directory. If the path refers to any rules. If the path refers to . The path may refer to something stdata directory somewhere in a d to exclude multiple paths, one
# gazelle:ignore	n/a
Prevents Gazelle from modifying the build rules in the build file and may modify bui	file. Gazelle will still read ld files in subdirectories.
# gazelle:importmap_prefix path	See below
A prefix for importmap attributes in l an importmap on a go_library or concatenating this with the relative path prefix is set to the library. For example, to"x/example.com/repo"in the build f then a library infoo/bar/bazwill hav"x/example.com/repo/baz".importmapis not set when it matches ` As a special case, when Gazelle enters a d setsimportmap_prefixto a string base location of the vendor directory. If you w to setimportmap_prefix`` explicitly in	ibrary rules. Gazelle will set go_proto_libraryby from the directory where the ifimportmap_prefixis set ile//foo/bar:BUILD.bazel, e theimportmapof `importpath. irectory named vendor, it d on the repository name and the ish to override this, you'll need the vendor directory.
# gazelle:prefix path	n/a
A prefix for importpath attributes on an importpath on a go_library or concatenating this with the relative path prefix is set to the library. Most commonl name of a repository in the root directory in this repository, prefix is set in github.com/bazelbuild/bazel-gazelle. T //cmd/gazelle is assigned the import"github.com/bazelbuild/bazel-gazelle/cmd As a special case, when Gazelle enters a d prefix to the empty string. This autom an intuitive importpath.	library rules. Gazelle will set go_proto_library by from the directory where the y, prefix is set to the of a repository. For example, //:BUILD.bazelto hego_libraryin path /gazelle". irectory namedvendor``, it sets atically gives vendored libraries
# gazelle:proto mode	default
Tells Gazelle how to generate rules for .p default: proto_library, go_pro rules are generated using@io_bazel_ru of each rule may be generated per direct package: multiple proto_library may be generated in the same directory. rules based on their package name or ano legacy: filegroup rules are gene @io_bazel_rules_go//proto:go_proto_lib rules must be written by hand. Gazelle w ifgo_proto_library.bzl`` is loaded to projects, but this can be overridden wit disable: .proto files are ignored. G automatically if go_proto_library is but this can be overridden with a direct disable_global: like disable mod using any special cases in dependency re Google APIs. Useful for avoiding build-t This directive applies to the current dire special case, when Gazelle enters a direct mode isn't set explicitly in a parent dire Gazelle will run in disable mode. Addi @io_bazel_rules_go//proto:go_proto_libra will run inlegacy`` mode.	roto files. Valid values are: to_library, andgo_libraryles_go//proto:def.bzl. Only one ory. This is the default mode. and go_proto_library rules .proto files are grouped into ther option (see proto_group). rated for use by rary.bzl.go_proto_libraryill run in this mode automatically avoid disrupting existing h a directive. azelle will run in this mode loaded from any other source, ive. e, but also prevents Gazelle from solution for Well Known Types and ime dependencies on protoc. ctory and subdirectories. As a ory namedvendor, if the proto ctory or on the command line, tionally, if the file ry.bzl is loaded, Gazelle
# gazelle:proto_group option	""
This directive is only effective in pa Specifies an option that Gazelle can use t For example, when set togo_package, .option go_packagewill be grouped toge When this directive is set to the empty st by their proto package statement. Rule names are generated based on the last in the package name. For example, if the pproto_libraryrule will be namedbaz	ckage*mode (see above).* o group .proto files into rules. proto files with the same ther. ring, Gazelle will group packages run of identifier characters ackage is"foo/bar/baz", the _proto.

Keep comments

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.

Example

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
    ],
)

Dependency resolution

One of Gazelle's most important jobs is resolving library import strings (like import "golang.org/x/sys/unix") to Bazel labels (like @org_golang_x_sys//unix:go_default_library). Gazelle follows the rules below to resolve dependencies:

1. If the import to be resolved is part of a standard library, no explicit dependency is written. For example, in Go, you don't need to declare that you depend on "fmt".
2. If proto rule generation is enabled, special rules will be used when importing certain libraries. These rules may be disabled by adding # gazelle:proto disable_global to a build file (this will affect subdirectories, too) or by passing -proto disable_global on the command line.
   1. Imports of Well Known Types are mapped to rules in @io_bazel_rules_go//proto/wkt.
   2. Imports of Google APIs are mapped to @go_googleapis.
   3. Imports of github.com/golang/protobuf/ptypes, descriptor, and jsonpb are mapped to special rules in @com_github_golang_protobuf. See Avoiding conflicts with proto rules.
3. If the import to be resolved is provided by a library in the current repository, the import will be resolved to that library. Gazelle builds an index of library rules in the current repository before starting dependency resolution, and this is how most dependencies are resolved.
   1. For Go, the match is based on the importpath attribute.
   2. For proto, the match is based on the srcs attribute.
4. If a package is imported that has the current go_prefix as a prefix, Gazelle generates a label following a convention. For example, if the build file in //src set the prefix with # gazelle:prefix example.com/repo/foo, and you import the library "example.com/repo/foo/bar, the dependency will be "//src/foo/bar:go_default_library".
5. Otherwise, Gazelle will use the current external mode to resolve the dependency.
   1. In external mode (the default), Gazelle will transform the import string into an external repository label. For example, "golang.org/x/sys/unix" would be resolved to "@org_golang_x_sys//unix:go_default_library". Gazelle does not confirm whether the external repository is actually declared in WORKSPACE, but if there is a go_repository in WORKSPACE with a matching importpath, Gazelle will use its name. Gazelle does not index rules in external repositories, so it's possible the resolved dependency does not exist.
   2. In vendored mode, Gazelle will transform the import string into a label in the vendor directory. For example, "golang.org/x/sys/unix" would be resolved to "//vendor/golang.org/x/sys/unix:go_default_library". This mode is usually not necessary, since vendored libraries will be indexed and resolved using rule 3.

Fix command transformations

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.

Update loads of gazelle rule (fix and update): Gazelle will remove loads of gazelle from @io_bazel_rules_go//go:def.bzl. It will automatically add a load from @bazel_gazelle//:def.bzl if gazelle is not loaded from another location.