rules_go

module
v0.5.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 17, 2017 License: Apache-2.0

README

Go rules for Bazel

Bazel ≥0.5.2 linux-x86_64 ubuntu_15.10-x86_64 darwin-x86_64
Build Status Build Status Build Status Build Status

Announcements

  • July 14, 2017 Release 0.5.2 is now available! This fixes an issue with Bazel at HEAD. Note that Bazel 0.5.2 is now required.
  • July 12, 2017 The rules now require Bazel 0.5.2 or newer at HEAD. The latest tagged version, 0.5.1, still works with Bazel 0.4.5 though.
  • July 10, 2017 Release 0.5.1 is now available!
  • June 13, 2017 Release 0.5.0 is now available!

Contents

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: The latest version of these rules (0.5.2) require Bazel ≥ 0.5.2 to work.

The master branch is only guaranteed to work with the latest version of Bazel.

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.5.2",
    )
    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)

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.

Attributes
go_version String, optional

The Go version to use. If none of the parameters are specified, the most recent stable version of Go will be used.

go_repository
go_repository(name, importpath, commit, tag, vcs, remote, urls, strip_prefix, type, sha256, build_file_name, build_file_generation, build_tags)

Fetches a remote repository of a Go project, and generates BUILD.bazel files if they are not already present. In vcs mode, it recognizes importpath redirection.

importpath must always be specified. This is used as the root import path for libraries in the repository.

If the repository should be fetched using a VCS, either commit or tag must be specified. remote and vcs may be specified if they can't be inferred from importpath using the normal go logic.

If the repository should be fetched using source archives, urls and sha256 must be specified. strip_prefix and type may be specified to control how the archives are unpacked.

build_file_name, build_file_generation, and build_tags may be used to control how BUILD.bazel files are generated. By default, Gazelle will generate BUILD.bazel files if they are not already present.

Attributes
name String, required

A unique name for this external dependency.

importpath String, required

The root import path for libraries in the repository.

commit String, optional

The commit hash to checkout in the repository.
Exactly one of commit or tag must be specified.

tag String, optional

The tag to checkout in the repository.
Exactly one of commit or tag must be specified.

vcs String, optional

The version control system to use for fetching the repository. Useful for disabling importpath redirection if necessary. May be "git", "hg", "svn", or "bzr".

remote String, optional

The URI of the target remote repository, if this cannot be determined from the value of importpath.

urls List of Strings, optional

URLs for one or more source code archives.
See http_archive for more details.

strip_prefix String, optional

The internal path prefix to strip when the archive is extracted.
See http_archive for more details.

type String, optional

The type of the archive, only needed if it cannot be inferred from the file extension.
See http_archive for more details.

sha256 String, optional

The expected SHA-256 hash of the file downloaded.
See http_archive for more details.

build_file_name String, optional

The name to use for the generated build files. Defaults to BUILD.bazel.

build_file_generation String, optional

Used to force build file generation.
"off" means do not generate build files.
"on" means always run gazelle, even if build files are already present
"auto" is the default and runs gazelle only if there is no root build file

build_tags String, optional

The set of tags to pass to gazelle when generating build files.

Example:

The rule below fetches a repository with Git. Import path redirection is used to automatically determine the true location of the repository.

load("@io_bazel_rules_go//go:def.bzl", "go_repository")

go_repository(
    name = "org_golang_x_tools",
    importpath = "golang.org/x/tools",
    commit = "663269851cdddc898f963782f74ea574bcd5c814",
)

The rule below fetches a repository archive with HTTP. GitHub provides HTTP archives for all repositories. It's generally faster to fetch these than to checkout a repository with Git, but the strip_prefix part can break if the repository is renamed.

load("@io_bazel_rules_go//go:def.bzl", "go_repository")

go_repository(
    name = "org_golang_x_tools",
    importpath = "golang.org/x/tools",
    urls = ["https://codeload.github.com/golang/tools/zip/663269851cdddc898f963782f74ea574bcd5c814"],
    strip_prefix = "tools-663269851cdddc898f963782f74ea574bcd5c814",
    type = "zip",
)
new_go_repository

new_go_repository is deprecated. Please use go_repository instead, which has the same functionality.

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.

Attributes
prefix String, required

Global prefix used to fully qualify all Go targets.

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

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.

library Label, optional

A label of another rule with Go `srcs`, `deps`, and `data`. When this library is compiled, the sources from this attribute will be combined with `srcs`. This is commonly used to depend on Go sources in `cgo_library`.

gc_goopts List of strings, optional

List of flags to add to the Go compilation command. Subject to Make variable substitution and Bourne shell tokenization.

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

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.

gc_goopts List of strings, optional

List of flags to add to the Go compilation command. Subject to Make variable substitution and Bourne shell tokenization.

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.

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.

library Label, optional

A label of another rule with Go `srcs`, `deps`, and `data`. When this binary is compiled, the sources from this attribute will be combined with `srcs`. This is commonly used to depend on Go sources in `cgo_library`.

linkstamp String; optional; default is ""

The name of a package containing global variables set by the linker as part of a link stamp. This may be used to embed version information in the generated binary. The -X flags will be of the form -X linkstamp.KEY=VALUE. The keys and values are read from bazel-bin/volatile-status.txt and bazel-bin/stable-status.txt. If you build with --workspace_status_command=./status.sh, the output of status.sh will be written to these files. Bazel tools/buildstamp/get_workspace_status is a good template which prints Git workspace status.

x_defs Dict of strings; optional

Additional -X flags to pass to the linker. Keys and values in this dict are passed as -X key=value. This can be used to set static information that doesn't change in each build.

If the value is surrounded by curly brackets (e.g. {VAR}), then the value of the corresponding workspace status variable will be used instead. Valid workspace status variables include BUILD_USER, BUILD_EMBED_LABEL, and custom variables provided through a --workspace_status_command as described in linkstamp.

gc_goopts List of strings, optional

List of flags to add to the Go compilation command. Subject to Make variable substitution and Bourne shell tokenization.

gc_linkopts List of strings, optional

List of flags to add to the Go link command. Subject to Make variable substitution and Bourne shell tokenization.

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.

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.

library Label, optional

A label of another rule with Go `srcs`, `deps`, and `data`. When this library is compiled, the sources from this attribute will be combined with `srcs`.

gc_goopts List of strings, optional

List of flags to add to the Go compilation command. Subject to Make variable substitution and Bourne shell tokenization.

gc_linkopts List of strings, optional

List of flags to add to the Go link command. Subject to Make variable substitution and Bourne shell tokenization.

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)
Attributes
name Name, required

A unique name for the underlying go_library rule. (usually `go_default_library`)

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.

ignore_go_package_option integer, optional, defaults to 0

If 1, will ignore the go_package option in the srcs proto files. Note: this will not work if the go_package options are specified in more than one line.

Directories

Path Synopsis
examples
bin
cgo
external
Command record_log just records a log with glog to show an example of linking with a external dependency.
Command record_log just records a log with glog to show an example of linking with a external dependency.
lib
lib/deep
Package deep provides an emulator of a computer which calculates answer to the ultimate question of Life, the Universe, and Everything.
Package deep provides an emulator of a computer which calculates answer to the ultimate question of Life, the Universe, and Everything.
go
tools/bazel
Package bazel provides utilities for interacting with the surrounding Bazel environment.
Package bazel provides utilities for interacting with the surrounding Bazel environment.
tools/builders
asm builds a single .s file with "go tool asm".
asm builds a single .s file with "go tool asm".
tools/extract_package
Command extract_package is a helper program that extracts a package name from a golang source file.
Command extract_package is a helper program that extracts a package name from a golang source file.
tools/fetch_repo
Command fetch_repo is similar to "go get -d" but it works even if the given repository path is not a buildable Go package and it checks out a specific revision rather than the latest revision.
Command fetch_repo is similar to "go get -d" but it works even if the given repository path is not a buildable Go package and it checks out a specific revision rather than the latest revision.
tools/gazelle/gazelle
Command gazelle is a BUILD file generator for Go projects.
Command gazelle is a BUILD file generator for Go projects.
tools/gazelle/merger
Package merger provides methods for merging parsed BUILD files.
Package merger provides methods for merging parsed BUILD files.
tools/gazelle/packages
Package packages provides Go package traversal in a Bazel repository.
Package packages provides Go package traversal in a Bazel repository.
tools/gazelle/rules
Package rules provides Bazel rule generation for Go build targets.
Package rules provides Bazel rule generation for Go build targets.
tools/gazelle/wspace
Package wspace provides functions to locate and modify a bazel WORKSPACE file.
Package wspace provides functions to locate and modify a bazel WORKSPACE file.
tools/wtool
wtool augments your bazel WORKSPACE file with go_repository entries Example Usage: wtool com_github_golang_glog com_google_cloud_go will add 2 go_repository rules to your WORKSPACE by converting com_github_golang_glog -> github.com/golang/glog and so forth and then doing a 'git ls-remote' to get the latest commit.
wtool augments your bazel WORKSPACE file with go_repository entries Example Usage: wtool com_github_golang_glog com_google_cloud_go will add 2 go_repository rules to your WORKSPACE by converting com_github_golang_glog -> github.com/golang/glog and so forth and then doing a 'git ls-remote' to get the latest commit.
tests

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL