Go toolchains

The Go toolchain is at the heart of the Go rules, and is the mechanism used to customize the behavior of the core Go rules.

depth: 2

Overview

The Go toolchain consists of three main layers: the SDK, the toolchain, and the context.

The SDK

The Go SDK (more commonly known as the Go distribution) is a directory tree containing sources for the Go toolchain and standard library and pre-compiled binaries for the same. You can download this from by visiting the Go website and downloading a binary distribution.

There are several Bazel rules for obtaining and configuring a Go SDK:

go_download_sdk: downloads a toolchain for a specific version of Go for a specific operating system and architecture.
go_host_sdk: uses the toolchain installed on the system where Bazel is run. The toolchain's location is specified with the GOROOT or by running go env GOROOT.
go_local_sdk: like go_host_sdk, but uses the toolchain in a specific directory on the host system.
go_wrap_sdk: configures a toolchain downloaded with another Bazel repository rule.

By default, if none of the above rules are used, the go_register_toolchains function creates a repository named @go_sdk using go_download_sdk, using a recent version of Go for the host operating system and architecture.

SDKs are specific to a host platform (e.g., linux_amd64) and a version of Go. They may target all platforms that Go supports. The Go SDK is naturally cross compiling.

The toolchain

The workspace rules above declare Bazel toolchains with go_toolchain implementations for each target platform that Go supports. Wrappers around the rules register these toolchains automatically. Bazel will select a registered toolchain automatically based on the execution and target platforms, specified with --host_platform and --platforms, respectively.

The toolchain itself should be considered opaque. You should only access its contents through the context.

The context

The context is the type you need if you are writing custom rules that need to be compatible with rules_go. It provides information about the SDK, the toolchain, and the standard library. It also provides a convenient way to declare mode-specific files, and to create actions for compiling, linking, and more.

Customizing

Normal usage

This is an example of normal usage for the other examples to be compared against. This will download and use a specific version of Go for the host platform.

# WORKSPACE

load("@io_bazel_rules_go//go:deps.bzl", "go_rules_dependencies", "go_register_toolchains")

go_rules_dependencies()

go_register_toolchains(version = "1.15.5")

Using the installed Go SDK

You can use the Go SDK that's installed on the system where Bazel is running. This may result in faster builds, since there's no need to download an SDK, but builds won't be reproducible across systems with different SDKs installed.

# WORKSPACE

load("@io_bazel_rules_go//go:deps.bzl", "go_rules_dependencies", "go_register_toolchains")

go_rules_dependencies()

go_register_toolchains(version = "host")

Registering a custom SDK

If you download the SDK through another repository rule, you can configure it with go_wrap_sdk. It must still be named go_sdk, but this is a temporary limitation that will be removed in the future.

# WORKSPACE

load("@io_bazel_rules_go//go:deps.bzl", "go_rules_dependencies", "go_register_toolchains", "go_wrap_sdk")

unknown_download_sdk(
    name = "go",
    ...,
)

go_wrap_sdk(
    name = "go_sdk",
    root_file = "@go//:README.md",
)

go_rules_dependencies()

go_register_toolchains()

Writing new Go rules

If you are writing a new Bazel rule that uses the Go toolchain, you need to do several things to ensure you have full access to the toolchain and common dependencies.

Declare a dependency on a toolchain of type @io_bazel_rules_go//go:toolchain. Bazel will select an appropriate, registered toolchain automatically.
Declare an implicit attribute named _go_context_data that defaults to @io_bazel_rules_go//:go_context_data. This target gathers configuration information and several common dependencies.
Use the go_context function to gain access to the context. This is your main interface to the Go toolchain.

load("@io_bazel_rules_go//go:def.bzl", "go_context")

def _my_rule_impl(ctx):
    go = go_context(ctx)
    ...

my_rule = rule(
    implementation = _my_rule_impl,
    attrs = {
        ...
        "_go_context_data": attr.label(
            default = "@io_bazel_rules_go//:go_context_data",
        ),
    },
    toolchains = ["@io_bazel_rules_go//go:toolchain"],
)

Rules and functions

go_register_toolchains

Installs the Go toolchains. If version is specified, it sets the SDK version to use (for example, "1.15.5").

Name	Type	Default value
`version`	string	mandatory value
Specifies the version of Go to d If a toolchain was already decla this parameter may not be set. Normally this is set to a Go ver set to `"host"`, which wi installed on the host system (fo	ownload if one has not been de red with go_download_sdk or sion like `"1.15.5"`. I ll cause rules_go to use the G und using `GOROOT` or ``PATH	clared. a similar rule, t may also be o toolchain ``).
`nogo`	label	`None`
The `nogo` attribute refers to used for static analysis. The `` Go compiler when building packag	a nogo rule that builds a bi nogo`` binary will be used alo es.	nary ngside the

go_download_sdk

This downloads a Go SDK for use in toolchains.

Name	Type	Default value
`name`	string	mandatory value
A unique name for this SDK. This you want the SDK to be used by t	should almost always be :valu oolchains.	e:go_sdk if
`goos`	string	`None`
The operating system the binarie By default, this is detected aut an unusual platform, or if you'r platform is different than the h	s in the SDK are intended to r omatically, but if you're buil e using remote execution and t ost, you may need to specify t	un on. ding on he execution his explictly.
`goarch`	string	`None`
The architecture the binaries in By default, this is detected aut an unusual platform, or if you'r platform is different than the h	the SDK are intended to run o omatically, but if you're buil e using remote execution and t ost, you may need to specify t	n. ding on he execution his explictly.
`version`	string	`latest Go version`
The version of Go to download, f `go_download_sdk` will list av pick the highest version. If `v unspecified,`go_download_sdk`` to determine the correct file na	or example `1.12.5`. If unsp ailable versions of Go from go ersion`is specified but`sd will list available versions me and SHA-256 sum.	ecified, lang.org, then ks`` is on golang.org
`urls`	string_list	`[https://dl.google.com/go/{}]`
A list of mirror urls to the bin used to substitute the sdk filen It defaults to the official repo This attribute is seldom used. I an alternative location (for exa	ary distribution of a Go SDK. ame being fetched (using .for sitory :value:"https://dl.goo t is only needed for downloadi mple, an internal mirror).	These must contain the {} mat`. gle.com/go/{}"`. ng Go from
`strip_prefix`	string	`"go"`
A directory prefix to strip from Used with `urls`.	the extracted files.
`sdks`	string_list_dict	`see description`
This consists of a set of mappin sha256 for that file. The filena urls to use. This option is seldom used. It i Go distribution (with a differen not supported by rules_go (for e	gs from the host platform tupl me is combined the :param:`url s only needed for downloading t SHA-256 sum) or a version of xample, a beta or release cand	e to a list of filename and s` to produce the final download a modified Go idate).

Example:

load(
    "@io_bazel_rules_go//go:deps.bzl",
    "go_download_sdk",
    "go_register_toolchains",
    "go_rules_dependencies",
)

go_download_sdk(
    name = "go_sdk",
    goos = "linux",
    goarch = "amd64",
    version = "1.12.5",
)

go_rules_dependencies()

go_register_toolchains()

go_host_sdk

This detects and configures the host Go SDK for use in toolchains.

If the GOROOT environment variable is set, the SDK in that directory is used. Otherwise, go env GOROOT is used.

Name	Type	Default value
`name`	string	mandatory value
A unique name for this SDK. This to be used by toolchains.	should almost always be :valu	e:go_sdk if you want the SDK

go_local_sdk

This prepares a local path to use as the Go SDK in toolchains.

Name	Type	Default value
`name`	string	mandatory value
A unique name for this SDK. This to be used by toolchains.	should almost always be :valu	e:go_sdk if you want the SDK
`path`	string	`""`
The local path to a pre-installe invokes and the standard library	d Go SDK. The path must contai sources.	n the go binary, the tools it

go_wrap_sdk

This configures an SDK that was downloaded or located with another repository rule.

Name	Type	Default value
`name`	string	mandatory value
A unique name for this SDK. This to be used by toolchains.	should almost always be :valu	e:go_sdk if you want the SDK
`root_file`	label	`None`
A Bazel label referencing a file determine the GOROOT for the SDK	in the root directory of the . This attribute and `root_fil	SDK. Used to es` cannot be both provided.
`root_files`	string_dict	`None`
A set of mappings from the host directory. This attribute and `r	platform to a Bazel label refe oot_file` cannot be both provi	rencing a file in the SDK's root ded.

Example:

load(
    "@io_bazel_rules_go//go:deps.bzl",
    "go_register_toolchains",
    "go_rules_dependencies",
    "go_wrap_sdk",
)

go_wrap_sdk(
    name = "go_sdk",
    root_file = "@other_repo//go:README.md",
)

go_rules_dependencies()

go_register_toolchains()

go_toolchain

This declares a toolchain that may be used with toolchain type "@io_bazel_rules_go//go:toolchain".

Normally, go_toolchain rules are declared and registered in repositories configured with go_download_sdk, go_host_sdk, go_local_sdk, or go_wrap_sdk. You usually won't need to declare these explicitly.

Name	Type	Default value
`name`	string	mandatory value
A unique name for the toolchain.
`goos`	string	mandatory value
The target operating system. Mus	t be a standard `GOOS` value	.
`goarch`	string	mandatory value
The target architecture. Must be	a standard `GOARCH` value.
`sdk`	label	mandatory value
The SDK this toolchain is based usually a go_sdk rule.	on. The target must provide `G	oSDK`_. This is
`link_flags`	string_list	`[]`
Flags passed to the Go external	linker.
`cgo_link_flags`	:type:string_list	`[]`
Flags passed to the external lin	ker (if it is used).

go_context

This collects the information needed to form and return a GoContext from a rule ctx. It uses the attributes and the toolchains. It can only be used in the implementation of a rule that has the go toolchain attached and the go context data as an attribute. To do this declare the rule using the go_rule wrapper.

def _my_rule_impl(ctx):
    go = go_context(ctx)
    ...

my_rule = go_rule(
    _my_rule_impl,
    attrs = {
        ...
    },
)

Name	Type	Default value
`ctx`	ctx	mandatory value
The Bazel ctx object for the cur	rent rule.

The context object

GoContext is never returned by a rule, instead you build one using go_context(ctx) in the top of any custom starlark rule that wants to interact with the go rules. It provides all the information needed to create go actions, and create or interact with the other go providers.

When you get a GoContext from a context it exposes a number of fields and methods.

All methods take the GoContext as the only positional argument. All other arguments must be passed as keyword arguments. This allows us to re-order and deprecate individual parameters over time.

Fields

Name	Type
`toolchain`	:type:ToolchainInfo
The underlying toolchain. This s	hould be considered an opaque type subject to change.
`sdk`	GoSDK
The SDK in use. This may be used	to access sources, packages, and tools.
`mode`	Mode
Controls the compilation setup a See compilation modes for mor	ffecting things like enabling profilers and sanitizers. e information about the allowed values.
`root`	string
Path of the effective GOROOT. If as `go.stdlib.root_file.dirname`go.sdk.root_file.dirname``.	`stdlib` is set, this is the same ``. Otherwise, this is the same as
`go`	File
The main "go" binary used to run	go sdk tools.
`stdlib`	GoStdLib
The standard library and tools t pre-compiled standard library th in a different directory for thi	o use in this build mode. This may be the at comes with the SDK, or it may be compiled s mode.
`actions`	ctx.actions
The actions structure from the B bazel actions.	azel context, which has all the methods for building new
`exe_extension`	string
The suffix to use for all execut filenames of binary rules.	ables in this build mode. Mostly used when generating the output
`shared_extension`	string
The suffix to use for shared lib generating output filenames of b	raries in this build mode. Mostly used when inary rules.
`crosstool`	list of File
The files you need to add to the	inputs of an action in order to use the cc toolchain.
`package_list`	File
A file that contains the package	list of the standard library.
`env`	dict of string to string
Environment variables to pass to `GOROOT`, `GOROOT_FINAL`, ``	actions. Includes `GOARCH`, `GOOS`, CGO_ENABLED`, and`PATH``.
`tags`	list of string
List of build tags used to filte	r source files.

Methods

Action generators
- archive
- asm
- binary
- compile
- cover
- link
- pack
Helpers

asm

The asm function adds an action that runs go tool asm on a source file to produce an object, and returns the File of that object.

Name	Type	Default value
`go`	GoContext	mandatory value
This must be the same GoContext	object you got this function f	rom.
`source`	File	mandatory value
A source code artifact to assemb This must be a `.s` file that	le. contains code in the platform	neutral go assembly language.
`hdrs`	File iterable	`[]`
The list of .h files that may be	included by the source.

binary

This emits actions to compile and link Go code into a binary. It supports embedding, cgo dependencies, coverage, and assembling and packing .s files.

It returns a tuple containing GoArchive, the output executable file, and a runfiles object.

Name	Type	Default value
`go`	GoContext	mandatory value
This must be the same GoContext	object you got this function f	rom.
`name`	string	`""`
The base name of the generated b	inaries. Required if :param:`e	xecutable` is not given.
`source`	GoSource	mandatory value
The GoSource that should be com	piled and linked.
`test_archives`	list GoArchiveData	`[]`
List of archives for libraries u	nder test. See link.
`gc_linkopts`	string_list	`[]`
Go link options.
`version_file`	File	`None`
Version file used for link stamp	ing. See link.
`info_file`	File	`None`
Info file used for link stamping	. See link.
`executable`	File	`None`
Optional output file to write. I file name based on `name`, the	f not set, `binary` will gen target platform, and the link	erate an output mode.

compile

The compile function adds an action that compiles a list of source files into a package archive (.a file).

It does not return anything.

Name	Type	Default value
`go`	GoContext	mandatory value
This must be the same GoContext	object you got this function f	rom.
`sources`	File iterable	mandatory value
An iterable of source code artif These must be pure .go files, no	acts. assembly or cgo is allowed.
`importpath`	string	`""`
The import path this package rep path is different than the sourc `go_library` rule), this shoul	resents. This is passed to the e import path (i.e., when ``im d be the actual import path.	-p flag. When the actual import portmap`` is set in a
`archives`	GoArchive iterable	`[]`
An iterable of all directly impo The action will verify that all transitive dependencies to satis used though.	rted libraries. directly imported libraries we fy imports. It will not check	re supplied, not allowing that all supplied libraries were
`out_lib`	File	mandatory value
The archive file that should be	produced.
`out_export`	File	`None`
File where extra information abo by nogo to store serialized fact be used to store export data (in	ut the package may be stored. s about definitions. In the fu stead of the .a file).	This is used ture, it may
`gc_goopts`	string_list	`[]`
Additional flags to pass to the	compiler.
`testfilter`	string	`"off"`
Controls how files with a `_tes `"off"`- files with and wit `"only"`- only files with a *`"exclude"`` - only files wit	t`suffix are filtered. hout a`_test`suffix are co`_test`suffix are compiled hout a`_test`` suffix are co	mpiled. . mpiled.
`asmhdr`	File	`None`
If provided, the compiler will w	rite an assembly header to thi	s file.

cover

The cover function adds an action that runs go tool cover on a set of source files to produce copies with cover instrumentation.

Returns a covered GoSource with the required source files process for coverage.

Note that this removes most comments, including cgo comments.

Name	Type	Default value
`go`	GoContext	mandatory value
This must be the same GoContext	object you got this function f	rom.
`source`	GoSource	mandatory value
The source object to process. An coverage will be processed and s	y source files in the object t ubstiuted in the returned GoSo	hat have been marked as needing urce.

link

The link function adds an action that runs go tool link on a library.

It does not return anything.

Name	Type	Default value
`go`	GoContext	mandatory value
This must be the same GoContext	object you got this function f	rom.
`archive`	GoArchive	mandatory value
The library to link.
`test_archives`	GoArchiveData list	`[]`
List of archives for libraries u if transitive dependencies of :p This is useful for linking exter archives.	nder test. These are excluded aram:archive have the same p nal test archives that depend	from linking ackage paths. internal test
`executable`	File	mandatory value
The binary to produce.
`gc_linkopts`	string_list	`[]`
Basic link options, these may be	adjusted by the `mode`	.
`version_file`	File	`None`
Version file used for link stamp	ing.
`info_file`	File	`None`
Info file used for link stamping	.

pack

The pack function adds an action that produces an archive from a base archive and a collection of additional object files.

It does not return anything.

Name	Type	Default value
`go`	GoContext	mandatory value
This must be the same GoContext	object you got this function f	rom.
`in_lib`	File	mandatory value
The archive that should be copie This must always be an archive i	d and appended to. n the common ar form (like tha	t produced by the go compiler).
`out_lib`	File	mandatory value
The archive that should be produ This will always be an archive i	ced. n the common ar form (like tha	t produced by the go compiler).
`objects`	File iterable	`()`
An iterable of object files to b	e added to the output archive	file.
`archives`	list of File	`[]`
Additional archives whose object These can be ar files in either	s will be appended to the outp common form or either the bsd	ut. or sysv variations.

args

This creates a new Args object, using the ctx.actions.args method. The object is pre-populated with standard arguments used by all the go toolchain builders.

Name	Type	Default value
`go`	GoContext	mandatory value
This must be the same GoContext	object you got this function f	rom.

declare_file

This is the equivalent of ctx.actions.declare_file. It uses the current build mode to make the filename unique between configurations.

Name	Type	Default value
`go`	GoContext	mandatory value
This must be the same GoContext	object you got this function f	rom.
`path`	string	`""`
A path for this file, including	the basename of the file.
`ext`	string	`""`
The extension to use for the fil	e.
`name`	string	`""`
A name to use for this file. If If this is not set, the current	path is not present, this beco rule name is used in it's plac	mes a prefix to the path. e.

library_to_source

This is used to build a GoSource object for a given GoLibrary in the current build mode.

Name	Type	Default value
`go`	GoContext	mandatory value
This must be the same GoContext	object you got this function f	rom.
`attr`	ctx.attr	mandatory value
The attributes of the target bei `ctx.attr`. Rules can also pas `library_to_source` looks for `go_library` and `go_binary` and so on. All fields are option argument at all), but if they ar allowed values as in `go_librar must be a list of`Targets; ` As an exception,deps`, if pr`Targets`or`GoArchives``.	ng analyzed. For most rules, t s in a `struct` with the sam fields corresponding to the at . This includes `srcs`, `de al (and may not be defined in e present, they must have the y` and `go_binary`. For exa gc_goopts` must be a list of esent, must be a list containi	his should be e fields. tributes of ps`,`embed`, the struct same types and mple,`srcs`` strings. ng either
`library`	GoLibrary	mandatory value
The GoLibrary that you want to	build a GoSource object for i	n the current build mode.
`coverage_instrumented`	bool	mandatory value
This controls whether cover is e This should generally be the val	nabled for this specific libra ue of ctx.coverage_instrumente	ry in this mode. d()

new_library

This creates a new GoLibrary. You can add extra fields to the go library by providing extra named parameters to this function, they will be visible to the resolver when it is invoked.

Name	Type	Default value
`go`	GoContext	mandatory value
This must be the same GoContext	object you got this function f	rom.
`resolver`	function	`None`
This is the function that gets i The function's signature must be def _testmain_library_to_sou attr is the attributes of the ru source is the dictionary of GoSo merge is a helper you can call t	nvoked when converting from a rce(go, attr, source, merge) le being processed urce fields being generated o merge	GoLibrary to a GoSource.
`importable`	bool	mandatory value
This controls whether the GoLibr for the "main" libraries that ar	ary is supposed to be importa e built just before linking.	ble. This is generally only false

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

toolchains.rst

toolchains.rst

Go toolchains

Overview

The SDK

The toolchain

The context

Customizing

Normal usage

Using the installed Go SDK

Registering a custom SDK

Writing new Go rules

Rules and functions

go_register_toolchains

go_download_sdk

go_host_sdk

go_local_sdk

go_wrap_sdk

go_toolchain

go_context

The context object

Fields

Methods

archive

asm

binary

compile

cover

link

pack

args

declare_file

library_to_source

new_library

Files

toolchains.rst

Latest commit

History

toolchains.rst

File metadata and controls

Go toolchains

Overview

The SDK

The toolchain

The context

Customizing

Normal usage

Using the installed Go SDK

Registering a custom SDK

Writing new Go rules

Rules and functions

go_register_toolchains

go_download_sdk

go_host_sdk

go_local_sdk

go_wrap_sdk

go_toolchain

go_context

The context object

Fields

Methods

archive

asm

binary

compile

cover

link

pack

args

declare_file

library_to_source

new_library