rules_go_pushserver

Go rules for Bazel

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

Announcements

• May 5, 2017 Release 0.4.4 is now available!
• April 12, 2017 Release 0.4.3 is now available!
• April 7, 2017 Builds using rules_go recently broke (#361) because of a name change in buildifier, one of our dependencies. You can upgrade to 0.3.4, 0.4.2, or master to get your build working again.

Contents

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

Overview

The rules are in the alpha stage of development. 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):

• cross compilation
• 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: since 0.4.x this repo requires bazel ≥ 0.4.4 to function (due to the use of BUILD.bazel files in bazelbuild/buildtools).

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

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

Example:

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, build_tags, url, string_prefix, type, sha256, build_file_name, build_file_generation)

Fetches a remote repository of a Go project, and generates BUILD files if needed. In vcs mode it recognizes importpath redirection of Go.

The importpath import path must always be specified. If url is specified, it is expected to be the url for a source archive. If remote and vcs are both specified, they control the source repository to be cloned for the import path. If neither a vcs nor a url are specified, the vcs will be inferred from the import path using the normal go logic.

Build rules

go_prefix

go_prefix(prefix)

go_prefix declares the common prefix of the import path which is shared by all Go libraries in the repository. A go_prefix rule must be declared in the top-level BUILD file for any repository containing Go rules. This is used by the Bazel rules during compilation to map import paths to dependencies. See the FAQ for more information.

go_library

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

go_library builds a Go library from a set of source files that are all part of the same package. This library cannot contain cgo code (see cgo_library).

cgo_library

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

cgo_library builds a Go library from a set of cgo source files that are part of the same package. This library cannot contain pure Go code (see the note below).

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)

go_binary builds an executable from a set of source files, which must all be in the main package. You can run the with bazel run, or you can run it directly.

go_test

go_test(name, srcs, deps, data, library, gc_goopts, gc_linkopts)

go_test builds a set of tests that can be run with bazel test. This can contain sources for internal tests or external tests, but not both (see example below).

You can run specific tests by passing the --test_filter=pattern argument to Bazel. You can pass arguments to tests by passing --test_arg=arg arguments to Bazel.

Example

To write an internal test, reference the library being tested with the library attribute instead of the deps attribute. This will compile the test sources into the same package as the library sources.

go_library(
    name = "go_default_library",
    srcs = ["lib.go"],
)

go_test(
    name = "go_default_test",
    srcs = ["lib_test.go"],
    library = ":go_default_library",
)

To write an external test, reference the library being tested with the deps attribute.

go_library(
    name = "go_default_library",
    srcs = ["lib.go"],
)

go_test(
    name = "go_default_xtest",
    srcs = ["lib_x_test.go"],
    deps = [":go_default_library"],
)

go_proto_library

go_proto_library(name, srcs, deps, has_services)