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.
Contents
The Go toolchain consists of three main layers, the sdk and the toolchain and the context.
At the bottom is the Go SDK. This is the same thing you would get if you go to the main Go website and download a binary distribution.
This is always bound to @go_sdk and can be referred to directly if needed, but in general
you should always access it through the toolchain.
The go_download_sdk, go_host_sdk and go_local_sdk family of rules are responsible for downloading these, and adding just enough of a build file to expose the contents to Bazel. It currently also builds the cross compiled standard libraries for specific combinations, although we hope to make that an on demand step in the future.
SDKs are specific to the host they are running on and the version of Go they want to use but not the target they compile for. The Go SDK is naturally cross compiling.
If you don't do anything special, the Go rules will download the most recent official SDK for your host. If you need a forked version of Go, want to control the version or just use the installed sdk then it is easy to do, you just need to make sure you have bound the go_sdk repository before you call go_register_toolchains.
This a wrapper over the sdk that provides enough extras to match, target and work on a specific platforms. It should be considered an opaque type, you only ever use it through the context.
Toolchains are declared using the go_toolchain macro.
Toolchains are pre-declared for all the known combinations of host and target, and the names are a predictable "<host>" for host toolchains and "<host>_cross_<target>" for cross compilation toolchains. So for instance if the rules_go repository is loaded with it's default name, the following toolchain labels (along with many others) will be available
@io_bazel_rules_go//go/toolchain:linux_amd64 @io_bazel_rules_go//go/toolchain:linux_amd64_cross_windows_amd64
The toolchains are not usable until you register them.
Normally you would just call go_register_toolchains from your WORKSPACE to register all the pre-declared toolchains, and allow normal selection logic to pick the right one.
It is fine to add more toolchains to the available set if you like. Because the normal toolchain matching mechanism prefers the first declared match, you can also override individual toolchains by declaring and registering toolchains with the same constraints before calling go_register_toolchains.
If you wish to have more control over the toolchains you can instead just make direct calls to register_toolchains with only the toolchains you wish to install. You can see an example of this in limiting the available toolchains.
This is the type you use if you are writing custom rules that need
If you are writing a new rule that wants to use the Go toolchain, you need to do a couple of things. First, you have to declare that you want to consume the toolchain on the rule declaration. The easiest way to do this is to use the go_rule wrapper, which adds in the toolchain and some hidden attributes that it consumes.
load("@io_bazel_rules_go//go:def.bzl", "go_context", "go_rule")
my_rule = go_rule(
_my_rule_impl,
attrs = {
...
},
)And then in the rule body, you need to get the toolchain itself and use it's action generators.
def _my_rule_impl(ctx):
go = go_context(ctx)This is an example of normal usage for the other examples to be compared against. This will download and use the latest Go SDK that was available when the version of rules_go you're using was released.
load("@io_bazel_rules_go//go:def.bzl", "go_rules_dependencies", "go_register_toolchains")
go_rules_dependencies()
go_register_toolchains()You can select the version of the Go SDK to use by specifying it when you call go_register_toolchains but you must use a value that matches a known toolchain.
load("@io_bazel_rules_go//go:def.bzl", "go_rules_dependencies", "go_register_toolchains")
go_rules_dependencies()
go_register_toolchains(go_version="1.7.5")The "host" version is a special toolchain that breaks the hermetic seal to use the host installed toolchain.
load("@io_bazel_rules_go//go:def.bzl", "go_rules_dependencies", "go_register_toolchains")
go_rules_dependencies()
go_register_toolchains(go_version="host")If you want to register your own toolchain that takes precedence over the pre-declared ones you can just add it and register it before the normal ones.
load("@io_bazel_rules_go//go:def.bzl", "go_rules_dependencies", "go_register_toolchains", "go_download_sdk")
go_download_sdk(name="my_linux_sdk", url="https://storage.googleapis.com/golang/go1.8.1.linux-amd64.tar.gz")
register_toolchains(
"@//:my_linux_toolchain",
)
go_rules_dependencies()
go_register_toolchains()go_toolchain(name="my_linux_toolchain", sdk="my_linux_sdk", target="linux_amd64")If you wanted to only allow your project to be compiled on mac at version 1.8.3, instead of calling go_register_toolchains you can put
load("@io_bazel_rules_go//go:def.bzl", "go_rules_dependencies")
go_rules_dependencies()
register_toolchains(
"@io_bazel_rules_go//go/toolchain:1.8.3_darwin_amd64",
)Installs the Go toolchains. If go_version is specified, it sets the
SDK version to use (for example, "1.8.2"). By default, the latest
SDK will be used.
| Name | Type | Default value |
| go_version | string | "1.9.2" |
| This specifies the Go version to select. It will match the version specification of the toochain which for normal sdk toolchains is also the string part of the binary distribution you want to use. You can also use it to select the "host" sdk toolchain, or a custom toolchain with a specialized version string. | ||
This downloads a Go SDK for use in toolchains.
| Name | Type | Default value |
| name | string | mandatory value |
A unique name for this sdk. This should almost always be go_sdk if you want the SDK
to be used by toolchains. |
||
| urls | string_list | official distributions |
A list of mirror urls to the binary distribution of a Go SDK. These must contain the {}
used to substitute the sdk filename being fetched (using .format.
It defaults to the official repository "https://storage.googleapis.com/golang/{}". |
||
| strip_prefix | string | "go" |
| A directory prefix to strip from the extracted files. | ||
| sdks | string_list_dict | mandatory value |
This consists of a set of mappings from the host platform tuple to a list of filename and sha256 for that file. The filename is combined the urls to produce the final download urls to use. As an example: go_download_sdk(
name = "go_sdk",
sdks = {
"linux_amd64": ("go1.8.1.linux-amd64.tar.gz",
"a579ab19d5237e263254f1eac5352efcf1d70b9dacadb6d6bb12b0911ede8994"),
"darwin_amd64": ("go1.8.1.darwin-amd64.tar.gz",
"25b026fe2f4de7c80b227f69588b06b93787f5b5f134fbf2d652926c08c04bcd"),
},
) |
||
This detects the host Go SDK for use in toolchains.
It first checks the GOROOT and then searches the PATH. You can achieve the same result by setting the version to "host" when registering toolchains to select the installed sdk so it should never be necessary to use this feature directly.
| Name | Type | Default value |
| name | string | mandatory value |
A unique name for this sdk. This should almost always be go_sdk if you want the SDK
to be used by toolchains. |
||
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 should almost always be go_sdk if you want the SDK
to be used by toolchains. |
||
| path | string | "" |
| The local path to a pre-installed Go SDK. The path must contain the go binary, the tools it invokes and the standard library sources. | ||
This adds a toolchain of type "@io_bazel_rules_go//go:toolchain".
| Name | Type | Default value |
| name | string | mandatory value |
| A unique name for the toolchain. You will need to use this name when registering the toolchain in the WORKSPACE. | ||
| target | string | mandatory value |
This specifies the target platform tuple for this toolchain. It should be in the form GOOS*_*GOARCH and is used for both names and constraint matching. |
||
| host | string | None |
| This is the host platform tuple. If it is not set, it defaults to the same as target. If it is set to a different value to target, then this is declaring a cross-compiling toolchain. | ||
| sdk | string | mandatory value |
| This is the name of the SDK to use for this toolchain. The SDK must have been registered using one of the go sdk rules. | ||
| constraints | label_list | [] |
| This list is added to the host and or target constraints when declaring the toolchains. It allows the declaration f additional constraints that must be matched for the toolchain to be automatically selected. | ||
| link_flags | string_list | [] |
| The link flags are directly exposed on the toolchain. They can be used to specify target specific flags that Go linking actions should apply when using this toolchain. | ||
| cgo_link_flags | string_list | [] |
| The cgo link flags are directly exposed on the toolchain. They can be used to specify target specific flags that c linking actions generated by cgo should apply when using this toolchain. | ||
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.
my_rule = go_rule(
_my_rule_impl,
attrs = {
...
},
)| Name | Type | Default value |
| ctx | ctx | mandatory value |
| The Bazel ctx object for the current rule. | ||
GoContext is never returned by a rule, instead you build one using go_context(ctx) in the top of any custom skylark 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 (see use) it exposes a number of fields and methods.
All methods take the GoContext as the only positional argument, all other arguments even if mandatory must be specified by name, to allow us to re-order and deprecate individual parameters over time.
- Action generators
- Helpers
| Name | Type |
| toolchain | GoToolchain |
| The underlying toolchain. This should be considered an opaque type subject to change. | |
| mode | Mode |
| Controls the compilation setup affecting things like enabling profilers and sanitizers. See compilation modes for more information about the allowed values. | |
| go | File |
| The main "go" binary used to run go sdk tools. | |
| root | string |
| The GOROOT value to use. | |
| stdlib | GoStdlib |
| The standard library and tools to use in this build mode. | |
| sdk_files | list of File |
| This is the full set of files exposed by the sdk. You should never need this, it is mainly used when compiling the standard library. | |
| sdk_tools | list of File |
| The set of tool binaries exposed by the sdk. You may need this as inputs to a rule that uses go tool | |
| actions | ctx.actions |
| The actions structure from the Bazel context, which has all the methods for building new bazel actions. | |
| exe_extension | String |
| The suffix to use for all executables in this build mode. Mostly used when generating the output filenames of binary 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. | |
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 from. | ||
| source | GoSource | mandatory value |
| The GoSource that should be compiled into an archive. | ||
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 from. | ||
| source | File | mandatory value |
A source code artifact to assemble.
This must be a .s file that contains code in the platform neutral go assembly language. |
||
| hdrs | File iterable | [] |
| The list of .h files that may be included by the source. | ||
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 and the output executable file.
| Name | Type | Default value |
| go | GoContext | mandatory value |
| This must be the same GoContext object you got this function from. | ||
| name | string | "" |
| The base name of the generated binaries. Required if executable is not given. | ||
| source | GoSource | mandatory value |
| The GoSource that should be compiled and linked. | ||
| gc_linkopts | string_list | [] |
| Go link options. | ||
| linkstamp | string | None |
| Optional link stamp. See link. | ||
| version_file | File | None |
| Version file used for link stamping. See link. | ||
| info_file | File | None |
| Info file used for link stamping. See link. | ||
| executable | File | None |
Optional output file to write. If not set, binary will generate an output
file name based on name, the target platform, and the link mode. |
||
The compile function adds an action that runs go tool compile on a set of source files
to produce an archive.
It does not return anything.
| Name | Type | Default value |
| go | GoContext | mandatory value |
| This must be the same GoContext object you got this function from. | ||
| sources | File iterable | mandatory value |
| An iterable of source code artifacts. These Must be pure .go files, no assembly or cgo is allowed. | ||
| importpath | string | "" |
The import path this package represents. This is passed to the -p flag. When the actual import
path is different than the source import path (i.e., when importmap is set in a
go_library rule), this should be the actual import path. |
||
| archives | GoArchive iterable | [] |
| An iterable of all directly imported libraries. The action will verify that all directly imported libraries were supplied, not allowing transitive dependencies to satisfy imports. It will not check that all supplied libraries were used though. | ||
| out_lib | File | mandatory value |
| The archive file that should be produced. | ||
| gc_goopts | string_list | [] |
| Additional flags to pass to the compiler. | ||
| testfilter | string | "off" |
Controls how files with a
|
||
| asmhdr | File | None |
| If provided, the compiler will write an assembly header to this file. | ||
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 from. | ||
| source | GoSource | mandatory value |
| The source object to process. Any source files in the object that have been marked as needing coverage will be processed and substiuted in the returned GoSource. | ||
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 from. | ||
| archive | GoArchive | mandatory value |
| The library to link. | ||
| executable | File | mandatory value |
| The binary to produce. | ||
| gc_linkopts | string_list | [] |
| Basic link options, these may be adjusted by the mode. | ||
| x_defs | map | {} |
| Link defines, including build stamping ones. | ||
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 from. | ||
| in_lib | File | mandatory value |
| The archive that should be copied and appended to. This must always be an archive in the common ar form (like that produced by the go compiler). | ||
| out_lib | File | mandatory value |
| The archive that should be produced. This will always be an archive in the common ar form (like that produced by the go compiler). | ||
| objects | File iterable | () |
| An iterable of object files to be added to the output archive file. | ||
| archives | list of File | [] |
| Additional archives whose objects will be appended to the output. These can be ar files in either common form or either the bsd or sysv variations. | ||
This creates a new args object, using the ctx.args method, and the populates it with the 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 from. | ||
This is the equivalent of ctx.actions.declare_file except 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 from. | ||
| path | string | "" |
| A path for this file, including the basename of the file. | ||
| ext | string | "" |
| The extension to use for the file. | ||
| name | string | "" |
| A name to use for this file. If path is not present, this becomes a prefix to the path. If this is not set, the current rule name is used in it's place. | ||
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 from. | ||
| attr | ctx.attr | mandatory value |
| The attributes of the rule being processed, in a normal rule implementation this would be ctx.attr. | ||
| library | GoLibrary | mandatory value |
| The GoLibrary that you want to build a GoSource object for in the current build mode. | ||
| coverage_instrumented | bool | mandatory value |
| This controls whether cover is enabled for this specific library in this mode. This should generally be the value of ctx.coverage_instrumented() | ||
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 from. | ||
| resolver | function | None |
This is the function that gets invoked when converting from a GoLibrary to a GoSource. The function's signature must be def _testmain_library_to_source(go, attr, source, merge)attr is the attributes of the rule being processed source is the dictionary of GoSource fields being generated merge is a helper you can call to merge |
||
| importable | bool | mandatory value |
| This controls whether the GoLibrary is supposed to be importable. This is generally only false for the "main" libraries that are built just before linking. | ||