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
The Go toolchain consists of three main layers: the SDK, the toolchain, and the context.
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 runninggo 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.
By default, all go_binary
, go_test
, etc. rules will use the first declared Go SDK. If you would like to build a target using a specific Go SDK version, first ensure that you have declared a Go SDK of that version using one of the above rules (go_download_sdk, go_host_sdk, go_local_sdk, go_wrap_sdk). Then you can specify the sdk version to build with when running a bazel build
by passing the flag --@io_bazel_rules_go//go/toolchain:sdk_version="version"
where "version"
is the SDK version you would like to build with, eg. "1.18.3"
. The SDK version can omit the patch, or include a prerelease part, eg. "1"
, "1.18"
, "1.18.0"
, and "1.19.0beta1"
are all valid values for sdk_version
. When go_host_sdk
is used, "version"
can be set to host
to refer to the host Go SDK. It can also be set remote
to match any non-host version.
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 workspace rules define the toolchains in a separate repository from the SDK. For example, if the SDK repository is @go_sdk, the toolchains will be defined in @go_sdk_toolchains. The @go_sdk_toolchains repository must be eagerly fetched in order to register the toolchain, but fetching the @go_sdk repository may be delayed until the toolchain is needed to build something. To activate lazily fetching the SDK, you must provide a version attribute to the workspace rule that defines the SDK (go_download_sdk, go_host_sdk, go_local_sdk, go_wrap_sdk, or go_register_toolchains). The value must match the actual version of the SDK; rules_go will validate this when the toolchain is used.
The toolchain itself should be considered opaque. You should only access its contents through 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.
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")
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")
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()
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"],
)
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 If |
ownload if one has not been de red with go_download_sdk or sion like is not set to |
clared.
t may also be o toolchain ``).
lts in this SDK being chosen. |
nogo |
label | None |
The nogo attribute refers to used for static analysis. The `` Go compiler when building packag |
nogo`` binary will be used alo es. |
nary ngside the |
experiments |
string_list | [] |
Go experiments to enable via `GO | EXPERIMENT`. |
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 | 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 | 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_sdkto determine the correct file na If version` is specified, the `toolchain resolution_ results |
or example 1.12.5 . If unsp ailable versions of Go from go ersionis specified but sd will list available versions me and SHA-256 sum. SDK will be fetched only when in this SDK being chosen. Othe |
ecified, lang.org, then ks`` is on golang.org
rwise it will be fetched unconditionally. |
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
idate). |
patches |
label_list | [] |
A list of files that are to be a implementation which doesn't sup patch command line tool if `patc | pplied to go sdk. By default, port fuzz match and binary pat h_tool` attribute is specified | it uses the Bazel-native patch ch, but Bazel will fall back to use . |
patch_strip |
int | 0 |
The number of leading slashes to | be stripped from the file nam | e in thepatches. |
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.18.1",
sdks = {
# NOTE: In most cases the whole sdks attribute is not needed.
# There are 2 "common" reasons you might want it:
#
# 1. You need to use an modified GO SDK, or an unsupported version
# (for example, a beta or release candidate)
#
# 2. You want to avoid the dependency on the index file for the
# SHA-256 checksums. In this case, You can get the expected
# filenames and checksums from https://go.dev/dl/
"linux_amd64": ("go1.18.1.linux-amd64.tar.gz", "b3b815f47ababac13810fc6021eb73d65478e0b2db4b09d348eefad9581a2334"),
"darwin_amd64": ("go1.18.1.darwin-amd64.tar.gz", "3703e9a0db1000f18c0c7b524f3d378aac71219b4715a6a4c5683eb639f41a4d"),
},
patch_strip = 1,
patches = [
"//patches:cgo_issue_fix.patch",
]
)
go_rules_dependencies()
go_register_toolchains()
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 |
version |
string | None |
The version of Go installed on t only when the build uses a Go to chosen. Otherwise it will be cre | he host. If specified, `go_hos olchain and `toolchain resolut ated unconditionally. | t_sdk will create its repository ion results in this SDK being |
experiments |
string_list | [] |
Go experiments to enable via `GO | EXPERIMENT`. |
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 |
|
n the go binary, the tools it |
version |
string | None |
The version of the Go SDK. If sp build uses a Go toolchain and `t Otherwise it will be created unc | ecified, go_local_sdk will c oolchain resolution`_ results onditionally. | reate its repository only when the in this SDK being chosen. |
experiments |
string_list | [] |
Go experiments to enable via `GO | EXPERIMENT`. |
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 | . 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. |
version |
string | None |
The version of the Go SDK. If sp build uses a Go toolchain and `t Otherwise it will be created unc | ecified, go_wrap_sdk will cr oolchain resolution`_ results onditionally. | eate its repository only when the in this SDK being chosen. |
experiments |
string_list | [] |
Go experiments to enable via `GO | EXPERIMENT`. |
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()
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). |
This collects the information needed to form and return a GoContext from a rule ctx. It uses the attributes and the toolchains.
def _my_rule_impl(ctx):
go = go_context(ctx)
...
Name | Type | Default value |
ctx |
ctx | mandatory value |
The Bazel ctx object for the cur | rent rule. |
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.
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``. |
``. 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 , `` |
CGO_ENABLED , and PATH``. |
tags |
list of string |
List of build tags used to filte | r source files. |
- Action generators
- Helpers
This emits actions to compile Go code into an archive. It supports embedding, cgo dependencies, coverage, and assembling and packing .s files.
It returns a GoArchive.
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 GoSource that should be com | piled into an archive. |
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 |
|
|
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 | . |
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. |
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. |
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
|
ng analyzed. For most rules, t s in a fields corresponding to the at . This includes esent, must be a list containi |
his should be e fields. tributes of ps 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() |
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 _stdlib_library_to_sourc 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 e(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 |