Go rules for Bazel

Bazel 0.5.2	Bazel HEAD

Announcements

August 28, 2017 Release 0.5.4 is now available! This will be the last stable tag before requiring Bazel 0.5.4 and toolchains support.
August 9, 2017 Release 0.5.3 is now available!
July 27, 2017 Bazel 0.5.3 is now available. This includes a change which is incompatible with rules_go 0.5.1 and earlier. rules_go 0.5.2 should work.
July 17, 2017 Release 0.5.2 is now available! This fixes an issue with Bazel at HEAD. Note that Bazel 0.5.2 is now required.
July 12, 2017 The rules now require Bazel 0.5.2 or newer at HEAD. The latest tagged version, 0.5.1, still works with Bazel 0.4.5 though.

Overview
Setup
Generating build files
Build modes
FAQ
Repository rules
Build rules

Overview

The rules are in the alpha stage of development. They support:

libraries
binaries
tests
vendoring
cgo
auto generating BUILD files via gazelle
protocol buffers (via extension //proto:go_proto_library.bzl)

They currently do not support (in order of importance):

cross compilation
bazel-style auto generating BUILD (where the library name is other than go_default_library)
C/C++ interoperation except cgo (swig etc.)
coverage
test sharding

Note: The latest version of these rules (0.5.4) require Bazel ≥ 0.5.2 to work.

The master branch is only guaranteed to work with the latest version of Bazel.

Setup

Decide on the name of your package, eg. github.com/joe/project. It's important to choose a name that will match where others will download your code. This will be a prefix for import paths within your project.

Create a file at the top of your repository named WORKSPACE, and add the following code, verbatim. This will let Bazel fetch necessary dependencies from this repository and a few others. You can add more external dependencies to this file later (see go_repository below).

git_repository(
    name = "io_bazel_rules_go",
    remote = "https://github.com/bazelbuild/rules_go.git",
    tag = "0.5.4",
)
load("@io_bazel_rules_go//go:def.bzl", "go_rules_dependencies", "go_register_toolchains")

go_rules_dependencies()
go_register_toolchains()

Add a BUILD file to the top of your project. Declare the name of your workspace using go_prefix. This is used by Bazel to translate between build targets and import paths. Also add the gazelle rule.
```
load("@io_bazel_rules_go//go:def.bzl", "go_prefix", "gazelle")

go_prefix("github.com/joe/project")
gazelle(name = "gazelle")
```
If your project can be built with go build, you can generate your BUILD files using Gazelle. If not, or if you just want to understand the things gazelle is going to generate for you, read on.
For a library github.com/joe/project/lib, create lib/BUILD, containing a single library with the special name "go_default_library." Using this name tells Bazel to set up the files so it can be imported in .go files as (in this example) github.com/joe/project/lib. See the FAQ below for more information on this name.
```
load("@io_bazel_rules_go//go:def.bzl", "go_library")

go_library(
    name = "go_default_library",
    srcs = ["file.go"]
)
```
Inside your project, you can use this library by declaring a dependency on the full Bazel name (including :go_default_library), and in the .go files, import it as shown above.
```
go_binary(
    ...
    deps = ["//lib:go_default_library"]
)
```

To declare a test,

go_test(
    name = "mytest",
    srcs = ["file_test.go"],
    library = ":go_default_library"
)

For instructions on how to depend on external libraries, see Vendoring.md.

Generating build files

If your project can be built with go build, you can generate and update your BUILD files automatically using Gazelle, a tool included in this repository. See the Gazelle README for more information.

The gazelle rule in your root BUILD file gives you the ability to build and run gazelle on your project using Bazel. This is the preferred way to run Gazelle.

bazel run //:gazelle

By default, Gazelle assumes external dependencies are present in your WORKSPACE file, following a certain naming convention. For example, it expects the repository for github.com/jane/utils to be named @com_github_jane_utils. If you prefer to use vendoring, add external=vendored to the gazelle rule. See Vendoring.md.

Build modes

Building static binaries

You can build binaries in static linking mode using

bazel build --output_groups=static //:my_binary

You can depend on static binaries (e.g., for packaging) using filegroup:

go_binary(
    name = "foo",
    srcs = ["foo.go"],
)

filegroup(
    name = "foo_static",
    srcs = [":foo"],
    output_group = "static",
)

Using the race detector

You can run tests with the race detector enabled using

bazel test --features=race //...

You can build binaries with the race detector enabled using

bazel build --output_groups=race //...

The difference is necessary because the rules for binaries can produce both race and non-race versions, but tools used during the build should always be built in the non-race configuration. --output_groups is needed to select the configuration of the final binary only. For tests, only one executable can be tested, and --features is needed to select the race configuration.

FAQ

Can I still use the `go` tool?

Yes, this setup was deliberately chosen to be compatible with the go tool. Make sure your workspace appears under

$GOPATH/src/github.com/joe/project/

eg.

mkdir -p $GOPATH/src/github.com/joe/
ln -s my/bazel/workspace $GOPATH/src/github.com/joe/project

and it should work.

What's up with the `go_default_library` name?

This is used to keep import paths consistent in libraries that can be built with go build.

In order to compile and link correctly, the Go rules need to be able to translate between Bazel labels and Go import paths. Let's say your project name is github.com/joe/project, and you have a library in the foo/bar directory named bar. The Bazel label for this would be //foo/bar:bar. The Go import path for this would be github.com/joe/project/foo/bar/bar.

This is not what go build expects; it expects github.com/joe/project/foo/bar/bar to refer to a library built from .go files in the directory foo/bar/bar.

In order to avoid this conflict, you can name your library go_default_library. The full Bazel label for this library would be //foo/bar:go_default_library. The import path would be github.com/joe/project/foo/bar.

BUILD files generated with Gazelle, including those in external projects imported with go_repository, will have libraries named go_default_library automatically.

Repository rules

`go_rules_dependencies`

go_rules_dependencies()

Adds Go-related external dependencies to the WORKSPACE, including the Go toolchain and standard library. All the other workspace rules and build rules assume that this rule is placed in the WORKSPACE. When nested workspaces arrive this will be redundant.

`go_register_toolchains`

go_register_toolchains(go_version)

Installs the Go toolchains. If go_version is specified, it sets the SDK version to use (for example, "1.8.2"). By default, the latest SDK will be used.

`go_repository`

go_repository(name, importpath, commit, tag, vcs, remote, urls, strip_prefix, type, sha256, build_file_name, build_file_generation, build_tags)

Fetches a remote repository of a Go project, and generates BUILD.bazel files if they are not already present. In vcs mode, it recognizes importpath redirection.

importpath must always be specified. This is used as the root import path for libraries in the repository.

If the repository should be fetched using a VCS, either commit or tag must be specified. remote and vcs may be specified if they can't be inferred from importpath using the normal go logic.

If the repository should be fetched using source archives, urls and sha256 must be specified. strip_prefix and type may be specified to control how the archives are unpacked.

build_file_name, build_file_generation, and build_tags may be used to control how BUILD.bazel files are generated. By default, Gazelle will generate BUILD.bazel files if they are not already present.

Attributes
`name`	`String, required` A unique name for this external dependency.
`importpath`	`String, required` The root import path for libraries in the repository.
`commit`	`String, optional` The commit hash to checkout in the repository. Exactly one of `commit` or `tag` must be specified.
`tag`	`String, optional` The tag to checkout in the repository. Exactly one of `commit` or `tag` must be specified.
`vcs`	`String, optional` The version control system to use for fetching the repository. Useful for disabling importpath redirection if necessary. May be `"git"`, `"hg"`, `"svn"`, or `"bzr"`.
`remote`	`String, optional` The URI of the target remote repository, if this cannot be determined from the value of `importpath`.
`urls`	`List of Strings, optional` URLs for one or more source code archives. See `http_archive` for more details.
`strip_prefix`	`String, optional` The internal path prefix to strip when the archive is extracted. See `http_archive` for more details.
`type`	`String, optional` The type of the archive, only needed if it cannot be inferred from the file extension. See `http_archive` for more details.
`sha256`	`String, optional` The expected SHA-256 hash of the file downloaded. See `http_archive` for more details.
`build_file_name`	`String, optional` The name to use for the generated build files. Defaults to BUILD.bazel.
`build_file_generation`	`String, optional` Used to force build file generation. `"off"` means do not generate build files. `"on"` means always run gazelle, even if build files are already present `"auto"` is the default and runs gazelle only if there is no root build file
`build_tags`	`String, optional` The set of tags to pass to gazelle when generating build files.

Example:

The rule below fetches a repository with Git. Import path redirection is used to automatically determine the true location of the repository.

load("@io_bazel_rules_go//go:def.bzl", "go_repository")

go_repository(
    name = "org_golang_x_tools",
    importpath = "golang.org/x/tools",
    commit = "663269851cdddc898f963782f74ea574bcd5c814",
)

The rule below fetches a repository archive with HTTP. GitHub provides HTTP archives for all repositories. It's generally faster to fetch these than to checkout a repository with Git, but the strip_prefix part can break if the repository is renamed.

load("@io_bazel_rules_go//go:def.bzl", "go_repository")

go_repository(
    name = "org_golang_x_tools",
    importpath = "golang.org/x/tools",
    urls = ["https://codeload.github.com/golang/tools/zip/663269851cdddc898f963782f74ea574bcd5c814"],
    strip_prefix = "tools-663269851cdddc898f963782f74ea574bcd5c814",
    type = "zip",
)

`new_go_repository`

new_go_repository is deprecated. Please use go_repository instead, which has the same functionality.

Build rules

`go_prefix`

go_prefix(prefix)

go_prefix declares the common prefix of the import path which is shared by all Go libraries in the repository. A go_prefix rule must be declared in the top-level BUILD file for any repository containing Go rules. This is used by the Bazel rules during compilation to map import paths to dependencies. See the FAQ for more information.

Attributes
`prefix`	`String, required` Global prefix used to fully qualify all Go targets.

`go_library`

go_library(name, srcs, deps, data, library, gc_goopts)

go_library builds a Go library from a set of source files that are all part of the same package. This library cannot contain cgo code (see cgo_library).

Attributes
`name`	`Name, required` A unique name for this rule.
`srcs`	`List of labels, required` List of Go `.go` (at least one) or ASM `.s/.S` source files used to build the library
`deps`	`List of labels, optional` List of other libraries to linked to this library target
`data`	`List of labels, optional` List of files needed by this rule at runtime.
`library`	`Label, optional` A label of another rule with Go `srcs`, `deps`, and `data`. When this library is compiled, the sources from this attribute will be combined with `srcs`. This is commonly used to depend on Go sources in `cgo_library`.
`gc_goopts`	`List of strings, optional` List of flags to add to the Go compilation command. Subject to Make variable substitution and Bourne shell tokenization.

`cgo_library`

cgo_library(name, srcs, copts, clinkopts, cdeps, deps, data, gc_goopts)

cgo_library builds a Go library from a set of cgo source files that are part of the same package. This library cannot contain pure Go code (see the note below).

Attributes
`name`	`Name, required` A unique name for this rule.
`srcs`	`List of labels, required` List of Go, C and C++ files that are processed to build a Go library. Those Go files must contain `import "C"`. C and C++ files can be anything allowed in `srcs` attribute of `cc_library`.
`copts`	`List of strings, optional` Add these flags to the C++ compiler
`clinkopts`	`List of strings, optional` Add these flags to the C++ linker
`cdeps`	`List of labels, optional` List of C/C++ libraries to be linked into the binary target. They must be `cc_library` rules.
`deps`	`List of labels, optional` List of other Go libraries to be linked to this library
`data`	`List of labels, optional` List of files needed by this rule at runtime.
`gc_goopts`	`List of strings, optional` List of flags to add to the Go compilation command. Subject to Make variable substitution and Bourne shell tokenization.

NOTE

srcs cannot contain pure-Go files, which do not have import "C". So you need to define another go_library when you build a go package with both cgo-enabled and pure-Go sources.

cgo_library(
    name = "cgo_enabled",
    srcs = ["cgo-enabled.go", "foo.cc", "bar.S", "baz.a"],
)

go_library(
    name = "go_default_library",
    srcs = ["pure-go.go"],
    library = ":cgo_enabled",
)

`go_binary`

go_binary(name, srcs, deps, data, library, linkstamp, x_defs, gc_goopts, gc_linkopts)

go_binary builds an executable from a set of source files, which must all be in the main package. You can run the with bazel run, or you can run it directly.

Attributes
`name`	`Name, required` A unique name for this rule.
`srcs`	`List of labels, required` List of Go `.go` (at least one) or ASM `.s/.S` source files used to build the binary
`deps`	`List of labels, optional` List of other Go libraries to linked to this binary target
`data`	`List of labels, optional` List of files needed by this rule at runtime.
`library`	`Label, optional` A label of another rule with Go `srcs`, `deps`, and `data`. When this binary is compiled, the sources from this attribute will be combined with `srcs`. This is commonly used to depend on Go sources in `cgo_library`.
`linkstamp`	`String; optional; default is ""` The name of a package containing global variables set by the linker as part of a link stamp. This may be used to embed version information in the generated binary. The -X flags will be of the form `-X linkstamp.KEY=VALUE`. The keys and values are read from `bazel-bin/volatile-status.txt` and `bazel-bin/stable-status.txt`. If you build with `--workspace_status_command=./status.sh`, the output of `status.sh` will be written to these files. Bazel `tools/buildstamp/get_workspace_status` is a good template which prints Git workspace status.
`x_defs`	`Dict of strings; optional` Additional -X flags to pass to the linker. Keys and values in this dict are passed as `-X key=value`. This can be used to set static information that doesn't change in each build. If the value is surrounded by curly brackets (e.g. `{VAR}`), then the value of the corresponding workspace status variable will be used instead. Valid workspace status variables include `BUILD_USER`, `BUILD_EMBED_LABEL`, and custom variables provided through a `--workspace_status_command` as described in `linkstamp`.
`gc_goopts`	`List of strings, optional` List of flags to add to the Go compilation command. Subject to Make variable substitution and Bourne shell tokenization.
`gc_linkopts`	`List of strings, optional` List of flags to add to the Go link command. Subject to Make variable substitution and Bourne shell tokenization.

`go_test`

go_test(name, srcs, deps, data, library, gc_goopts, gc_linkopts, rundir)

go_test builds a set of tests that can be run with bazel test. This can contain sources for internal tests or external tests, but not both (see example below).

To run all tests in the workspace, and print output on failure (the equivalent of "go test ./..." from go_prefix in a GOPATH tree), run

bazel test --test_output=errors //...

You can run specific tests by passing the --test_filter=pattern argument to Bazel. You can pass arguments to tests by passing --test_arg=arg arguments to Bazel.

Attributes
`name`	`Name, required` A unique name for this rule.
`srcs`	`List of labels, required` List of Go `.go` (at least one) or ASM `.s/.S` source files used to build the test
`deps`	`List of labels, optional` List of other Go libraries to linked to this test target
`data`	`List of labels, optional` List of files needed by this rule at runtime.
`library`	`Label, optional` A label of another rule with Go `srcs`, `deps`, and `data`. When this library is compiled, the sources from this attribute will be combined with `srcs`.
`gc_goopts`	`List of strings, optional` List of flags to add to the Go compilation command. Subject to Make variable substitution and Bourne shell tokenization.
`gc_linkopts`	`List of strings, optional` List of flags to add to the Go link command. Subject to Make variable substitution and Bourne shell tokenization.
`rundir`	`String, optional` Path to the directory the test should run in. This should be relative to the root of the repository the test is defined in. By default, the test will run in the directory of the BUILD file that defines it. Use "." to run the test at the repository root.

Example

To write an internal test, reference the library being tested with the library attribute instead of the deps attribute. This will compile the test sources into the same package as the library sources.

go_library(
    name = "go_default_library",
    srcs = ["lib.go"],
)

go_test(
    name = "go_default_test",
    srcs = ["lib_test.go"],
    library = ":go_default_library",
)

To write an external test, reference the library being tested with the deps attribute.

go_library(
    name = "go_default_library",
    srcs = ["lib.go"],
)

go_test(
    name = "go_default_xtest",
    srcs = ["lib_x_test.go"],
    deps = [":go_default_library"],
)

`go_proto_library`

go_proto_library(name, srcs, deps, has_services)

Attributes
`name`	`Name, required` A unique name for the underlying go_library rule. (usually `go_default_library`)
`srcs`	`List of labels, required` List of Protocol Buffer `.proto` source files used to generate `.go` sources for a go_library
`deps`	`List of labels, optional` List of other go_proto_library(s) to depend on. Note: this also works if the label is a go_library, and there is a filegroup {name}+"_protos" (which is used for golang protobuf)
`has_services`	`integer, optional, defaults to 0` If 1, will generate with `plugins=grpc` and add the required dependencies.
`ignore_go_package_option`	`integer, optional, defaults to 0` If 1, will ignore the go_package option in the srcs proto files. Note: this will not work if the go_package options are specified in more than one line.

`go_embed_data`

go_embed_data(name, src, srcs, out, package, var, flatten, string)

Attributes
`name`	`Name, required` A unique name for the go_embed_data rule.
`src`	`Label, optional` A single file to embed. This cannot be used at the same time as `srcs`. The generated file will have a variable of type `[]byte` or `string` with the contents of this file.
`srcs`	`List of labels, optional` A list of files to embed. This cannot be used at the same time as `src`. The generated file will have a variable of type `map[string][]byte` or `map[string]string` with the contents of each file. The map keys are relative paths the files from the repository root. Keys for files in external repositories will be prefixed with "external/repo/" where "repo" is the name of the external repository.
`out`	`String, required` Name of the .go file to generated. This may be referenced by other rules, such as `go_library`.
`package`	`String, optional, defaults to directory base name` Go package name for the generated .go file. This defaults to the name of the directory containing the `go_embed_data` rule. This attribute is required in the repository root directory though.
`var`	`String, optional, defaults to "Data"` Name of the variable that will contain the embedded data.
`flatten`	`Boolean, optional, defaults to false` If true and `srcs` is used, map keys are file base names instead of relative paths.
`string`	`Boolean, optional, defaults to false` If true, the embedded data will be stored as `string` instead of `[]byte`.

Example:

The foo_data rule below will generate a file named foo_data.go, which can be included in a library. Gazelle will find and add these files automatically.

load("@io_bazel_rules_go//go:def.bzl", "go_embed_data", "go_library")

go_embed_data(
    name = "foo_data",
    src = "foo.txt",
    out = "foo_data.go",
    package = "foo",
    string = True,
    var = "Data",
)

go_library(
    name = "go_default_library",
    srcs = ["foo_data.go"],
)

The generated file will look like this:

// Generated by go_embed_data for //:foo_data. DO NOT EDIT.

package foo



var Data = "Contents of foo.txt"

htuch / rules_go

Go rules for Bazel

Announcements

Contents

Overview

Setup

Generating build files

Build modes

Building static binaries

Using the race detector

FAQ

Can I still use the `go` tool?

What's up with the `go_default_library` name?

Repository rules

`go_rules_dependencies`

`go_register_toolchains`

`go_repository`

Example:

`new_go_repository`

Build rules

`go_prefix`

`go_library`

`cgo_library`

NOTE

`go_binary`

`go_test`

Example

`go_proto_library`

`go_embed_data`

Example:

About

Languages

Go rules for Bazel

Announcements

Contents

Overview

Setup

Generating build files

Build modes

Building static binaries

Using the race detector

FAQ

Can I still use the go tool?

What's up with the go_default_library name?

Repository rules

go_rules_dependencies

go_register_toolchains

go_repository

Example:

new_go_repository

Build rules

go_prefix

go_library

cgo_library

NOTE

go_binary

go_test

Example

go_proto_library

go_embed_data

Example:

About

Languages

Can I still use the `go` tool?

What's up with the `go_default_library` name?

`go_rules_dependencies`

`go_register_toolchains`

`go_repository`

`new_go_repository`

`go_prefix`

`go_library`

`cgo_library`

`go_binary`

`go_test`

`go_proto_library`

`go_embed_data`