Skip to content

Latest commit

 

History

History
527 lines (467 loc) · 36.9 KB

core.rst

File metadata and controls

527 lines (467 loc) · 36.9 KB
Raw

Core go rules

These are the core go rules, required for basic operation. The intent is that theses rules are sufficient to match the capabilities of the normal go tools.

Contents

Design

Defines and stamping

In order to make it possible to provide build time information to go code without data files, we support the concept of stamping.

Stamping asks the linker to substitute the inital value of a global string variable with a new value. It only happens at link time, not compile, so it happens at the level of a go binary not a package. This means that changing a value results only in re-linking, not re-compilation and thus does not cause cascading changes.

You specify the values to substitute in the x_defs parameter to any of the go rules. This is a map of string to string, where the key is the name of the variable to substitute and the value is the value to use. If the key is not a fully qualified name, then the current package is used. These mappings are collected up across the entire transitive dependancies of a binary, and then applied, which means you can set a define on a library, and it will be applied in any binary that links in that library. You can also override a the value of any libraries stamping from the x_defs of the binary if needed.

Embedding

This is used for things like internal tests, where a library is recompiled with additional sources and also code generators where the generated source will be known to have extra dependencies.

TODO: More information

API

go_library

This builds a Go library from a set of source files that are all part of the same package.

Providers

Attributes

Name Type Default value
name string mandatory value

A unique name for this rule.

To interoperated cleanly with gazelle right now this should be go_default_library.
importpath string ""
The import path of this library. If unspecified, the library will have an implicit dependency on //:go_prefix, and the import path will be derived from the prefix and the library's label.
srcs label_list None
The list of Go source files that are compiled to create the package. Only .go files are permitted, unless the cgo attribute is set, in which case the following file types are permitted: .go, .c, .s, .S .h. The files may contain Go-style build constraints.
x_defs string_dict {}
Map of defines to add to the go link command. See Defines and stamping for examples of how to use these.
deps label_list None
List of Go libraries this library imports directly. These may be go_library rules or compatible rules with the GoLibrary provider.
embed label_list None
List of Go libraries this test library directly. These may be go_library rules or compatible rules with the GoLibrary provider. These can provide both srcs and deps to this library. See Embedding for more information about how and when to use this.
data label_list None
The list of files needed by this rule at runtime. Targets named in the data attribute will appear in the *.runfiles area of this rule, if it has one. This may include data files needed by the binary, or other programs needed by it. See data dependencies for more information about how to depend on and use data files.
gc_goopts string_list []
List of flags to add to the Go compilation command when using the gc compiler. Subject to "Make variable" substitution and Bourne shell tokenization.
cgo boolean False
If True, the package uses cgo. The cgo tool permits Go code to call C code and vice-versa. This does not support calling C++. When cgo is set, srcs may contain C or assembly files; these files are compiled with the normal c compiler and included in the package.
cdeps label_list None
The list of other libraries that the c code depends on. This can be anything that would be allowed in cc library deps Only valid if cgo = True.
copts string_list []
List of flags to add to the C compilation command. Subject to "Make variable" substitution and Bourne shell tokenization. Only valid if cgo = True.
clinkopts string_list []
List of flags to add to the C link command. Subject to "Make variable" substitution and Bourne shell tokenization. Only valid if cgo = True.

Example

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_binary

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

Providers

Attributes

Name Type Default value
name string mandatory value

A unique name for this rule.

This should be named the same as the desired name of the generated binary .
importpath string ""
The import path of this binary. If unspecified, the binary will have an implicit dependency on //:go_prefix, and the import path will be derived from the prefix and the binary's label.
srcs label_list None
The list of Go source files that are compiled to create the binary. Only .go files are permitted, unless the cgo attribute is set, in which case the following file types are permitted: .go, .c, .s, .S .h. The files may contain Go-style build constraints.
deps label_list None
List of Go libraries this binary imports directly. These may be go_library rules or compatible rules with the GoLibrary provider.
embed label_list None
List of Go libraries this binary embeds directly. These may be go_library rules or compatible rules with the GoLibrary provider. These can provide both srcs and deps to this binary. See Embedding for more information about how and when to use this.
data label_list None
The list of files needed by this rule at runtime. Targets named in the data attribute will appear in the *.runfiles area of this rule, if it has one. This may include data files needed by the binary, or other programs needed by it. See data dependencies for more information about how to depend on and use data files.
pure string auto
This is one of the mode attributes that controls whether to link in pure mode. It should be one of on, off or auto.
static string auto
This is one of the mode attributes that controls whether to link in static mode. It should be one of on, off or auto.
goos string auto

This is one of the mode attributes that controls which goos to compile and link for.

If set to anything other than auto this overrideds the default as set by the current target platform, and allows for single builds to make binaries for multiple architectures.

Because this has no control over the cc toolchain, it does not work for cgo, so if this attribute is set then pure must be set to on.
goarch string auto

This is one of the mode attributes that controls which goarch to compile and link for.

If set to anything other than auto this overrideds the default as set by the current target platform, and allows for single builds to make binaries for multiple architectures.

Because this has no control over the cc toolchain, it does not work for cgo, so if this attribute is set then pure must be set to on.
gc_goopts string_list []
List of flags to add to the Go compilation command when using the gc compiler. Subject to "Make variable" substitution and Bourne shell tokenization.
gc_linkopts string_list []
List of flags to add to the Go link command when using the gc compiler. Subject to "Make variable" substitution and Bourne shell tokenization.
x_defs string_dict {}
Map of defines to add to the go link command. See Defines and stamping for examples of how to use these.
cgo boolean False
If True, the binary uses cgo. The cgo tool permits Go code to call C code and vice-versa. This does not support calling C++. When cgo is set, srcs may contain C or assembly files; these files are compiled with the normal c compiler and included in the package.
cdeps label_list None
The list of other libraries that the c code depends on. This can be anything that would be allowed in cc library deps Only valid if cgo = True.
copts string_list []
List of flags to add to the C compilation command. Subject to "Make variable" substitution and Bourne shell tokenization. Only valid if cgo = True.
clinkopts string_list []
List of flags to add to the C link command. Subject to "Make variable" substitution and Bourne shell tokenization. Only valid if cgo = True.

go_test

This builds a set of tests that can be run with bazel test.

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.

Attributes

Name Type Default value
name string mandatory value

A unique name for this rule.

To interoperated cleanly with gazelle right now this should be go_default_test for internal tests and go_default_xtest for external tests.
importpath string ""
The import path of this test. If unspecified, the test will have an implicit dependency on //:go_prefix, and the import path will be derived from the prefix and the test's label.
srcs label_list None
The list of Go source files that are compiled to create the test. Only .go files are permitted, unless the cgo attribute is set, in which case the following file types are permitted: .go, .c, .s, .S .h. The files may contain Go-style build constraints.
deps label_list None
List of Go libraries this test imports directly. These may be go_library rules or compatible rules with the GoLibrary provider.
embed label_list None
List of Go libraries this test embeds directly. These may be go_library rules or compatible rules with the GoLibrary provider. These can provide both srcs and deps to this test. See Embedding for more information about how and when to use this.
data label_list None
The list of files needed by this rule at runtime. Targets named in the data attribute will appear in the *.runfiles area of this rule, if it has one. This may include data files needed by the binary, or other programs needed by it. See data dependencies for more information about how to depend on and use data files.
gc_goopts string_list []
List of flags to add to the Go compilation command when using the gc compiler. Subject to "Make variable" substitution and Bourne shell tokenization.
gc_linkopts string_list []
List of flags to add to the Go link command when using the gc compiler. Subject to "Make variable" substitution and Bourne shell tokenization.
x_defs string_dict {}
Map of defines to add to the go link command. See Defines and stamping for examples of how to use these.
cgo boolean False
If True, the binary uses cgo. The cgo tool permits Go code to call C code and vice-versa. This does not support calling C++. When cgo is set, srcs may contain C or assembly files; these files are compiled with the normal c compiler and included in the package.
cdeps label_list None
The list of other libraries that the c code depends on. This can be anything that would be allowed in cc library deps Only valid if cgo = True.
copts string_list []
List of flags to add to the C compilation command. Subject to "Make variable" substitution and Bourne shell tokenization. Only valid if cgo = True.
clinkopts string_list []
List of flags to add to the C link command. Subject to "Make variable" substitution and Bourne shell tokenization. Only valid if cgo = True.
rundir string The package path

A directory to cd to before the test is run. This should be a path relative to the execution dir of the test.

The default behaviour is to change to the workspace relative path, this replicates the normal behaviour of go test so it is easy to write compatible tests.

Setting it to . makes the test behave the normal way for a bazel test.

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

Internal test example

This builds a test that can use the internal interface of the package being tested.

In the normal go toolchain this would be the kind of tests formed by adding writing <file>_test.go files in the same package.

It references the library being tested with embed.

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

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

External test example

This builds a test that can only use the public interface(s) of the packages being tested.

In the normal go toolchain this would be the kind of tests formed by adding an <name>_test package.

It references the library(s) being tested with deps.

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_source

This declares a set of source files and related dependencies that can be embedded into one of the other rules. This is used as a way of easily declaring a common set of sources re-used in multiple rules.

Providers

Attributes

Name Type Default value
name string mandatory value
A unique name for this rule.
srcs label_list None
The list of Go source files that are compiled to create the package. The following file types are permitted: .go, .c, .s, .S .h. The files may contain Go-style build constraints.
deps label_list None
List of Go libraries this source list imports directly. These may be go_library rules or compatible rules with the GoLibrary provider.
embed label_list None
List of sources to directly embed in this list. These may be go_library rules or compatible rules with the GoSource provider. These can provide both srcs and deps to this library. See Embedding for more information about how and when to use this.
data label_list None
The list of files needed by this rule at runtime. Targets named in the data attribute will appear in the *.runfiles area of this rule, if it has one. This may include data files needed by the binary, or other programs needed by it. See data dependencies for more information about how to depend on and use data files.
gc_goopts string_list []
List of flags to add to the Go compilation command when using the gc compiler. Subject to "Make variable" substitution and Bourne shell tokenization.