github.com/bazelbuild/rules_go@v0.47.2-0.20240515105122-e7ddb9ea474e/go/toolchains.rst (about) 1 Go toolchains 2 ============= 3 4 .. _Args: https://docs.bazel.build/versions/master/skylark/lib/Args.html 5 .. _Bazel toolchains: https://docs.bazel.build/versions/master/toolchains.html 6 .. _Go website: https://golang.org/ 7 .. _GoArchive: providers.rst#goarchive 8 .. _GoLibrary: providers.rst#golibrary 9 .. _GoSDK: providers.rst#gosdk 10 .. _GoSource: providers.rst#gosource 11 .. _binary distribution: https://golang.org/dl/ 12 .. _compilation modes: modes.rst#compilation-modes 13 .. _control the version: `Forcing the Go version`_ 14 .. _core: core.bzl 15 .. _forked version of Go: `Registering a custom SDK`_ 16 .. _go assembly: https://golang.org/doc/asm 17 .. _go sdk rules: `The SDK`_ 18 .. _go/platform/list.bzl: platform/list.bzl 19 .. _installed SDK: `Using the installed Go sdk`_ 20 .. _nogo: nogo.rst#nogo 21 .. _register: Registration_ 22 .. _register_toolchains: https://docs.bazel.build/versions/master/skylark/lib/globals.html#register_toolchains 23 .. _toolchain resolution: https://bazel.build/extending/toolchains#toolchain-resolution 24 25 .. role:: param(kbd) 26 .. role:: type(emphasis) 27 .. role:: value(code) 28 .. |mandatory| replace:: **mandatory value** 29 30 The Go toolchain is at the heart of the Go rules, and is the mechanism used to 31 customize the behavior of the core_ Go rules. 32 33 .. contents:: :depth: 2 34 35 ----- 36 37 Overview 38 -------- 39 40 The Go toolchain consists of three main layers: `the SDK`_, `the toolchain`_, 41 and `the context`_. 42 43 The SDK 44 ~~~~~~~ 45 46 The Go SDK (more commonly known as the Go distribution) is a directory tree 47 containing sources for the Go toolchain and standard library and pre-compiled 48 binaries for the same. You can download this from by visiting the `Go website`_ 49 and downloading a `binary distribution`_. 50 51 There are several Bazel rules for obtaining and configuring a Go SDK: 52 53 * `go_download_sdk`_: downloads a toolchain for a specific version of Go for a 54 specific operating system and architecture. 55 * `go_host_sdk`_: uses the toolchain installed on the system where Bazel is 56 run. The toolchain's location is specified with the ``GOROOT`` or by running 57 ``go env GOROOT``. 58 * `go_local_sdk`_: like `go_host_sdk`_, but uses the toolchain in a specific 59 directory on the host system. 60 * `go_wrap_sdk`_: configures a toolchain downloaded with another Bazel 61 repository rule. 62 63 By default, if none of the above rules are used, the `go_register_toolchains`_ 64 function creates a repository named ``@go_sdk`` using `go_download_sdk`_, using 65 a recent version of Go for the host operating system and architecture. 66 67 SDKs are specific to a host platform (e.g., ``linux_amd64``) and a version of 68 Go. They may target all platforms that Go supports. The Go SDK is naturally 69 cross compiling. 70 71 By default, all ``go_binary``, ``go_test``, etc. rules will use the first declared 72 Go SDK. If you would like to build a target using a specific Go SDK version, first 73 ensure that you have declared a Go SDK of that version using one of the above rules 74 (`go_download_sdk`_, `go_host_sdk`_, `go_local_sdk`_, `go_wrap_sdk`_). Then you 75 can specify the sdk version to build with when running a ``bazel build`` by passing 76 the flag ``--@io_bazel_rules_go//go/toolchain:sdk_version="version"`` where 77 ``"version"`` is the SDK version you would like to build with, eg. ``"1.18.3"``. 78 The SDK version can omit the patch, or include a prerelease part, eg. ``"1"``, 79 ``"1.18"``, ``"1.18.0"``, and ``"1.19.0beta1"`` are all valid values for ``sdk_version``. 80 When ``go_host_sdk`` is used, ``"version"`` can be set to ``host`` to refer to the host Go SDK. 81 It can also be set ``remote`` to match any non-host version. 82 83 The toolchain 84 ~~~~~~~~~~~~~ 85 86 The workspace rules above declare `Bazel toolchains`_ with `go_toolchain`_ 87 implementations for each target platform that Go supports. Wrappers around 88 the rules register these toolchains automatically. Bazel will select a 89 registered toolchain automatically based on the execution and target platforms, 90 specified with ``--host_platform`` and ``--platforms``, respectively. 91 92 The workspace rules define the toolchains in a separate repository from the 93 SDK. For example, if the SDK repository is `@go_sdk`, the toolchains will be 94 defined in `@go_sdk_toolchains`. The `@go_sdk_toolchains` repository must be 95 eagerly fetched in order to register the toolchain, but fetching the `@go_sdk` 96 repository may be delayed until the toolchain is needed to build something. To 97 activate lazily fetching the SDK, you must provide a `version` attribute to the 98 workspace rule that defines the SDK (`go_download_sdk`, `go_host_sdk`, `go_local_sdk`, 99 `go_wrap_sdk`, or `go_register_toolchains`). The value must match the actual 100 version of the SDK; rules_go will validate this when the toolchain is used. 101 102 The toolchain itself should be considered opaque. You should only access 103 its contents through `the context`_. 104 105 The context 106 ~~~~~~~~~~~ 107 108 The context is the type you need if you are writing custom rules that need 109 to be compatible with rules_go. It provides information about the SDK, the 110 toolchain, and the standard library. It also provides a convenient way to 111 declare mode-specific files, and to create actions for compiling, linking, 112 and more. 113 114 Customizing 115 ----------- 116 117 Normal usage 118 ~~~~~~~~~~~~ 119 120 This is an example of normal usage for the other examples to be compared 121 against. This will download and use a specific version of Go for the host 122 platform. 123 124 .. code:: bzl 125 126 # WORKSPACE 127 128 load("@io_bazel_rules_go//go:deps.bzl", "go_rules_dependencies", "go_register_toolchains") 129 130 go_rules_dependencies() 131 132 go_register_toolchains(version = "1.15.5") 133 134 135 Using the installed Go SDK 136 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 137 138 You can use the Go SDK that's installed on the system where Bazel is running. 139 This may result in faster builds, since there's no need to download an SDK, 140 but builds won't be reproducible across systems with different SDKs installed. 141 142 .. code:: bzl 143 144 # WORKSPACE 145 146 load("@io_bazel_rules_go//go:deps.bzl", "go_rules_dependencies", "go_register_toolchains") 147 148 go_rules_dependencies() 149 150 go_register_toolchains(version = "host") 151 152 153 Registering a custom SDK 154 ~~~~~~~~~~~~~~~~~~~~~~~~ 155 156 If you download the SDK through another repository rule, you can configure 157 it with ``go_wrap_sdk``. It must still be named ``go_sdk``, but this is a 158 temporary limitation that will be removed in the future. 159 160 .. code:: bzl 161 162 # WORKSPACE 163 164 load("@io_bazel_rules_go//go:deps.bzl", "go_rules_dependencies", "go_register_toolchains", "go_wrap_sdk") 165 166 unknown_download_sdk( 167 name = "go", 168 ..., 169 ) 170 171 go_wrap_sdk( 172 name = "go_sdk", 173 root_file = "@go//:README.md", 174 ) 175 176 go_rules_dependencies() 177 178 go_register_toolchains() 179 180 181 Writing new Go rules 182 ~~~~~~~~~~~~~~~~~~~~ 183 184 If you are writing a new Bazel rule that uses the Go toolchain, you need to 185 do several things to ensure you have full access to the toolchain and common 186 dependencies. 187 188 * Declare a dependency on a toolchain of type 189 ``@io_bazel_rules_go//go:toolchain``. Bazel will select an appropriate, 190 registered toolchain automatically. 191 * Declare an implicit attribute named ``_go_context_data`` that defaults to 192 ``@io_bazel_rules_go//:go_context_data``. This target gathers configuration 193 information and several common dependencies. 194 * Use the ``go_context`` function to gain access to `the context`_. This is 195 your main interface to the Go toolchain. 196 197 .. code:: bzl 198 199 load("@io_bazel_rules_go//go:def.bzl", "go_context") 200 201 def _my_rule_impl(ctx): 202 go = go_context(ctx) 203 ... 204 205 my_rule = rule( 206 implementation = _my_rule_impl, 207 attrs = { 208 ... 209 "_go_context_data": attr.label( 210 default = "@io_bazel_rules_go//:go_context_data", 211 ), 212 }, 213 toolchains = ["@io_bazel_rules_go//go:toolchain"], 214 ) 215 216 217 Rules and functions 218 ------------------- 219 220 go_register_toolchains 221 ~~~~~~~~~~~~~~~~~~~~~~ 222 223 Installs the Go toolchains. If :param:`version` is specified, it sets the 224 SDK version to use (for example, :value:`"1.15.5"`). 225 226 +--------------------------------+-----------------------------+-----------------------------------+ 227 | **Name** | **Type** | **Default value** | 228 +--------------------------------+-----------------------------+-----------------------------------+ 229 | :param:`version` | :type:`string` | |mandatory| | 230 +--------------------------------+-----------------------------+-----------------------------------+ 231 | Specifies the version of Go to download if one has not been declared. | 232 | | 233 | If a toolchain was already declared with `go_download_sdk`_ or a similar rule, | 234 | this parameter may not be set. | 235 | | 236 | Normally this is set to a Go version like :value:`"1.15.5"`. It may also be | 237 | set to :value:`"host"`, which will cause rules_go to use the Go toolchain | 238 | installed on the host system (found using ``GOROOT`` or ``PATH``). | 239 | | 240 | If ``version`` is specified and is not set to :value:`"host"`, the SDK will be fetched only when | 241 | the build uses a Go toolchain and `toolchain resolution`_ results in this SDK being chosen. | 242 | Otherwise it will be fetched unconditionally. | 243 +--------------------------------+-----------------------------+-----------------------------------+ 244 | :param:`nogo` | :type:`label` | :value:`None` | 245 +--------------------------------+-----------------------------+-----------------------------------+ 246 | The ``nogo`` attribute refers to a nogo_ rule that builds a binary | 247 | used for static analysis. The ``nogo`` binary will be used alongside the | 248 | Go compiler when building packages. | 249 +--------------------------------+-----------------------------+-----------------------------------+ 250 | :param:`experiments` | :type:`string_list` | :value:`[]` | 251 +--------------------------------+-----------------------------+-----------------------------------+ 252 | Go experiments to enable via `GOEXPERIMENT`. | 253 +--------------------------------+-----------------------------+-----------------------------------+ 254 255 go_download_sdk 256 ~~~~~~~~~~~~~~~ 257 258 This downloads a Go SDK for use in toolchains. 259 260 +--------------------------------+-----------------------------+---------------------------------------------+ 261 | **Name** | **Type** | **Default value** | 262 +--------------------------------+-----------------------------+---------------------------------------------+ 263 | :param:`name` | :type:`string` | |mandatory| | 264 +--------------------------------+-----------------------------+---------------------------------------------+ 265 | A unique name for this SDK. This should almost always be :value:`go_sdk` if | 266 | you want the SDK to be used by toolchains. | 267 +--------------------------------+-----------------------------+---------------------------------------------+ 268 | :param:`goos` | :type:`string` | :value:`None` | 269 +--------------------------------+-----------------------------+---------------------------------------------+ 270 | The operating system the binaries in the SDK are intended to run on. | 271 | By default, this is detected automatically, but if you're building on | 272 | an unusual platform, or if you're using remote execution and the execution | 273 | platform is different than the host, you may need to specify this explictly. | 274 +--------------------------------+-----------------------------+---------------------------------------------+ 275 | :param:`goarch` | :type:`string` | :value:`None` | 276 +--------------------------------+-----------------------------+---------------------------------------------+ 277 | The architecture the binaries in the SDK are intended to run on. | 278 | By default, this is detected automatically, but if you're building on | 279 | an unusual platform, or if you're using remote execution and the execution | 280 | platform is different than the host, you may need to specify this explictly. | 281 +--------------------------------+-----------------------------+---------------------------------------------+ 282 | :param:`version` | :type:`string` | :value:`latest Go version` | 283 +--------------------------------+-----------------------------+---------------------------------------------+ 284 | The version of Go to download, for example ``1.12.5``. If unspecified, | 285 | ``go_download_sdk`` will list available versions of Go from golang.org, then | 286 | pick the highest version. If ``version`` is specified but ``sdks`` is | 287 | unspecified, ``go_download_sdk`` will list available versions on golang.org | 288 | to determine the correct file name and SHA-256 sum. | 289 | If ``version`` is specified, the SDK will be fetched only when the build uses a Go toolchain and | 290 | `toolchain resolution`_ results in this SDK being chosen. Otherwise it will be fetched unconditionally. | 291 +--------------------------------+-----------------------------+---------------------------------------------+ 292 | :param:`urls` | :type:`string_list` | :value:`[https://dl.google.com/go/{}]` | 293 +--------------------------------+-----------------------------+---------------------------------------------+ 294 | A list of mirror urls to the binary distribution of a Go SDK. These must contain the `{}` | 295 | used to substitute the sdk filename being fetched (using `.format`. | 296 | It defaults to the official repository :value:`"https://dl.google.com/go/{}"`. | 297 | | 298 | This attribute is seldom used. It is only needed for downloading Go from | 299 | an alternative location (for example, an internal mirror). | 300 +--------------------------------+-----------------------------+---------------------------------------------+ 301 | :param:`strip_prefix` | :type:`string` | :value:`"go"` | 302 +--------------------------------+-----------------------------+---------------------------------------------+ 303 | A directory prefix to strip from the extracted files. | 304 | Used with ``urls``. | 305 +--------------------------------+-----------------------------+---------------------------------------------+ 306 | :param:`sdks` | :type:`string_list_dict` | :value:`see description` | 307 +--------------------------------+-----------------------------+---------------------------------------------+ 308 | This consists of a set of mappings from the host platform tuple to a list of filename and | 309 | sha256 for that file. The filename is combined the :param:`urls` to produce the final download | 310 | urls to use. | 311 | | 312 | This option is seldom used. It is only needed for downloading a modified | 313 | Go distribution (with a different SHA-256 sum) or a version of Go | 314 | not supported by rules_go (for example, a beta or release candidate). | 315 +--------------------------------+-----------------------------+---------------------------------------------+ 316 | :param:`patches` | :type:`label_list` | :value:`[]` | 317 +--------------------------------+-----------------------------+---------------------------------------------+ 318 | A list of files that are to be applied to go sdk. By default, it uses the Bazel-native patch | 319 | implementation which doesn't support fuzz match and binary patch, but Bazel will fall back to use | 320 | patch command line tool if `patch_tool` attribute is specified. | 321 +--------------------------------+-----------------------------+---------------------------------------------+ 322 | :param:`patch_strip` | :type:`int` | :value:`0` | 323 +--------------------------------+-----------------------------+---------------------------------------------+ 324 | The number of leading slashes to be stripped from the file name in thepatches. | 325 +--------------------------------+-----------------------------+---------------------------------------------+ 326 327 **Example**: 328 329 .. code:: bzl 330 331 load( 332 "@io_bazel_rules_go//go:deps.bzl", 333 "go_download_sdk", 334 "go_register_toolchains", 335 "go_rules_dependencies", 336 ) 337 338 go_download_sdk( 339 name = "go_sdk", 340 goos = "linux", 341 goarch = "amd64", 342 version = "1.18.1", 343 sdks = { 344 # NOTE: In most cases the whole sdks attribute is not needed. 345 # There are 2 "common" reasons you might want it: 346 # 347 # 1. You need to use an modified GO SDK, or an unsupported version 348 # (for example, a beta or release candidate) 349 # 350 # 2. You want to avoid the dependency on the index file for the 351 # SHA-256 checksums. In this case, You can get the expected 352 # filenames and checksums from https://go.dev/dl/ 353 "linux_amd64": ("go1.18.1.linux-amd64.tar.gz", "b3b815f47ababac13810fc6021eb73d65478e0b2db4b09d348eefad9581a2334"), 354 "darwin_amd64": ("go1.18.1.darwin-amd64.tar.gz", "3703e9a0db1000f18c0c7b524f3d378aac71219b4715a6a4c5683eb639f41a4d"), 355 }, 356 patch_strip = 1, 357 patches = [ 358 "//patches:cgo_issue_fix.patch", 359 ] 360 ) 361 362 go_rules_dependencies() 363 364 go_register_toolchains() 365 366 go_host_sdk 367 ~~~~~~~~~~~ 368 369 This detects and configures the host Go SDK for use in toolchains. 370 371 If the ``GOROOT`` environment variable is set, the SDK in that directory is 372 used. Otherwise, ``go env GOROOT`` is used. 373 374 +--------------------------------+-----------------------------+-----------------------------------+ 375 | **Name** | **Type** | **Default value** | 376 +--------------------------------+-----------------------------+-----------------------------------+ 377 | :param:`name` | :type:`string` | |mandatory| | 378 +--------------------------------+-----------------------------+-----------------------------------+ 379 | A unique name for this SDK. This should almost always be :value:`go_sdk` if you want the SDK | 380 | to be used by toolchains. | 381 +--------------------------------+-----------------------------+-----------------------------------+ 382 | :param:`version` | :type:`string` | :value:`None` | 383 +--------------------------------+-----------------------------+-----------------------------------+ 384 | The version of Go installed on the host. If specified, `go_host_sdk` will create its repository | 385 | only when the build uses a Go toolchain and `toolchain resolution`_ results in this SDK being | 386 | chosen. Otherwise it will be created unconditionally. | 387 +--------------------------------+-----------------------------+-----------------------------------+ 388 | :param:`experiments` | :type:`string_list` | :value:`[]` | 389 +--------------------------------+-----------------------------+-----------------------------------+ 390 | Go experiments to enable via `GOEXPERIMENT`. | 391 +--------------------------------+-----------------------------+-----------------------------------+ 392 393 go_local_sdk 394 ~~~~~~~~~~~~ 395 396 This prepares a local path to use as the Go SDK in toolchains. 397 398 +--------------------------------+-----------------------------+-----------------------------------+ 399 | **Name** | **Type** | **Default value** | 400 +--------------------------------+-----------------------------+-----------------------------------+ 401 | :param:`name` | :type:`string` | |mandatory| | 402 +--------------------------------+-----------------------------+-----------------------------------+ 403 | A unique name for this SDK. This should almost always be :value:`go_sdk` if you want the SDK | 404 | to be used by toolchains. | 405 +--------------------------------+-----------------------------+-----------------------------------+ 406 | :param:`path` | :type:`string` | :value:`""` | 407 +--------------------------------+-----------------------------+-----------------------------------+ 408 | The local path to a pre-installed Go SDK. The path must contain the go binary, the tools it | 409 | invokes and the standard library sources. | 410 +--------------------------------+-----------------------------+-----------------------------------+ 411 | :param:`version` | :type:`string` | :value:`None` | 412 +--------------------------------+-----------------------------+-----------------------------------+ 413 | The version of the Go SDK. If specified, `go_local_sdk` will create its repository only when the | 414 | build uses a Go toolchain and `toolchain resolution`_ results in this SDK being chosen. | 415 | Otherwise it will be created unconditionally. | 416 +--------------------------------+-----------------------------+-----------------------------------+ 417 | :param:`experiments` | :type:`string_list` | :value:`[]` | 418 +--------------------------------+-----------------------------+-----------------------------------+ 419 | Go experiments to enable via `GOEXPERIMENT`. | 420 +--------------------------------+-----------------------------+-----------------------------------+ 421 422 423 go_wrap_sdk 424 ~~~~~~~~~~~ 425 426 This configures an SDK that was downloaded or located with another repository 427 rule. 428 429 +--------------------------------+-----------------------------+-----------------------------------+ 430 | **Name** | **Type** | **Default value** | 431 +--------------------------------+-----------------------------+-----------------------------------+ 432 | :param:`name` | :type:`string` | |mandatory| | 433 +--------------------------------+-----------------------------+-----------------------------------+ 434 | A unique name for this SDK. This should almost always be :value:`go_sdk` if you want the SDK | 435 | to be used by toolchains. | 436 +--------------------------------+-----------------------------+-----------------------------------+ 437 | :param:`root_file` | :type:`label` | :value:`None` | 438 +--------------------------------+-----------------------------+-----------------------------------+ 439 | A Bazel label referencing a file in the root directory of the SDK. Used to | 440 | determine the GOROOT for the SDK. This attribute and `root_files` cannot be both provided. | 441 +--------------------------------+-----------------------------+-----------------------------------+ 442 | :param:`root_files` | :type:`string_dict` | :value:`None` | 443 +--------------------------------+-----------------------------+-----------------------------------+ 444 | A set of mappings from the host platform to a Bazel label referencing a file in the SDK's root | 445 | directory. This attribute and `root_file` cannot be both provided. | 446 +--------------------------------+-----------------------------+-----------------------------------+ 447 | :param:`version` | :type:`string` | :value:`None` | 448 +--------------------------------+-----------------------------+-----------------------------------+ 449 | The version of the Go SDK. If specified, `go_wrap_sdk` will create its repository only when the | 450 | build uses a Go toolchain and `toolchain resolution`_ results in this SDK being chosen. | 451 | Otherwise it will be created unconditionally. | 452 +--------------------------------+-----------------------------+-----------------------------------+ 453 | :param:`experiments` | :type:`string_list` | :value:`[]` | 454 +--------------------------------+-----------------------------+-----------------------------------+ 455 | Go experiments to enable via `GOEXPERIMENT`. | 456 +--------------------------------+-----------------------------+-----------------------------------+ 457 458 459 **Example:** 460 461 .. code:: bzl 462 463 load( 464 "@io_bazel_rules_go//go:deps.bzl", 465 "go_register_toolchains", 466 "go_rules_dependencies", 467 "go_wrap_sdk", 468 ) 469 470 go_wrap_sdk( 471 name = "go_sdk", 472 root_file = "@other_repo//go:README.md", 473 ) 474 475 go_rules_dependencies() 476 477 go_register_toolchains() 478 479 go_toolchain 480 ~~~~~~~~~~~~ 481 482 This declares a toolchain that may be used with toolchain type 483 :value:`"@io_bazel_rules_go//go:toolchain"`. 484 485 Normally, ``go_toolchain`` rules are declared and registered in repositories 486 configured with `go_download_sdk`_, `go_host_sdk`_, `go_local_sdk`_, or 487 `go_wrap_sdk`_. You usually won't need to declare these explicitly. 488 489 +--------------------------------+-----------------------------+-----------------------------------+ 490 | **Name** | **Type** | **Default value** | 491 +--------------------------------+-----------------------------+-----------------------------------+ 492 | :param:`name` | :type:`string` | |mandatory| | 493 +--------------------------------+-----------------------------+-----------------------------------+ 494 | A unique name for the toolchain. | 495 +--------------------------------+-----------------------------+-----------------------------------+ 496 | :param:`goos` | :type:`string` | |mandatory| | 497 +--------------------------------+-----------------------------+-----------------------------------+ 498 | The target operating system. Must be a standard ``GOOS`` value. | 499 +--------------------------------+-----------------------------+-----------------------------------+ 500 | :param:`goarch` | :type:`string` | |mandatory| | 501 +--------------------------------+-----------------------------+-----------------------------------+ 502 | The target architecture. Must be a standard ``GOARCH`` value. | 503 +--------------------------------+-----------------------------+-----------------------------------+ 504 | :param:`sdk` | :type:`label` | |mandatory| | 505 +--------------------------------+-----------------------------+-----------------------------------+ 506 | The SDK this toolchain is based on. The target must provide `GoSDK`_. This is | 507 | usually a `go_sdk`_ rule. | 508 +--------------------------------+-----------------------------+-----------------------------------+ 509 | :param:`link_flags` | :type:`string_list` | :value:`[]` | 510 +--------------------------------+-----------------------------+-----------------------------------+ 511 | Flags passed to the Go external linker. | 512 +--------------------------------+-----------------------------+-----------------------------------+ 513 | :param:`cgo_link_flags` | :type:`string_list` | :value:`[]` | 514 +--------------------------------+-----------------------------+-----------------------------------+ 515 | Flags passed to the external linker (if it is used). | 516 +--------------------------------+-----------------------------+-----------------------------------+ 517 518 go_context 519 ~~~~~~~~~~ 520 521 This collects the information needed to form and return a :type:`GoContext` from 522 a rule ctx. It uses the attributes and the toolchains. 523 524 .. code:: bzl 525 526 def _my_rule_impl(ctx): 527 go = go_context(ctx) 528 ... 529 530 531 +--------------------------------+-----------------------------+-----------------------------------+ 532 | **Name** | **Type** | **Default value** | 533 +--------------------------------+-----------------------------+-----------------------------------+ 534 | :param:`ctx` | :type:`ctx` | |mandatory| | 535 +--------------------------------+-----------------------------+-----------------------------------+ 536 | The Bazel ctx object for the current rule. | 537 +--------------------------------+-----------------------------+-----------------------------------+ 538 539 The context object 540 ~~~~~~~~~~~~~~~~~~ 541 542 ``GoContext`` is never returned by a rule, instead you build one using 543 ``go_context(ctx)`` in the top of any custom starlark rule that wants to interact 544 with the go rules. It provides all the information needed to create go actions, 545 and create or interact with the other go providers. 546 547 When you get a ``GoContext`` from a context it exposes a number of fields 548 and methods. 549 550 All methods take the ``GoContext`` as the only positional argument. All other 551 arguments must be passed as keyword arguments. This allows us to re-order and 552 deprecate individual parameters over time. 553 554 Fields 555 ^^^^^^ 556 557 +--------------------------------+-----------------------------------------------------------------+ 558 | **Name** | **Type** | 559 +--------------------------------+-----------------------------------------------------------------+ 560 | :param:`toolchain` | :type:`ToolchainInfo` | 561 +--------------------------------+-----------------------------------------------------------------+ 562 | The underlying toolchain. This should be considered an opaque type subject to change. | 563 +--------------------------------+-----------------------------------------------------------------+ 564 | :param:`sdk` | :type:`GoSDK` | 565 +--------------------------------+-----------------------------------------------------------------+ 566 | The SDK in use. This may be used to access sources, packages, and tools. | 567 +--------------------------------+-----------------------------------------------------------------+ 568 | :param:`mode` | :type:`Mode` | 569 +--------------------------------+-----------------------------------------------------------------+ 570 | Controls the compilation setup affecting things like enabling profilers and sanitizers. | 571 | See `compilation modes`_ for more information about the allowed values. | 572 +--------------------------------+-----------------------------------------------------------------+ 573 | :param:`root` | :type:`string` | 574 +--------------------------------+-----------------------------------------------------------------+ 575 | Path of the effective GOROOT. If :param:`stdlib` is set, this is the same | 576 | as ``go.stdlib.root_file.dirname``. Otherwise, this is the same as | 577 | ``go.sdk.root_file.dirname``. | 578 +--------------------------------+-----------------------------------------------------------------+ 579 | :param:`go` | :type:`File` | 580 +--------------------------------+-----------------------------------------------------------------+ 581 | The main "go" binary used to run go sdk tools. | 582 +--------------------------------+-----------------------------------------------------------------+ 583 | :param:`stdlib` | :type:`GoStdLib` | 584 +--------------------------------+-----------------------------------------------------------------+ 585 | The standard library and tools to use in this build mode. This may be the | 586 | pre-compiled standard library that comes with the SDK, or it may be compiled | 587 | in a different directory for this mode. | 588 +--------------------------------+-----------------------------------------------------------------+ 589 | :param:`actions` | :type:`ctx.actions` | 590 +--------------------------------+-----------------------------------------------------------------+ 591 | The actions structure from the Bazel context, which has all the methods for building new | 592 | bazel actions. | 593 +--------------------------------+-----------------------------------------------------------------+ 594 | :param:`exe_extension` | :type:`string` | 595 +--------------------------------+-----------------------------------------------------------------+ 596 | The suffix to use for all executables in this build mode. Mostly used when generating the output | 597 | filenames of binary rules. | 598 +--------------------------------+-----------------------------------------------------------------+ 599 | :param:`shared_extension` | :type:`string` | 600 +--------------------------------+-----------------------------------------------------------------+ 601 | The suffix to use for shared libraries in this build mode. Mostly used when | 602 | generating output filenames of binary rules. | 603 +--------------------------------+-----------------------------------------------------------------+ 604 | :param:`crosstool` | :type:`list of File` | 605 +--------------------------------+-----------------------------------------------------------------+ 606 | The files you need to add to the inputs of an action in order to use the cc toolchain. | 607 +--------------------------------+-----------------------------------------------------------------+ 608 | :param:`package_list` | :type:`File` | 609 +--------------------------------+-----------------------------------------------------------------+ 610 | A file that contains the package list of the standard library. | 611 +--------------------------------+-----------------------------------------------------------------+ 612 | :param:`env` | :type:`dict of string to string` | 613 +--------------------------------+-----------------------------------------------------------------+ 614 | Environment variables to pass to actions. Includes ``GOARCH``, ``GOOS``, | 615 | ``GOROOT``, ``GOROOT_FINAL``, ``CGO_ENABLED``, and ``PATH``. | 616 +--------------------------------+-----------------------------------------------------------------+ 617 | :param:`tags` | :type:`list of string` | 618 +--------------------------------+-----------------------------------------------------------------+ 619 | List of build tags used to filter source files. | 620 +--------------------------------+-----------------------------------------------------------------+ 621 622 Methods 623 ^^^^^^^ 624 625 * Action generators 626 627 * archive_ 628 * binary_ 629 * link_ 630 631 * Helpers 632 633 * args_ 634 * `declare_file`_ 635 * `library_to_source`_ 636 * `new_library`_ 637 638 639 archive 640 +++++++ 641 642 This emits actions to compile Go code into an archive. It supports embedding, 643 cgo dependencies, coverage, and assembling and packing .s files. 644 645 It returns a GoArchive_. 646 647 +--------------------------------+-----------------------------+-----------------------------------+ 648 | **Name** | **Type** | **Default value** | 649 +--------------------------------+-----------------------------+-----------------------------------+ 650 | :param:`go` | :type:`GoContext` | |mandatory| | 651 +--------------------------------+-----------------------------+-----------------------------------+ 652 | This must be the same GoContext object you got this function from. | 653 +--------------------------------+-----------------------------+-----------------------------------+ 654 | :param:`source` | :type:`GoSource` | |mandatory| | 655 +--------------------------------+-----------------------------+-----------------------------------+ 656 | The GoSource_ that should be compiled into an archive. | 657 +--------------------------------+-----------------------------+-----------------------------------+ 658 659 660 binary 661 ++++++ 662 663 This emits actions to compile and link Go code into a binary. It supports 664 embedding, cgo dependencies, coverage, and assembling and packing .s files. 665 666 It returns a tuple containing GoArchive_, the output executable file, and 667 a ``runfiles`` object. 668 669 +--------------------------------+-----------------------------+-----------------------------------+ 670 | **Name** | **Type** | **Default value** | 671 +--------------------------------+-----------------------------+-----------------------------------+ 672 | :param:`go` | :type:`GoContext` | |mandatory| | 673 +--------------------------------+-----------------------------+-----------------------------------+ 674 | This must be the same GoContext object you got this function from. | 675 +--------------------------------+-----------------------------+-----------------------------------+ 676 | :param:`name` | :type:`string` | :value:`""` | 677 +--------------------------------+-----------------------------+-----------------------------------+ 678 | The base name of the generated binaries. Required if :param:`executable` is not given. | 679 +--------------------------------+-----------------------------+-----------------------------------+ 680 | :param:`source` | :type:`GoSource` | |mandatory| | 681 +--------------------------------+-----------------------------+-----------------------------------+ 682 | The GoSource_ that should be compiled and linked. | 683 +--------------------------------+-----------------------------+-----------------------------------+ 684 | :param:`test_archives` | :type:`list GoArchiveData` | :value:`[]` | 685 +--------------------------------+-----------------------------+-----------------------------------+ 686 | List of archives for libraries under test. See link_. | 687 +--------------------------------+-----------------------------+-----------------------------------+ 688 | :param:`gc_linkopts` | :type:`string_list` | :value:`[]` | 689 +--------------------------------+-----------------------------+-----------------------------------+ 690 | Go link options. | 691 +--------------------------------+-----------------------------+-----------------------------------+ 692 | :param:`version_file` | :type:`File` | :value:`None` | 693 +--------------------------------+-----------------------------+-----------------------------------+ 694 | Version file used for link stamping. See link_. | 695 +--------------------------------+-----------------------------+-----------------------------------+ 696 | :param:`info_file` | :type:`File` | :value:`None` | 697 +--------------------------------+-----------------------------+-----------------------------------+ 698 | Info file used for link stamping. See link_. | 699 +--------------------------------+-----------------------------+-----------------------------------+ 700 | :param:`executable` | :type:`File` | :value:`None` | 701 +--------------------------------+-----------------------------+-----------------------------------+ 702 | Optional output file to write. If not set, ``binary`` will generate an output | 703 | file name based on ``name``, the target platform, and the link mode. | 704 +--------------------------------+-----------------------------+-----------------------------------+ 705 706 707 link 708 ++++ 709 710 The link function adds an action that runs ``go tool link`` on a library. 711 712 It does not return anything. 713 714 +--------------------------------+-----------------------------+-----------------------------------+ 715 | **Name** | **Type** | **Default value** | 716 +--------------------------------+-----------------------------+-----------------------------------+ 717 | :param:`go` | :type:`GoContext` | |mandatory| | 718 +--------------------------------+-----------------------------+-----------------------------------+ 719 | This must be the same GoContext object you got this function from. | 720 +--------------------------------+-----------------------------+-----------------------------------+ 721 | :param:`archive` | :type:`GoArchive` | |mandatory| | 722 +--------------------------------+-----------------------------+-----------------------------------+ 723 | The library to link. | 724 +--------------------------------+-----------------------------+-----------------------------------+ 725 | :param:`test_archives` | :type:`GoArchiveData list` | :value:`[]` | 726 +--------------------------------+-----------------------------+-----------------------------------+ 727 | List of archives for libraries under test. These are excluded from linking | 728 | if transitive dependencies of :param:`archive` have the same package paths. | 729 | This is useful for linking external test archives that depend internal test | 730 | archives. | 731 +--------------------------------+-----------------------------+-----------------------------------+ 732 | :param:`executable` | :type:`File` | |mandatory| | 733 +--------------------------------+-----------------------------+-----------------------------------+ 734 | The binary to produce. | 735 +--------------------------------+-----------------------------+-----------------------------------+ 736 | :param:`gc_linkopts` | :type:`string_list` | :value:`[]` | 737 +--------------------------------+-----------------------------+-----------------------------------+ 738 | Basic link options, these may be adjusted by the :param:`mode`. | 739 +--------------------------------+-----------------------------+-----------------------------------+ 740 | :param:`version_file` | :type:`File` | :value:`None` | 741 +--------------------------------+-----------------------------+-----------------------------------+ 742 | Version file used for link stamping. | 743 +--------------------------------+-----------------------------+-----------------------------------+ 744 | :param:`info_file` | :type:`File` | :value:`None` | 745 +--------------------------------+-----------------------------+-----------------------------------+ 746 | Info file used for link stamping. | 747 +--------------------------------+-----------------------------+-----------------------------------+ 748 749 750 args 751 ++++ 752 753 This creates a new Args_ object, using the ``ctx.actions.args`` method. The 754 object is pre-populated with standard arguments used by all the go toolchain 755 builders. 756 757 +--------------------------------+-----------------------------+-----------------------------------+ 758 | **Name** | **Type** | **Default value** | 759 +--------------------------------+-----------------------------+-----------------------------------+ 760 | :param:`go` | :type:`GoContext` | |mandatory| | 761 +--------------------------------+-----------------------------+-----------------------------------+ 762 | This must be the same GoContext object you got this function from. | 763 +--------------------------------+-----------------------------+-----------------------------------+ 764 765 declare_file 766 ++++++++++++ 767 768 This is the equivalent of ``ctx.actions.declare_file``. It uses the 769 current build mode to make the filename unique between configurations. 770 771 +--------------------------------+-----------------------------+-----------------------------------+ 772 | **Name** | **Type** | **Default value** | 773 +--------------------------------+-----------------------------+-----------------------------------+ 774 | :param:`go` | :type:`GoContext` | |mandatory| | 775 +--------------------------------+-----------------------------+-----------------------------------+ 776 | This must be the same GoContext object you got this function from. | 777 +--------------------------------+-----------------------------+-----------------------------------+ 778 | :param:`path` | :type:`string` | :value:`""` | 779 +--------------------------------+-----------------------------+-----------------------------------+ 780 | A path for this file, including the basename of the file. | 781 +--------------------------------+-----------------------------+-----------------------------------+ 782 | :param:`ext` | :type:`string` | :value:`""` | 783 +--------------------------------+-----------------------------+-----------------------------------+ 784 | The extension to use for the file. | 785 +--------------------------------+-----------------------------+-----------------------------------+ 786 | :param:`name` | :type:`string` | :value:`""` | 787 +--------------------------------+-----------------------------+-----------------------------------+ 788 | A name to use for this file. If path is not present, this becomes a prefix to the path. | 789 | If this is not set, the current rule name is used in it's place. | 790 +--------------------------------+-----------------------------+-----------------------------------+ 791 792 library_to_source 793 +++++++++++++++++ 794 795 This is used to build a GoSource object for a given GoLibrary in the current 796 build mode. 797 798 +--------------------------------+-----------------------------+-----------------------------------+ 799 | **Name** | **Type** | **Default value** | 800 +--------------------------------+-----------------------------+-----------------------------------+ 801 | :param:`go` | :type:`GoContext` | |mandatory| | 802 +--------------------------------+-----------------------------+-----------------------------------+ 803 | This must be the same GoContext object you got this function from. | 804 +--------------------------------+-----------------------------+-----------------------------------+ 805 | :param:`attr` | :type:`ctx.attr` | |mandatory| | 806 +--------------------------------+-----------------------------+-----------------------------------+ 807 | The attributes of the target being analyzed. For most rules, this should be | 808 | ``ctx.attr``. Rules can also pass in a ``struct`` with the same fields. | 809 | | 810 | ``library_to_source`` looks for fields corresponding to the attributes of | 811 | ``go_library`` and ``go_binary``. This includes ``srcs``, ``deps``, ``embed``, | 812 | and so on. All fields are optional (and may not be defined in the struct | 813 | argument at all), but if they are present, they must have the same types and | 814 | allowed values as in ``go_library`` and ``go_binary``. For example, ``srcs`` | 815 | must be a list of ``Targets``; ``gc_goopts`` must be a list of strings. | 816 | | 817 | As an exception, ``deps``, if present, must be a list containing either | 818 | ``Targets`` or ``GoArchives``. | 819 +--------------------------------+-----------------------------+-----------------------------------+ 820 | :param:`library` | :type:`GoLibrary` | |mandatory| | 821 +--------------------------------+-----------------------------+-----------------------------------+ 822 | The GoLibrary_ that you want to build a GoSource_ object for in the current build mode. | 823 +--------------------------------+-----------------------------+-----------------------------------+ 824 | :param:`coverage_instrumented` | :type:`bool` | |mandatory| | 825 +--------------------------------+-----------------------------+-----------------------------------+ 826 | This controls whether cover is enabled for this specific library in this mode. | 827 | This should generally be the value of ctx.coverage_instrumented() | 828 +--------------------------------+-----------------------------+-----------------------------------+ 829 830 new_library 831 +++++++++++ 832 833 This creates a new GoLibrary. You can add extra fields to the go library by 834 providing extra named parameters to this function, they will be visible to the 835 resolver when it is invoked. 836 837 +--------------------------------+-----------------------------+-----------------------------------+ 838 | **Name** | **Type** | **Default value** | 839 +--------------------------------+-----------------------------+-----------------------------------+ 840 | :param:`go` | :type:`GoContext` | |mandatory| | 841 +--------------------------------+-----------------------------+-----------------------------------+ 842 | This must be the same GoContext object you got this function from. | 843 +--------------------------------+-----------------------------+-----------------------------------+ 844 | :param:`resolver` | :type:`function` | :value:`None` | 845 +--------------------------------+-----------------------------+-----------------------------------+ 846 | This is the function that gets invoked when converting from a GoLibrary to a GoSource. | 847 | The function's signature must be | 848 | | 849 | .. code:: bzl | 850 | | 851 | def _stdlib_library_to_source(go, attr, source, merge) | 852 | | 853 | attr is the attributes of the rule being processed | 854 | source is the dictionary of GoSource fields being generated | 855 | merge is a helper you can call to merge | 856 +--------------------------------+-----------------------------+-----------------------------------+ 857 | :param:`importable` | :type:`bool` | |mandatory| | 858 +--------------------------------+-----------------------------+-----------------------------------+ 859 | This controls whether the GoLibrary_ is supposed to be importable. This is generally only false | 860 | for the "main" libraries that are built just before linking. | 861 +--------------------------------+-----------------------------+-----------------------------------+