Skip to content

Latest commit

 

History

History
230 lines (159 loc) · 6.98 KB

modes.rst

File metadata and controls

230 lines (159 loc) · 6.98 KB
Raw

Build modes

Contents

Overview

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.

Command line

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

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:

Mode attributes

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, pure, goos and goarch 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 mode structure

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:

Build modes

The following is a description of the build modes. Not all build modes are truly independent, but most combinations are valid.

static

Causes any cgo code to be statically linked in to the go binary.

race

Causes the binary to be built with race detection enabled. Most often used when running tests.

msan

Causes go code to be built with support for the clang memory sanitizer.

pure

Compiles go code with CGO_ENABLED=0. Mostly often used to force go code to not link against libc.

link

This is not yet working, and there is no mechaism to actually control the link mode,
so it is always the default value of "normal"

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.

debug

This compiles with full support for debugging, specifically it compiles with optimizations disabled and inlining off.

strip

Causes debugging information to be stripped from the binaries.

goos

This controls which operating system to target.

goarch

This controls which architecture to target.

Using build modes

Building pure go binaries

You can switch the default binaries to non cgo using

bazel build --features=pure //:my_binary

You can build pure go binaries by setting those attributes on a binary.

go_binary(
    name = "foo",
    srcs = ["foo.go"],
    pure = "on",
)

Building static binaries

Note that static linking does not work on darwin.

You can switch the default binaries to statically linked binaries using

bazel build --features=static //:my_binary

You 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",
)

Using the race detector

You can switch the default binaries to race detection mode, and thus also switch the mode of tests by using

bazel test --features=race //...

but in general it is strongly recommended instead to turn it on for specific tests.

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