Go rules for Bazel
Mailing list: bazel-go-discuss
Slack: #go on Bazel Slack, #bazel on Go Slack
- 2021-07-07
- Release v0.28.0 is now available. This adds experimental editor support, plus a few other changes. See the release notes for details. Thanks to all who contributed!
- 2021-03-18
- Release
v0.27.0
is now available. This updates
org_golang_x_toolsand addsorg_golang_x_sys. This should have been done inv0.26.0. Additionally, v0.24.14 is now available with support for Go 1.16.2, 1.16.1, 1.15.10, and 1.15.9. This will be the last release on the 0.24 branch. 0.27 and 0.25 are now the two supported branches. - 2021-03-08
- Release
v0.26.0
is now available. This provides support for the new
//go:embedattribute, plus several other improvements. Gazelle v0.23.0 is also available with support forembedsrcsattributes (needed for//go:embed) and a few other improvements.
- Core rules
- Proto rules
- Dependencies
- go_rules_dependencies
- go_repository (Gazelle)
- Toolchains
- Extra rules
- nogo build-time static analysis
- Build modes
The rules are in the beta stage of development. They support:
- Building libraries, binaries, and tests (go_library, go_binary, go_test)
- Vendoring
- cgo
- Cross-compilation
- Generating BUILD files via gazelle
- Build-time code analysis via nogo
- Protocol buffers
- Remote execution
They currently do not support or have limited support for:
- Editor and tool integration
- Coverage
- Debugging
- C/C++ integration other than cgo (SWIG)
The Go rules are tested and supported on the following host platforms:
- Linux, macOS, Windows
- amd64
Users have reported success on several other platforms, but the rules are only tested on those listed above.
Note: The latest version of these rules (v0.28.0) requires Bazel ≥ 4.0.0 to work.
The master branch is only guaranteed to work with the latest version of Bazel.
To build Go code with Bazel, you will need:
- A recent version of Bazel.
- A C/C++ toolchain (if using cgo). Bazel will attempt to configure the toolchain automatically.
- Bash,
patch,cat, and a handful of other Unix tools inPATH.
You normally won't need a Go toolchain installed. Bazel will download one.
See Using rules_go on Windows for Windows-specific setup instructions. Several additional tools need to be installed and configured.
Create a file at the top of your repository named WORKSPACE, and add the
snippet below (or add to your existing WORKSPACE). This tells Bazel to
fetch rules_go and its dependencies. Bazel will download a recent supported
Go toolchain and register it for use.
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
name = "io_bazel_rules_go",
sha256 = "8e968b5fcea1d2d64071872b12737bbb5514524ee5f0a4f54f5920266c261acb",
urls = [
"https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.28.0/rules_go-v0.28.0.zip",
"https://github.com/bazelbuild/rules_go/releases/download/v0.28.0/rules_go-v0.28.0.zip",
],
)
load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")
go_rules_dependencies()
go_register_toolchains(version = "1.17")You can use rules_go at master by using git_repository instead of
http_archive and pointing to a recent commit.
Add a file named BUILD.bazel in the root directory of your project.
You'll need a build file in each directory with Go code, but you'll also need
one in the root directory, even if your project doesn't have Go code there.
For a "Hello, world" binary, the file should look like this:
load("@io_bazel_rules_go//go:def.bzl", "go_binary")
go_binary(
name = "hello",
srcs = ["hello.go"],
)You can build this target with bazel build //:hello.
If your project can be built with go build, you can generate and update your
build files automatically using gazelle.
Add the bazel_gazelle repository and its dependencies to your
WORKSPACE. It should look like this:
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") http_archive( name = "io_bazel_rules_go", sha256 = "8e968b5fcea1d2d64071872b12737bbb5514524ee5f0a4f54f5920266c261acb", urls = [ "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.28.0/rules_go-v0.28.0.zip", "https://github.com/bazelbuild/rules_go/releases/download/v0.28.0/rules_go-v0.28.0.zip", ], ) http_archive( name = "bazel_gazelle", sha256 = "62ca106be173579c0a167deb23358fdfe71ffa1e4cfdddf5582af26520f1c66f", urls = [ "https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.23.0/bazel-gazelle-v0.23.0.tar.gz", "https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.23.0/bazel-gazelle-v0.23.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_rules_dependencies() go_register_toolchains(version = "1.17") gazelle_dependencies()
Add the code below to the BUILD.bazel file in your project's root directory.
Replace the string after prefix with an import path prefix that matches your
project. It should be the same as your module path, if you have a go.mod
file.
load("@bazel_gazelle//:def.bzl", "gazelle")
# gazelle:prefix github.com/example/project
gazelle(name = "gazelle")This declares a gazelle binary rule, which you can run using the command
below:
bazel run //:gazelleThis will generate a BUILD.bazel file with go_library, go_binary, and
go_test targets for each package in your project. You can run the same
command in the future to update existing build files with new source files,
dependencies, and options.
If your project doesn't follow go build conventions or you prefer not to use
gazelle, you can write build files by hand.
In each directory that contains Go code, create a file named BUILD.bazel
Add a load statement at the top of the file for the rules you use.
load("@io_bazel_rules_go//go:def.bzl", "go_binary", "go_library", "go_test")For each library, add a go_library rule like the one below. Source files are
listed in the srcs attribute. Imported packages outside the standard library
are listed in the deps attribute using Bazel labels that refer to
corresponding go_library rules. The library's import path must be specified
with the importpath attribute.
go_library(
name = "foo_library",
srcs = [
"a.go",
"b.go",
],
importpath = "github.com/example/project/foo",
deps = [
"//tools",
"@org_golang_x_utils//stuff",
],
visibility = ["//visibility:public"],
)For tests, add a go_test rule like the one below. The library being tested
should be listed in an embed attribute.
go_test(
name = "foo_test",
srcs = [
"a_test.go",
"b_test.go",
],
embed = [":foo_lib"],
deps = [
"//testtools",
"@org_golang_x_utils//morestuff",
],
)For binaries, add a go_binary rule like the one below.
go_binary(
name = "foo",
srcs = ["main.go"],
)For each Go repository, add a go_repository rule to WORKSPACE like the
one below. This rule comes from the Gazelle repository, so you will need to
load it. gazelle update-repos can generate or update these rules
automatically from a go.mod or Gopkg.lock file.
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
# Download the Go rules.
http_archive(
name = "io_bazel_rules_go",
sha256 = "69de5c704a05ff37862f7e0f5534d4f479418afc21806c887db544a316f3cb6b",
urls = [
"https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.27.0/rules_go-v0.27.0.tar.gz",
"https://github.com/bazelbuild/rules_go/releases/download/v0.27.0/rules_go-v0.27.0.tar.gz",
],
)
# Download Gazelle.
http_archive(
name = "bazel_gazelle",
sha256 = "62ca106be173579c0a167deb23358fdfe71ffa1e4cfdddf5582af26520f1c66f",
urls = [
"https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.23.0/bazel-gazelle-v0.23.0.tar.gz",
"https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.23.0/bazel-gazelle-v0.23.0.tar.gz",
],
)
# Load macros and repository rules.
load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")
load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies", "go_repository")
# Declare Go direct dependencies.
go_repository(
name = "org_golang_x_net",
importpath = "golang.org/x/net",
sum = "h1:zK/HqS5bZxDptfPJNq8v7vJfXtkU7r9TLIoSr1bXaP4=",
version = "v0.0.0-20200813134508-3edf25e44fcc",
)
# Declare indirect dependencies and register toolchains.
go_rules_dependencies()
go_register_toolchains(version = "1.17")
gazelle_dependencies()To generate code from protocol buffers, you'll need to add a dependency on
com_google_protobuf to your WORKSPACE.
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
name = "com_google_protobuf",
sha256 = "d0f5f605d0d656007ce6c8b5a82df3037e1d8fe8b121ed42e536f569dec16113",
strip_prefix = "protobuf-3.14.0",
urls = [
"https://mirror.bazel.build/github.com/protocolbuffers/protobuf/archive/v3.14.0.tar.gz",
"https://github.com/protocolbuffers/protobuf/archive/v3.14.0.tar.gz",
],
)
load("@com_google_protobuf//:protobuf_deps.bzl", "protobuf_deps")
protobuf_deps()You'll need a C/C++ toolchain registered for the execution platform (the platform where Bazel runs actions) to build protoc.
The proto_library rule is provided by the rules_proto repository.
protoc-gen-go, the Go proto compiler plugin, is provided by the
com_github_golang_protobuf repository. Both are declared by
go_rules_dependencies. You won't need to declare an explicit dependency
unless you specifically want to use a different version. See Overriding
dependencies for instructions on using a different version.
gRPC dependencies are not declared by default (there are too many). You can
declare them in WORKSPACE using go_repository. You may want to use
gazelle update-repos to import them from go.mod.
See Proto dependencies, gRPC dependencies for more information. See also Avoiding conflicts.
Once all dependencies have been registered, you can declare proto_library and go_proto_library rules to generate and compile Go code from .proto files.
load("@rules_proto//proto:defs.bzl", "proto_library")
load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library")
proto_library(
name = "foo_proto",
srcs = ["foo.proto"],
deps = ["//bar:bar_proto"],
visibility = ["//visibility:public"],
)
go_proto_library(
name = "foo_go_proto",
importpath = "github.com/example/protos/foo_proto",
protos = [":foo_proto"],
visibility = ["//visibility:public"],
)A go_proto_library target may be imported and depended on like a normal
go_library.
Note that recent versions of rules_go support both APIv1
(github.com/golang/protobuf) and APIv2 (google.golang.org/protobuf).
By default, code is generated with
github.com/golang/protobuf/cmd/protoc-gen-gen for compatibility with both
interfaces. Client code may import use either runtime library or both.
Go
- Can I still use the go command?
- Does this work with Go modules?
- What's up with the go_default_library name?
- How do I cross-compile?
- How do I access testdata?
- How do I access go_binary executables from go_test?
Protocol buffers
Dependencies and testing
- How do I use different versions of dependencies?
- How do I run Bazel on Travis CI?
- How do I test a beta version of the Go SDK?
Yes, but not directly.
rules_go invokes the Go compiler and linker directly, based on the targets
described with go_binary and other rules. Bazel and rules_go together
fill the same role as the go command, so it's not necessary to use the
go command in a Bazel workspace.
That said, it's usually still a good idea to follow conventions required by
the go command (e.g., one package per directory, package paths match
directory paths). Tools that aren't compatible with Bazel will still work,
and your project can be depended on by non-Bazel projects.
Yes, but not directly. Bazel ignores go.mod files, and all package
dependencies must be expressed through deps attributes in targets
described with go_library and other rules.
You can download a Go module at a specific version as an external repository using go_repository, a workspace rule provided by gazelle. This will also generate build files using gazelle.
You can import go_repository rules from a go.mod file using
gazelle update-repos.
This was used to keep import paths consistent in libraries that can be built
with go build before the importpath attribute was available.
In order to compile and link correctly, rules_go must know the Go import path
(the string by which a package can be imported) for each library. This is now
set explicitly with the importpath attribute. Before that attribute existed,
the import path was inferred by concatenating a string from a special
go_prefix rule and the library's package and label name. For example, if
go_prefix was github.com/example/project, for a library
//foo/bar:bar, rules_go would infer the import path as
github.com/example/project/foo/bar/bar. The stutter at the end is
incompatible with go build, so if the label name was go_default_library,
the import path would not include it. So for the library
//foo/bar:go_default_library, the import path would be
github.com/example/project/foo/bar.
Since go_prefix was removed and the importpath attribute became
mandatory (see #721), the go_default_library name no longer serves any
purpose. We may decide to stop using it in the future (see #265).
You can cross-compile by setting the --platforms flag on the command line.
For example:
$ bazel build --platforms=@io_bazel_rules_go//go/toolchain:linux_amd64 //cmd
By default, cgo is disabled when cross-compiling. To cross-compile with cgo,
add a _cgo suffix to the target platform. You must register a
cross-compiling C/C++ toolchain with Bazel for this to work.
$ bazel build --platforms=@io_bazel_rules_go//go/toolchain:linux_amd64_cgo //cmd
Platform-specific sources with build tags or filename suffixes are filtered
automatically at compile time. You can selectively include platform-specific
dependencies with select expressions (Gazelle does this automatically).
go_library(
name = "foo",
srcs = [
"foo_linux.go",
"foo_windows.go",
],
deps = select({
"@io_bazel_rules_go//go/platform:linux_amd64": [
"//bar_linux",
],
"@io_bazel_rules_go//go/platform:windows_amd64": [
"//bar_windows",
],
"//conditions:default": [],
}),
)To build a specific go_binary or go_test target for a target platform,
set the goos and goarch attributes on that rule. This is useful for
producing multiple binaries for different platforms in a single build.
You can equivalently depend on a go_binary or go_test rule through
a Bazel configuration transition on //command_line_option:platforms
(there are problems with this approach prior to rules_go 0.23.0).
Bazel executes tests in a sandbox, which means tests don't automatically have
access to files. You must include test files using the data attribute.
For example, if you want to include everything in the testdata directory:
go_test(
name = "foo_test",
srcs = ["foo_test.go"],
data = glob(["testdata/**"]),
importpath = "github.com/example/project/foo",
)By default, tests are run in the directory of the build file that defined them.
Note that this follows the Go testing convention, not the Bazel convention
followed by other languages, which run in the repository root. This means
that you can access test files using relative paths. You can change the test
directory using the rundir attribute. See go_test.
Gazelle will automatically add a data attribute like the one above if you
have a testdata directory unless it contains buildable .go files or
build files, in which case, testdata is treated as a normal package.
Note that on Windows, data files are not directly available to tests, since test data files rely on symbolic links, and by default, Windows doesn't let unprivileged users create symbolic links. You can use the github.com/bazelbuild/rules_go/go/tools/bazel library to access data files.
The location where go_binary writes its executable file is not stable across
rules_go versions and should not be depended upon. The parent directory includes
some configuration data in its name. This prevents Bazel's cache from being
poisoned when the same binary is built in different configurations. The binary
basename may also be platform-dependent: on Windows, we add an .exe extension.
To depend on an executable in a go_test rule, reference the executable
in the data attribute (to make it visible), then expand the location
in args. The real location will be passed to the test on the command line.
For example:
go_binary(
name = "cmd",
srcs = ["cmd.go"],
)
go_test(
name = "cmd_test",
srcs = ["cmd_test.go"],
args = ["$(location :cmd)"],
data = [":cmd"],
)See //tests/core/cross for a full example of a test that accesses a binary.
Alternatively, you can set the out attribute of go_binary to a specific
filename. Note that when out is set, the binary won't be cached when
changing configurations.
go_binary(
name = "cmd",
srcs = ["cmd.go"],
out = "cmd",
)
go_test(
name = "cmd_test",
srcs = ["cmd_test.go"],
data = [":cmd"],
)See Avoiding conflicts in the proto documentation.
This is not supported. When using go_proto_library with the
@io_bazel_rules_go//proto:go_grpc compiler, an implicit dependency is added
on @org_golang_google_grpc//:go_default_library. If you link another copy of
the same package from //vendor/google.golang.org/grpc:go_default_library
or anywhere else, you may experience conflicts at compile or run-time.
If you're using Gazelle with proto rule generation enabled, imports of
google.golang.org/grpc will be automatically resolved to
@org_golang_google_grpc//:go_default_library to avoid conflicts. The
vendored gRPC should be ignored in this case.
If you specifically need to use a vendored gRPC package, it's best to avoid
using go_proto_library altogether. You can check in pre-generated .pb.go
files and build them with go_library rules. Gazelle will generate these
rules when proto rule generation is disabled (add # gazelle:proto
disable_global to your root build file).
See Overriding dependencies for instructions on overriding repositories declared in go_rules_dependencies.
References:
In order to run Bazel tests on Travis CI, you'll need to install Bazel in the
before_install script. See our configuration file linked above.
You'll want to run Bazel with a number of flags to prevent it from consuming a huge amount of memory in the test environment.
--host_jvm_args=-Xmx500m --host_jvm_args=-Xms500m: Set the maximum and initial JVM heap size. Keeping the same means the JVM won't spend time growing the heap. The choice of heap size is somewhat arbitrary; other configuration files recommend limits as high as 2500m. Higher values mean a faster build, but higher risk of OOM kill.--bazelrc=.test-bazelrc: Use a Bazel configuration file specific to Travis CI. You can put most of the remaining options in here.build --spawn_strategy=standalone --genrule_strategy=standalone: Disable sandboxing for the build. Sandboxing may fail inside of Travis's containers because themountsystem call is not permitted.test --test_strategy=standalone: Disable sandboxing for tests as well.--local_resources=1536,1.5,0.5: Set Bazel limits on available RAM in MB, available cores for compute, and available cores for I/O. Higher values mean a faster build, but higher contention and risk of OOM kill.--noshow_progress: Suppress progress messages in output for cleaner logs.--verbose_failures: Get more detailed failure messages.--test_output=errors: Show test stderr in the Travis log. Normally, test output is written log files which Travis does not save or report.
Downloads on Travis are relatively slow (the network is heavily
contended), so you'll want to minimize the amount of network I/O in
your build. Downloading Bazel and a Go SDK is a huge part of that. To
avoid downloading a Go SDK, you may request a container with a
preinstalled version of Go in your .travis.yml file, then call
go_register_toolchains(go_version = "host") in a Travis-specific
WORKSPACE file.
You may be tempted to put Bazel's cache in your Travis cache. Although this can speed up your build significantly, Travis stores its cache on Amazon, and it takes a very long time to transfer. Clean builds seem faster in practice.
rules_go only supports official releases of the Go SDK. However, you can still
test beta and RC versions by passing a version like "1.16beta1" to
go_register_toolchains. See also go_download_sdk.
load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")
go_rules_dependencies()
go_register_toolchains(version = "1.17beta1")