Contents
There are a few modes in which the core go rules can be run, and the selection mechanism depends on the nature of the variation.
Build modes can be selected either on the command line, or controlled on the go_binary and go_test rules using mode attributes.
The command line sets defaults that affect all rules, but explicit settings on a rule always override the command line. Not all build modes can be controlled in both places.
On the command line, there are a few mechanisms that influence the build mode.
| --features | Controls race, static, msan and pure, see features |
| --cpu | Controls GOOS_ GOARCH_, also forces pure for cross compilation |
| --compilation_mode | Controls debug and strip |
| --strip | Controls strip |
Features are normally off, unless you select them with --features=featurename on the bazel
command line. Features are generic tags that affect all rules, not just the ones you specify or
even just the go ones, and any feature can be interpreted by any rule. There is also no protections
that two different rules will not intepret the same feature in very different ways, and no way for
rule authors to protect against that, so it is up to the user when specifying a feature on the
command line to know what it's affects will be on all the rules in their build.
Available features that affect the go rules are:
Only rules that link accept build mode controlling attributes (go_binary and go_test, not go_library). The entire transitive set of libraries that a leaf depends on are built in the mode specified by the binary rule. The compiled libraries are distinct and multiple modes can be built in a single pass, but are shared between leaves building in the same mode.
Currently only static and pure can be specified as attributes. Both of these can take one of the values "on", "off" or "auto", and "auto" is the default.
| on | Forces the feature to be turned on for this binary. |
| off | This forces the feature to be turned off for the binary even if it is enabled on the command line. |
| auto | The default, it means obey whatever the command line suggests. |
The build mode structure is handed to all low level go build action. It has the following fields that control the bevhaviour of those actions:
The following is a description of the build modes. Not all build modes are truly independant, but most combinations are valid.
Causes any cgo code to be statically linked in to the go binary.
Causes the binary to be built with race detection enabled. Most often used when running tests.
Causes go code to be built with support for the clang memory sanitizer.
Compiles go code with CGO_ENABLED=0. Mostly often used to force go code to not
link against libc.
Controls the linking mode, must be one of
| normal | This is the default, builds executables. |
| shared | Links to a shared go library. |
| c-shared | Links to a shared c library. |
| pie | Links a position independent executables |
| plugin | Links to a go plugin. |
This compiles with full support for debugging, specifically it compiles with optimizations disabled and inlining off.
Causes debugging information to be stripped from the binaries.
You can switch the default binaries to non cgo using
bazel build --features=pure //:my_binaryYou can build pure go binaries by setting those attributes on a binary.
go_binary(
name = "foo",
srcs = ["foo.go"],
pure = "on",
)You can switch the default binaries to statically linked binaries using
bazel build --features=static //:my_binaryYou can build static go binaries by setting those attributes on a binary. If you want it to be fully static (no libc), you should also specify pure.
go_binary(
name = "foo",
srcs = ["foo.go"],
static = "on",
)You can switch the default binaries to race detection mode, and thus also switch the mode of tests by using
bazel test --features=race //...