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. Gazelle natively supports Go and protobuf, and it may be extended to support new languages and custom rule sets.
Gazelle may be run by Bazel using the gazelle rule, or it may be installed and run as a command line tool. Gazelle can also generate build files for external repositories 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.
Mailing list: bazel-go-discuss
Slack: #go on Bazel Slack, #bazel on Go Slack
rules_go and Gazelle are getting community maintainers! If you are a regular user of either project and are interested in helping out with development, code reviews, and issue triage, please drop by our Slack channels (linked above) and say hello!
Contents
See also:
Gazelle can generate Bazel BUILD files for many languages:
Go
Go supported is included here in bazel-gazelle, see below.
Haskell
Tweag's rules_haskell has an extension, gazelle_cabal, for generating rules from Cabal files.
Java
bazel-contrib's rules_jvm extensions include a gazelle extension for generating
java_library,java_binary,java_test, andjava_test_suiterules.JavaScript / TypeScript
BenchSci's rules_nodejs_gazelle supports generating ts_project, js_library, jest_test, and web_asset rules, and is able to support module bundlers like Webpack and Next.js
Protocol Buffers
Support for the proto_library rule, as well as go_proto_library is in this repository, see below. Other language-specific proto rules are not supported here. stackb/rules_proto is a good resource for these rules.
Python
rules_python has an extension for generating
py_library,py_binary, andpy_testrules.R
rules_r has an extension for generating rules for R package builds and tests.
Starlark
bazel-skylib has an extension for generating
bzl_libraryrules. See `bazel_skylib//gazelle/bzl`_.Swift
swift_bazel has an extension for generating
swift_library,swift_binary, andswift_testrules. It also includes facilities for resolving, downloading and building external Swift packages for a Bazel workspace.
If you know of an extension which could be linked here, please open a PR!
More languages can be added by Extending Gazelle.
Chat with us in the #gazelle channel on Bazel Slack if you'd like to discuss your design.
If you've written your own extension, please consider open-sourcing it for use by the rest of the community. Note that such extensions belong in a language-specific repository, not in bazel-gazelle. See discussion in #1030.
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",
sha256 = "56d8c5a5c91e1af73eca71a6fab2ced959b67c86d12ba37feedb0a2dfea441a6",
urls = [
"https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.37.0/rules_go-v0.37.0.zip",
"https://github.com/bazelbuild/rules_go/releases/download/v0.37.0/rules_go-v0.37.0.zip",
],
)
http_archive(
name = "bazel_gazelle",
sha256 = "ecba0f04f96b4960a5b250c8e8eeec42281035970aa8852dda73098274d14a1d",
urls = [
"https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.29.0/bazel-gazelle-v0.29.0.tar.gz",
"https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.29.0/bazel-gazelle-v0.29.0.tar.gz",
],
)
load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")
load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies", "go_repository")
############################################################
# Define your own dependencies here using go_repository.
# Else, dependencies declared by rules_go/gazelle will be used.
# The first declaration of an external repository "wins".
############################################################
go_rules_dependencies()
go_register_toolchains(version = "1.19.5")
gazelle_dependencies()gazelle_dependencies supports optional argument go_env (dict-mapping)
to set project specific go environment variables. If you are using a
WORKSPACE.bazel file, you will need to specify that using:
gazelle_dependencies(go_repository_default_config = "//:WORKSPACE.bazel")Add the code below to the BUILD or BUILD.bazel file in the root directory of your repository.
Important: For Go projects, 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 write other gazelle rules to run alternate commands like update-repos.
gazelle(
name = "gazelle-update-repos",
args = [
"-from_file=go.mod",
"-to_macro=deps.bzl%go_dependencies",
"-prune",
],
command = "update-repos",
)You can also pass additional arguments to Gazelle after a -- argument.
$ bazel run //:gazelle -- update-repos -from_file=go.mod -to_macro=deps.bzl%go_dependencies
After running update-repos, you might want to run bazel run //:gazelle again, as the
update-repos command can affect the output of a normal run of Gazelle.
If you have a Go toolchain installed, you can install Gazelle with the command below:
go install github.com/bazelbuild/bazel-gazelle/cmd/gazelle@latest
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/projectGazelle is compatible with supported releases of Go, per the Go Release Policy. The Go Team officially supports the current and previous minor releases. Older releases are not supported and don't receive bug fixes or security updates.
Gazelle may use language and library features from the oldest supported release.
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 | n/a |
| 0.9 | 0.9 | n/a |
| 0.10 | 0.9 | 0.11 |
| 0.11 | 0.11 | 0.24 |
| 0.12 | 0.11 | 0.24 |
| 0.13 | 0.13 | 0.24 |
| 0.14 | 0.13 | 0.24 |
| 0.15 | 0.13 | 0.24 |
| 0.16 | 0.13 | 0.24 |
| 0.17 | 0.13 | 0.24 |
| 0.18 | 0.19 | 0.24 |
| 0.19 | 0.19 | 0.24 |
| 0.20 | 0.20 | 0.24 |
| 0.21 | 0.20 | 0.24 |
| 0.22 | 0.20 | 0.24 |
| 0.23 | 0.26 | 0.28 |
| 0.24 | 0.29 | n/a |
| 0.25 | 0.29 | n/a |
| 0.26 | 0.29 | n/a |
| 0.27 | 0.29 | n/a |
| 0.28 | 0.35 | 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
- Adds and 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 gazelle_binary rule that builds Gazelle. You can substitute a modified version of Gazelle with this. See Extending Gazelle. | ||
| external | string | external |
The method for resolving unknown imports to Bazel dependencies. May be
external, static or vendored.
See Dependency resolution. |
||
| build_tags | string_list | [] |
| The list of Go build tags that Gazelle should consider to always be true. | ||
| prefix | string | "" |
The import path that corresponds to the repository root directory. Note: It's usually better to write a directive like
|
||
| extra_args | string_list | [] |
A list of extra command line arguments passed to Gazelle. Note that
extra_args are suppressed by extra command line args (e.g.
bazel run //:gazelle -- subdir).
See bazel-contrib#536 for explanation. |
||
| command | string | update |
The Gazelle command to use. May be fix, update or
update-repos. |
||
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 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
|
|
-exclude pattern |
|
Prevents Gazelle from processing a file or directory if the given doublestar.Match pattern matches. If the pattern refers to a source file, Gazelle won't include it in any rules. If the pattern refers to a directory, Gazelle won't recurse into it. This option may be repeated. Patterns must be slash-separated, relative to the
repository root. This is equivalent to the |
|
-external external|static|vendored |
external |
Determines how Gazelle resolves import paths that cannot be resolve in the
current repository. May be external, static or vendored. See
Dependency resolution. |
|
-index true|false |
true |
Determines whether Gazelle should index the libraries in the current repository and whether it
should use the index to resolve dependencies. If this is switched off, Gazelle would rely on
# gazelle:prefix directive or -go_prefix flag to resolve dependencies. |
|
-go_grpc_compiler |
@io_bazel_rules_go//proto:go_grpc |
The protocol buffers compiler to use for building go bindings for gRPC. May be repeated. See Predefined plugins for available options; commonly used options include
|
|
-go_naming_convention |
|
Controls the names of generated Go targets. Equivalent to the
# gazelle:go_naming_convention directive. See details in
Directives below. |
|
-go_naming_convention_external |
|
Controls the default naming convention used when resolving libraries in
external repositories with unknown naming conventions. Equivalent to the
# gazelle:go_naming_convention_external directive. |
|
-go_prefix example.com/repo |
|
A prefix of import paths for libraries in the repository that corresponds to
the repository root. Equivalent to setting the This prefix is used to determine whether an import path refers to a library in the current repository or an external dependency. |
|
-go_proto_compiler |
@io_bazel_rules_go//proto:go_proto |
The protocol buffers compiler to use for building go bindings. May be repeated. See Predefined plugins for available options; commonly used options include
|
|
-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|file|package|legacy|disable|disable_global |
default |
| Determines how Gazelle should generate rules for .proto files. See details in Directives below. | |
-proto_group group |
"" |
Determines the proto option Gazelle uses to group .proto files into rules
when in package mode. See details in Directives below. |
|
-proto_import_prefix path |
|
Sets the import_prefix attribute of generated proto_library rules.
This adds a prefix to the string used to import .proto files listed in
the srcs attribute of generated rules. Equivalent to the
# gazelle:proto_import_prefix directive. 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. |
|
-lang lang1,lang2,... |
"" |
Selects languages for which to compose and index rules. By default, all languages that this Gazelle was built with are processed. |
|
The update-repos command updates repository rules. It can write the rules
to either the WORKSPACE (by default) or a .bzl file macro function. It can be
used to add new repository rules or update existing rules to the specified
version. It can also import repository rules from a go.mod, go.work or a
Gopkg.lock file.
# Add or update a repository to latest version by import path
$ gazelle update-repos example.com/new/repo
# Add or update a repository to specified version/commit by import path
$ gazelle update-repos example.com/new/[email protected]
# Import repositories from go.mod
$ gazelle update-repos -from_file=go.mod
# Import repositories from go.work
$ gazelle update-repos -from_file=go.work
# Import repositories from go.mod and update macro
$ gazelle update-repos -from_file=go.mod -to_macro=repositories.bzl%go_repositories
# Import repositories from go.work and update macro
$ gazelle update-repos -from_file=go.work -to_macro=repositories.bzl%go_repositoriesThe following flags are accepted:
| Name | Default value |
|---|---|
-from_file lock-file |
|
Import repositories from a file as go_repository rules. These rules will be added to the bottom of the WORKSPACE file or merged with existing rules. The lock file format is inferred from the file name. |
|
-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. |
|
-to_macro macroFile%defName |
|
Tells Gazelle to write new repository rules into a .bzl macro function rather than the WORKSPACE file. The |
|
-prune true|false |
false |
When true, Gazelle will remove go_repository rules that no longer have equivalent repos in the This flag can only be used with |
|
-build_directives arg1,arg2,... |
|
Sets the build_directives attribute for the generated go_repository rule(s). |
|
-build_external external|vendored |
|
Sets the build_external attribute for the generated go_repository rule(s). |
|
-build_extra_args arg1,arg2,... |
|
Sets the build_extra_args attribute for the generated go_repository rule(s). |
|
-build_file_generation auto|on|off |
|
Sets the build_file_generation attribute for the generated go_repository rule(s). |
|
-build_file_names file1,file2,... |
|
Sets the build_file_name attribute for the generated go_repository rule(s). |
|
-build_file_proto_mode default|package|legacy|disable|disable_global |
|
Sets the build_file_proto_mode attribute for the generated go_repository rule(s). |
|
-build_tags tag1,tag2,... |
|
Sets the build_tags attribute for the generated go_repository rule(s). |
|
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:
Gazelle also reads directives from the WORKSPACE file. They may be used to
discover custom repository names and known prefixes. The fix and update
commands use these directives for dependency resolution. update-repos uses
them to learn about repository rules defined in alternate locations.
| WORKSPACE Directive | Default value |
|---|---|
# gazelle:repository_macro [+]macroFile%defName |
n/a |
Tells Gazelle to look for repository rules in a macro in a .bzl file. The directive can be
repeated multiple times.
The macro can be generated by calling The directive can be prepended with a "+", which will tell Gazelle to also look for repositories within any macros called by the specified macro. |
|
# gazelle:repository rule_kind attr1_name=attr1_value ... |
n/a |
Specifies a repository rule that Gazelle should know about. The directive can be repeated multiple times, and can be declared from within a macro definition that Gazelle knows about. At the very least the directive must define a rule kind and a name attribute, but it can define extra attributes after that. This is useful for teaching Gazelle about repos declared in external macros. The directive can also be used
to override an actual repository rule. For example, a # gazelle:repository go_repository name=org_golang_x_tools importpath=golang.org/x/toolsGazelle would then proceed as if |
|
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
],
)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:
- 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". - If a
# gazelle:resolvedirective matches the import to be resolved, the label at the end of the directive will be used. - 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_globalto a build file (this will affect subdirectories, too) or by passing-proto disable_globalon the command line.- Imports of Well Known Types are mapped to rules in
@io_bazel_rules_go//proto/wkt. - Imports of Google APIs are mapped to
@go_googleapis. - Imports of
github.com/golang/protobuf/ptypes,descriptor, andjsonpbare mapped to special rules in@com_github_golang_protobuf. See Avoiding conflicts with proto rules.
- Imports of Well Known Types are mapped to rules in
- If the import to be resolved is in the library index, the import will be resolved
to that library. If
-index=true, Gazelle builds an index of library rules in the current repository before starting dependency resolution, and this is how most dependencies are resolved.- For Go, the match is based on the
importpathattribute. - For proto, the match is based on the
srcsattribute.
- For Go, the match is based on the
- If
-index=falseand a package is imported that has the currentgo_prefixas a prefix, Gazelle generates a label following a convention. For example, if the build file in//srcset 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". - Otherwise, Gazelle will use the current
externalmode to resolve the dependency.- In
externalmode (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 ago_repositoryin WORKSPACE with a matchingimportpath, Gazelle will use its name. Gazelle does not index rules in external repositories, so it's possible the resolved dependency does not exist. - In
staticmode, Gazelle has the same behavior asexternalmode, except that it will not call out to the network for resolution when no matching import is found within WORKSPACE. Instead, it will skip the unknown import. This is the default mode forgo_repositoryrules. - In
vendoredmode, 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 4.
- In
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.