commit | 4c9a52aba0b59511c5646af88d2f93a9c0193647 | [log] [tgz] |
---|---|---|
author | Jay Conrod <jayconrod@gmail.com> | Fri May 05 17:43:28 2017 -0400 |
committer | Jay Conrod <jayconrod@google.com> | Fri May 05 17:44:23 2017 -0400 |
tree | ac332e58dd4c94a814958a537d340611cfa2a8ce | |
parent | 52eb4dcab0b57c99d36d6c64c7cc5fccec87ce19 [diff] |
Update README.md in preparation for 0.4.4 release (#439)
Bazel ≥0.4.4 | linux-x86_64 | ubuntu_15.10-x86_64 | darwin-x86_64 |
---|---|---|---|
0.3.4
, 0.4.2
, or master
to get your build working again.The rules are in the alpha stage of development. They support:
They currently do not support (in order of importance):
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
. 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.4", ) 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.
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.
go install github.com/bazelbuild/rules_go/go/tools/gazelle/gazelle
gazelle -go_prefix github.com/joe/project
BUILD
files later, just run gazelle
.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.
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.
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.
go_repositories
go_repositories(go_version, go_linux, go_darwin)
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.
Suppose you have your own fork of Go, perhaps with some custom patches applied. To use that toolchain with these rules, declare the toolchain repository with a workspace rule, such as new_git_repository
or local_repository
, then pass it to go_repositories
as below. The rules expect Go binaries and libraries to be present in the bin/
and pkg/
directories, so you'll need a different repository for each supported host platform.
new_git_repository( name = "custom_go_linux", remote = "https://github.com/j_r_hacker/go_linux", tag = "2.5", build_file_content = "", ) new_git_repository( name = "custom_go_darwin", remote = "https://github.com/j_r_hacker/go_darwin", tag = "2.5", build_file_content = "", ) go_repositories( go_linux = "@custom_go_linux", go_darwin = "@custom_go_darwin", )
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
.
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.
go_prefix
go_prefix(prefix)
go_library
go_library(name, srcs, deps, data, library, gc_goopts)
cgo_library
cgo_library(name, srcs, copts, clinkopts, cdeps, deps, data, gc_goopts)
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_test
go_test(name, srcs, deps, data, library, gc_goopts, gc_linkopts)
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)