Go rules

Bazel ≥0.4.4	linux-x86_64	ubuntu_15.10-x86_64	darwin-x86_64

Overview
Setup
Generating build files
FAQ
Repository rules
go_repositories
go_repository
new_go_repository
Build rules
go_prefix
go_library
cgo_library
go_binary
go_test
go_proto_library

Overview

The rules should be considered experimental. 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):

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

Note: this repo requires bazel ≥ 0.4.4 to function (due to the use of BUILD.bazel files in bazelbuild/buildifier).

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.

Add the following to your WORKSPACE file:

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

go_repositories()

If your project follows the structure that go build uses, you can generate your BUILD files with Gazelle. If not, read on.
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.
```
load("@io_bazel_rules_go//go:def.bzl", "go_prefix")

go_prefix("github.com/joe/project")
```
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 you project is compatible with the go tool, you can generate and update your BUILD files automatically using Gazelle, a command line tool which is part of this repository.

You can install Gazelle using the command below. This assumes this repository is checked out under GOPATH.

go install github.com/bazelbuild/rules_go/go/tools/gazelle/gazelle

To run Gazelle for the first time, run the command below from your project root directory.

gazelle -go_prefix github.com/joe/project

To update your BUILD files later, just 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, run gazelle with -external vendored. See Vendoring.md.

See the Gazelle README for more information.

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_repositories`

go_repositories()

Instantiates external dependencies to Go toolchain in a WORKSPACE. All the other workspace rules and build rules assume that this rule is placed in the WORKSPACE.

`go_repository`

go_repository(name, importpath, remote, vcs, commit, tag)

Fetches a remote repository of a Go project, expecting it contains BUILD files. It is an analogy to git_repository but it recognizes importpath redirection of Go.

Either importpath or remote may be specified. To bypass importpath redirection, specify both remote and vcs.

Attributes
`name`	`String, required` A unique name for this external dependency.
`importpath`	`String, optional` An import path in Go, which also provides a default value for the root of the target remote repository
`remote`	`String, optional` The URI of the target remote repository, if this cannot be determined from the value of `importpath`.
`vcs`	`String, optional` The version control system to use for fetching the repository. Useful for disabling importpath redirection if necessary.
`commit`	`String, optional` The commit hash to checkout in the repository. Note that one of either `commit` or `tag` must be defined.
`tag`	`String, optional` The tag to checkout in the repository. Note that one of either `commit` or `tag` must be defined.

`new_go_repository`

new_go_repository(name, importpath, remote, vcs, commit, tag)

Fetches a remote repository of a Go project and automatically generates BUILD files in it. It is an analogy to new_git_repository but it recognizes importpath redirection of Go.

Attributes
`name`	`String, required` A unique name for this external dependency.
`importpath`	`String, optional` An import path in Go, which also provides a default value for the root of the target remote repository
`remote`	`String, optional` The URI of the target remote repository, if this differs from the value of `importpath`
`vcs`	`String, optional` The version control system to use for fetching the repository.
`commit`	`String, optional` The commit hash to checkout in the repository. Note that one of either `commit` or `tag` must be defined.
`tag`	`String, optional` The tag to checkout in the repository. Note that one of either `commit` or `tag` must be defined.

Build rules

`go_prefix`

go_prefix(prefix)

Attributes

Attributes
`prefix`	`String, required` Global prefix used to fully qualify all Go targets. In Go, imports are always fully qualified with a URL, eg. `github.com/user/project`. Hence, a label `//foo:bar` from within a Bazel workspace must be referred to as `github.com/user/project/foo/bar`. To make this work, each rule must know the repository's URL. This is achieved, by having all go rules depend on a globally unique target that has a `go_prefix` transitive info provider.

prefix

String, required

Global prefix used to fully qualify all Go targets.

In Go, imports are always fully qualified with a URL, eg. github.com/user/project. Hence, a label //foo:bar from within a Bazel workspace must be referred to as github.com/user/project/foo/bar. To make this work, each rule must know the repository's URL. This is achieved, by having all go rules depend on a globally unique target that has a go_prefix transitive info provider.

`go_library`

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

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)

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)

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.
`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)

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.

NOTE

In order for a go_test to refer to private definitions within a go_library, it must on the library's sources through the library attribute, not the deps attribute.

go_library(
    name = "go_default_library",
    srcs = glob(["*.go"], exclude=["*_test.go"]),
)

go_test(
    name = "go_default_test",
    srcs = glob(["*_test.go"]),
    library = ":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.
`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.

xtrqt/rules_go

Go rules

Contents

Overview

Setup

Generating build files

FAQ

Can I still use the `go` tool?

What's up with the `go_default_library` name?

Repository rules

`go_repositories`

`go_repository`

`new_go_repository`

Build rules

`go_prefix`

`go_library`

`cgo_library`

NOTE

`go_binary`

`go_test`

NOTE

`go_proto_library`

xtrqt/rules_go

Go rules

Contents

Overview

Setup

Generating build files

FAQ

Can I still use the go tool?

What's up with the go_default_library name?

Repository rules

go_repositories

go_repository

new_go_repository

Build rules

go_prefix

go_library

cgo_library

NOTE

go_binary

go_test

NOTE

go_proto_library

Can I still use the `go` tool?

What's up with the `go_default_library` name?

`go_repositories`

`go_repository`

`new_go_repository`

`go_prefix`

`go_library`

`cgo_library`

`go_binary`

`go_test`

`go_proto_library`