| commit | 5bbd4dc63afda883451d693adf12f8b3781f8bec | [log] [tgz] |
|---|---|---|
| author | Ian Cottrell <ian.the.hat@gmail.com> | Tue Sep 19 17:09:17 2017 -0400 |
| committer | GitHub <noreply@github.com> | Tue Sep 19 17:09:17 2017 -0400 |
| tree | 81f510fa9920a20e31b261071a85ea720332a83c | |
| parent | 47250c5b9053bb942c86772fbd3190e6a9125191 [diff] |
Initial shell of new documentation (#840) The old documentation is deliberatly still there so I can keep moving stuff over, and is still the one shown by default.
| Bazel 0.5.4 | Bazel HEAD |
|---|---|
 |
The rules are in the alpha stage of development. They support:
They currently do not support (in order of importance):
Note: The latest version of these rules (0.5.5) require Bazel ≥ 0.5.2 to work.
The master branch is only guaranteed to work with the latest version of Bazel.
Create a file at the top of your repository named WORKSPACE, and add one of the following snippets, verbatim. This will let Bazel fetch necessary dependencies from this repository and a few others. If you're using the latest stable release you can use the following contents:
http_archive( name = "io_bazel_rules_go", url = "https://github.com/bazelbuild/rules_go/releases/download/0.5.5/rules_go-0.5.5.tar.gz", sha256 = "ca58b0b856dc95473b93f2228ab117913b82a6617fc0deabd107346e3981522a", ) load("@io_bazel_rules_go//go:def.bzl", "go_repositories") go_repositories()
If you're using rules_go at or near the HEAD of master, you can use the following contents (optionally replacing the commit with something newer):
git_repository( name = "io_bazel_rules_go", remote = "https://github.com/bazelbuild/rules_go.git", commit = "d8d73c918ed7b59a5584e0cab4f5274d2f91faab", ) load("@io_bazel_rules_go//go:def.bzl", "go_rules_dependencies", "go_register_toolchains") go_rules_dependencies() go_register_toolchains()
You can add more external dependencies to this file later (see go_repository below).
Add a file named BUILD.bazel or BUILD in the root directory of your project. In general, you need one of these files in every directory with Go code, but you need one in the root directory even if your project doesn't have any Go code there.
Decide on a prefix for your project, e.g., github.com/example/project. This must be a prefix of the import paths for libraries in your project. It should generally be the repository URL. Bazel will use this prefix to convert between import paths and labels in build files.
If your project can be built with go build, you can generate your build files using Gazelle. If your project isn't compatible with go build or if you prefer not to use Gazelle, you can write build files by hand.
If your project can be built with go build, you can generate and update your build files automatically using Gazelle, a tool included in this repository. See the Gazelle README for more information.
BUILD.bazel file in your repository's root directory. Replace the prefix string with the prefix you chose for your project earlier.load("@io_bazel_rules_go//go:def.bzl", "gazelle") gazelle( name = "gazelle", prefix = "github.com/example/project", )
If your project uses vendoring, add external = "vendored", below the prefix line.
After adding the gazelle rule, run the command below:
bazel run //:gazelle
This will generate a BUILD.bazel file for each Go package in your repository. You can run the same command in the future to update existing build files with new source files, dependencies, and options.
If your project doesn't follow go build conventions or you prefer not to use Gazelle, you can write build files by hand.
In each directory that contains Go code, create a file named BUILD.bazel or BUILD (Bazel recognizes both names).
Add a load statement at the top of the file for the rules you use.
load("@io_bazel_rules_go//go:def.bzl", "go_binary", "go_library", "go_test")
go_library rule like the one below. Source files are listed in srcs. Other packages you import are listed in deps using Bazel labels that refer to other go_library rules. The library's import path should be specified with importpath.go_library( name = "go_default_library", srcs = [ "foo.go", "bar.go", ], deps = [ "//tools:go_default_library", "@org_golang_x_utils//stuff:go_default_library", ], importpath = "github.com/example/project/foo", visibility = ["//visibility:public"], )
go_test rule like either of the ones below. You'll need separate go_test rules for internal and external tests.# Internal test go_test( name = "go_default_test", srcs = ["foo_test.go"], importpath = "github.com/example/project/foo", library = ":go_default_library", ) # External test go_test( name = "go_default_xtest", srcs = ["bar_test.go"], deps = [":go_default_library"], importpath = "github.com/example/project/foo", )
go_binary rule like the one below.go_binary( name = "foo", srcs = ["main.go"], deps = [":go_default_library"], importpath = "github.com/example/project/foo", )
You can build binaries in static linking mode using
bazel build --output_groups=static //:my_binary
You can depend on static binaries (e.g., for packaging) using filegroup:
go_binary( name = "foo", srcs = ["foo.go"], ) filegroup( name = "foo_static", srcs = [":foo"], output_group = "static", )
You can run tests with the race detector enabled using
bazel test --features=race //...
You can build binaries with the race detector enabled using
bazel build --output_groups=race //...
The difference is necessary because the rules for binaries can produce both race and non-race versions, but tools used during the build should always be built in the non-race configuration. --output_groups is needed to select the configuration of the final binary only. For tests, only one executable can be tested, and --features is needed to select the race configuration.
go tool?Yes, this setup was deliberately chosen to be compatible with go build. Make sure your project appears in GOPATH, and it should work.
Note that go build won't be aware of dependencies listed in WORKSPACE, so these will be downloaded into GOPATH. You may also need to check in generated files.
go_default_library name?This was used to keep import paths consistent in libraries that can be built with go build before the importpath attribute was available.
In order to compile and link correctly, the Go rules need to be able to translate Bazel labels to Go import paths. Libraries that don't set the importpath attribute explicitly have an implicit dependency on //:go_prefix, a special rule that specifies an import path prefix. The import path is the prefix concatenated with the Bazel package and target name. For example, if your prefix was github.com/example/project, and your library was //foo/bar:bar, the Go rules would decide the import path was github.com/example/project/foo/bar/bar. The stutter at the end is incompatible with go build, so if the label name is go_default_library, the import path is just the prefix concatenated with the package name. So if your library is //foo/bar:go_default_library, the import path is github.com/example/project/foo/bar.
We are working on deprecating go_prefix and making importpath mandatory (see #721). When this work is complete, the go_default_library name won't be needed. We may decide to stop using this name in the future (see #265).
go_rules_dependenciesgo_rules_dependencies()
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. When nested workspaces arrive this will be redundant.
go_register_toolchainsgo_register_toolchains(go_version)
Installs the Go toolchains. If go_version is specified, it sets the SDK version to use (for example, "1.8.2"). By default, the latest SDK will be used.
go_repositorygo_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.
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_repositoryDEPRECATED Use go_repository instead, which has the same functionality.
go_prefixgo_prefix(prefix)
DEPRECATED Set the importpath attribute on all rules instead of using go_prefix. See #721.
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_librarygo_library(name, srcs, deps, data, importpath, gc_goopts, cgo, cdeps, copts, clinkopts)
go_library builds a Go library from a set of source files that are all part of the same package.
go_library( name = "go_default_library", srcs = [ "foo.go", "bar.go", ], deps = [ "//tools:go_default_library", "@org_golang_x_utils//stuff:go_default_library", ], importpath = "github.com/example/project/foo", visibility = ["//visibility:public"], )
cgo_librarycgo_library(name, srcs, copts, clinkopts, cdeps, deps, data, gc_goopts)
DEPRECATED Use go_library with cgo = True instead.
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).
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_binarygo_binary(name, srcs, deps, data, importpath, library, cgo, cdeps, copts, clinkopts, 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 binary with bazel run, or you can build it with bazel build and run it directly.
go_testgo_test(name, srcs, deps, data, importpath, library, cgo, cdeps, copts, clinkopts, linkstamp, x_defs, gc_goopts, gc_linkopts, rundir)
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).
To run all tests in the workspace, and print output on failure (the equivalent of “go test ./...” from go_prefix in a GOPATH tree), run
bazel test --test_output=errors //...
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.
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_librarygo_proto_library(name, srcs, deps, has_services)
go_embed_datago_embed_data(name, src, srcs, out, package, var, flatten, string)
The foo_data rule below will generate a file named foo_data.go, which can be included in a library. Gazelle will find and add these files automatically.
load("@io_bazel_rules_go//go:def.bzl", "go_embed_data", "go_library") go_embed_data( name = "foo_data", src = "foo.txt", out = "foo_data.go", package = "foo", string = True, var = "Data", ) go_library( name = "go_default_library", srcs = ["foo_data.go"], )
The generated file will look like this:
// Generated by go_embed_data for //:foo_data. DO NOT EDIT. package foo var Data = "Contents of foo.txt"