The rules should be considered experimental. They support:
- libraries
- binaries
- tests
- vendoring
- cgo
They currently do not support (in order of importance):
- build constraints/tags (
//+build
comments - see here)) - auto generating BUILD files
- C/C++ interoperation except cgo (swig etc.)
- race detector
- coverage
- test sharding
-
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.2.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 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/project
and 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, 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 |
tag |
String, optional
The tag to checkout in the repository. Note that one of either |
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 |
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. |