| Bazel ≥0.3.1 | linux-x86_64 | ubuntu_15.10-x86_64 | darwin-x86_64 |
|---|---|---|---|
 |
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 (
//+buildcomments - 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
Note: this repo requires bazel >= 0.4.4 to function (due to the use of BUILD.bazel files in bazelbuild/buildifier)
-
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", DE24 tag = "0.4.0", ) load("@io_bazel_rules_go//go:def.bzl", "go_repositories") go_repositories()
-
Add a
BUILDfile to the top of your workspace, declaring the name of your workspace usinggo_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, createlib/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.
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/projectand it should work.
These rules are not supported by Google's Go team.
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(name, importpath, remote, 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 also provides a default value for the root of the target remote repository |
remote |
String, optional
The root of the target remote repository, if this differs from the
value of |
commit |
String, optional
The commit hash to checkout in the repository. Note that one of either |
tag |
String, optional
The tag to checkout in the repository. Note that one of either |
new_go_repository(name, importpath, remote, 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 also provides a default value for the root of the target remote repository |
remote |
String, optional
The root of the target remote repository, if this differs from the
value of |
commit |
String, optional
The commit hash to checkout in the repository. Note that one of either |
tag |
String, optional
The tag to checkout in the repository. Note that one of either |
go_prefix(prefix)| Attributes | |
|---|---|
prefix |
String, required
Global prefix used to fully qualify all Go targets.
In Go, imports are always fully qualified with a URL, eg.
|
go_library(name, srcs, deps, data)| Attributes | |
|---|---|
name |
Name, required
A unique name for this rule. |
srcs |
List of labels, required
List of Go |
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(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 |
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 |
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. |
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(name, srcs, deps, data)| Attributes | |
|---|---|
name |
Name, required
A unique name for this rule. |
srcs |
List of labels, required
List of Go |
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(name, srcs, deps, data)| Attributes | |
|---|---|
name |
Name, required
A unique name for this rule. |
srcs |
List of labels, required
List of Go |
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(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 |
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 |