rules_go

module
v0.4.1 Latest Latest
Warning

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

Go to latest
Published: Mar 3, 2017 License: Apache-2.0

README

Go rules

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

Overview

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 (//+build comments - 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)

Setup

  • 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.4.1",
    )
    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 using go_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, 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.

    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.

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

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

Disclaimer

These rules are not supported by Google's Go team.

go_repositories

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

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 importpath

commit String, optional

The commit hash to checkout in the repository.

Note that one of either commit or tag must be defined.

tag String, optional

The tag to checkout in the repository.

Note that one of either commit or tag must be defined.

new_go_repository

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 importpath

commit String, optional

The commit hash to checkout in the repository.

Note that one of either commit or tag must be defined.

tag String, optional

The tag to checkout in the repository.

Note that one of either commit or tag must be defined.

go_prefix

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. github.com/user/project. Hence, a label //foo:bar from within a Bazel workspace must be referred to as github.com/user/project/foo/bar. To make this work, each rule must know the repository's URL. This is achieved, by having all go rules depend on a globally unique target that has a go_prefix transitive info provider.

go_library

go_library(name, srcs, deps, data)
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.

cgo_library

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

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

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.

go_test

go_test(name, srcs, deps, data)
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.

....

go_proto_library

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

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/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/generator
Package generator provides core functionality of BUILD file generation in gazelle.
Package generator provides core functionality of BUILD file generation in gazelle.
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 new_go_repository entries Example Usage: wtool com_github_golang_glog com_google_cloud_go will add 2 new_go_repository 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 new_go_repository entries Example Usage: wtool com_github_golang_glog com_google_cloud_go will add 2 new_go_repository 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