Go rules

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

Rules

go_repositories
go_repository
new_go_repository
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):

build constraints/tags (//+build comments - see here))
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

Setup

Decide on the name of your package, eg. github.com/joe/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.3.0",
)
load("@io_bazel_rules_go//go:def.bzl", "go_repositories")

go_repositories()

Add a BUILD file to the top of your workspace, declaring the name of your workspace using go_prefix. This prefix is used for Go's "import" statements to refer to packages within your own project, so it's important to choose a prefix that might match the location that another user might choose to put your code into.
```
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.
```
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.

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

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

eg.

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

and it should work.

Disclaimer

These rules are not supported by Google's Go team.

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, 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.

Attributes
`name`	`String, required` A unique name for this external dependency.
`importpath`	`String, required` An import path in Go, which corresponds to the root of the target remote 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.

new_go_repository

new_go_repository(name, importpath, 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, required` An import path in Go, which corresponds to the root of the target remote 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.

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)

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.

cgo_library

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

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.

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)

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.

go_test

go_test(name, srcs, deps, data)

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.

....

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.

yohcop/rules_go