modes.rst

Build modes

depth

2

Overview

The Go toolchain can be configured to build targets in different modes using Bazel build settings specified on the command line or by using attributes specified on individual go_binary or go_test targets. For example, tests may be run in race mode with the command line flag --@io_bazel_rules_go//go/config:race or by setting race = "on" on the individual test targets.

Similarly, the Go toolchain can be made to cross-compile binaries for a specific platform by setting the --platforms command line flag or by setting the goos and goarch attributes of the binary target. For example, a binary could be built for linux / arm64 using the command line flag --platforms=@io_bazel_rules_go//go/toolchain:linux_arm64 or by setting goos = "linux" and goarch = "arm64".

Build settings

The build settings below are defined in the package @io_bazel_rules_go//go/config. They can all be set on the command line or using Bazel configuration transitions.

Name	Type	Default value
static	bool	false
Statically links th standard library an Works best with ``p	e target binary. d other C depende ure`` set as well	May not always work since parts of the ncies won't tolerate static linking. .
race	bool	false
Instruments the bin race is detected. R	ary for race dete equires cgo. Mutu	ction. Programs will panic when a data ally exclusive with msan.
msan	bool	false
Instruments the bin exclusive with ``ra	ary for memory sa ce``.	nitization. Requires cgo. Mutually
pure	bool	false
Disables cgo, even CGO_ENABLED=0). the cgo code will b Sets the de-facto ` files.	when a C/C++ tool Packages that co e filtered out, a purego` build t	chain is configured (similar to setting ntain cgo code may still be built, but nd the cgo build tag will be false. ag for conditional inclusion of source
debug	bool	false
Includes debugging -l flags). This	information in co is always true w	mpiled packages (using the -N and ith -c dbg.
gotags	:type:`string_li	st` | []
Controls which buil source files. Usefu	d tags are enable l for conditional	d when evaluating build constraints in compilation.
linkmode	string	"normal"
Determines how the Must be one of "n"c-shared","	Go binary is buil ormal","shar c-archive"``.	t and linked. Similar to -buildmode. ed","pie","plugin"``,

Platforms

You can define a Bazel platform using the native platform rule. A platform is essentially a list of facts (constraint values) about a target platform. rules_go defines a platform for each configuration the Go toolchain supports in @io_bazel_rules_go//go/toolchain. There are also config_setting targets in @io_bazel_rules_go//go/platform that can be used to pick platform-specific sources or dependencies using select.

You can specify a target platform using the --platforms command line flag. Bazel will automatically select a registered toolchain compatible with the target platform (rules_go registers toolchains for all supported platforms). For example, you could build for Linux / arm64 with the flag --platforms=@io_bazel_rules_go//go/toolchain:linux_arm64.

You can set the goos and goarch attributes on an individual go_binary or go_test rule to build a binary for a specific platform. This sets the --platforms flag via Bazel configuration transitions.

Examples

Building pure go binaries

You can switch the default binaries to non cgo using

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

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 --@io_bazel_rules_go//go/config:race //...

Alternatively, you can activate race detection for specific tests.

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

)