1Go 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 30The Go toolchain is at the heart of the Go rules, and is the mechanism used to 31customize the behavior of the core_ Go rules. 32 33.. contents:: :depth: 2 34 35----- 36 37Overview 38-------- 39 40The Go toolchain consists of three main layers: `the SDK`_, `the toolchain`_, 41and `the context`_. 42 43The SDK 44~~~~~~~ 45 46The Go SDK (more commonly known as the Go distribution) is a directory tree 47containing sources for the Go toolchain and standard library and pre-compiled 48binaries for the same. You can download this from by visiting the `Go website`_ 49and downloading a `binary distribution`_. 50 51There 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 63By default, if none of the above rules are used, the `go_register_toolchains`_ 64function creates a repository named ``@go_sdk`` using `go_download_sdk`_, using 65a recent version of Go for the host operating system and architecture. 66 67SDKs are specific to a host platform (e.g., ``linux_amd64``) and a version of 68Go. They may target all platforms that Go supports. The Go SDK is naturally 69cross compiling. 70 71By default, all ``go_binary``, ``go_test``, etc. rules will use the first declared 72Go SDK. If you would like to build a target using a specific Go SDK version, first 73ensure 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 75can specify the sdk version to build with when running a ``bazel build`` by passing 76the 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"``. 78The 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``. 80When ``go_host_sdk`` is used, ``"version"`` can be set to ``host`` to refer to the host Go SDK. 81It can also be set ``remote`` to match any non-host version. 82 83The toolchain 84~~~~~~~~~~~~~ 85 86The workspace rules above declare `Bazel toolchains`_ with `go_toolchain`_ 87implementations for each target platform that Go supports. Wrappers around 88the rules register these toolchains automatically. Bazel will select a 89registered toolchain automatically based on the execution and target platforms, 90specified with ``--host_platform`` and ``--platforms``, respectively. 91 92The workspace rules define the toolchains in a separate repository from the 93SDK. For example, if the SDK repository is `@go_sdk`, the toolchains will be 94defined in `@go_sdk_toolchains`. The `@go_sdk_toolchains` repository must be 95eagerly fetched in order to register the toolchain, but fetching the `@go_sdk` 96repository may be delayed until the toolchain is needed to build something. To 97activate lazily fetching the SDK, you must provide a `version` attribute to the 98workspace 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 100version of the SDK; rules_go will validate this when the toolchain is used. 101 102The toolchain itself should be considered opaque. You should only access 103its contents through `the context`_. 104 105The context 106~~~~~~~~~~~ 107 108The context is the type you need if you are writing custom rules that need 109to be compatible with rules_go. It provides information about the SDK, the 110toolchain, and the standard library. It also provides a convenient way to 111declare mode-specific files, and to create actions for compiling, linking, 112and more. 113 114Customizing 115----------- 116 117Normal usage 118~~~~~~~~~~~~ 119 120This is an example of normal usage for the other examples to be compared 121against. This will download and use a specific version of Go for the host 122platform. 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 135Using the installed Go SDK 136~~~~~~~~~~~~~~~~~~~~~~~~~~ 137 138You can use the Go SDK that's installed on the system where Bazel is running. 139This may result in faster builds, since there's no need to download an SDK, 140but 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 153Registering a custom SDK 154~~~~~~~~~~~~~~~~~~~~~~~~ 155 156If you download the SDK through another repository rule, you can configure 157it with ``go_wrap_sdk``. It must still be named ``go_sdk``, but this is a 158temporary 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 181Writing new Go rules 182~~~~~~~~~~~~~~~~~~~~ 183 184If you are writing a new Bazel rule that uses the Go toolchain, you need to 185do several things to ensure you have full access to the toolchain and common 186dependencies. 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 217Rules and functions 218------------------- 219 220go_register_toolchains 221~~~~~~~~~~~~~~~~~~~~~~ 222 223Installs the Go toolchains. If :param:`version` is specified, it sets the 224SDK 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 255go_download_sdk 256~~~~~~~~~~~~~~~ 257 258This 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 317**Example**: 318 319.. code:: bzl 320 321 load( 322 "@io_bazel_rules_go//go:deps.bzl", 323 "go_download_sdk", 324 "go_register_toolchains", 325 "go_rules_dependencies", 326 ) 327 328 go_download_sdk( 329 name = "go_sdk", 330 goos = "linux", 331 goarch = "amd64", 332 version = "1.18.1", 333 sdks = { 334 # NOTE: In most cases the whole sdks attribute is not needed. 335 # There are 2 "common" reasons you might want it: 336 # 337 # 1. You need to use an modified GO SDK, or an unsupported version 338 # (for example, a beta or release candidate) 339 # 340 # 2. You want to avoid the dependency on the index file for the 341 # SHA-256 checksums. In this case, You can get the expected 342 # filenames and checksums from https://go.dev/dl/ 343 "linux_amd64": ("go1.18.1.linux-amd64.tar.gz", "b3b815f47ababac13810fc6021eb73d65478e0b2db4b09d348eefad9581a2334"), 344 "darwin_amd64": ("go1.18.1.darwin-amd64.tar.gz", "3703e9a0db1000f18c0c7b524f3d378aac71219b4715a6a4c5683eb639f41a4d"), 345 }, 346 ) 347 348 go_rules_dependencies() 349 350 go_register_toolchains() 351 352go_host_sdk 353~~~~~~~~~~~ 354 355This detects and configures the host Go SDK for use in toolchains. 356 357If the ``GOROOT`` environment variable is set, the SDK in that directory is 358used. Otherwise, ``go env GOROOT`` is used. 359 360+--------------------------------+-----------------------------+-----------------------------------+ 361| **Name** | **Type** | **Default value** | 362+--------------------------------+-----------------------------+-----------------------------------+ 363| :param:`name` | :type:`string` | |mandatory| | 364+--------------------------------+-----------------------------+-----------------------------------+ 365| A unique name for this SDK. This should almost always be :value:`go_sdk` if you want the SDK | 366| to be used by toolchains. | 367+--------------------------------+-----------------------------+-----------------------------------+ 368| :param:`version` | :type:`string` | :value:`None` | 369+--------------------------------+-----------------------------+-----------------------------------+ 370| The version of Go installed on the host. If specified, `go_host_sdk` will create its repository | 371| only when the build uses a Go toolchain and `toolchain resolution`_ results in this SDK being | 372| chosen. Otherwise it will be created unconditionally. | 373+--------------------------------+-----------------------------+-----------------------------------+ 374| :param:`experiments` | :type:`string_list` | :value:`[]` | 375+--------------------------------+-----------------------------+-----------------------------------+ 376| Go experiments to enable via `GOEXPERIMENT`. | 377+--------------------------------+-----------------------------+-----------------------------------+ 378 379go_local_sdk 380~~~~~~~~~~~~ 381 382This prepares a local path to use as the Go SDK in toolchains. 383 384+--------------------------------+-----------------------------+-----------------------------------+ 385| **Name** | **Type** | **Default value** | 386+--------------------------------+-----------------------------+-----------------------------------+ 387| :param:`name` | :type:`string` | |mandatory| | 388+--------------------------------+-----------------------------+-----------------------------------+ 389| A unique name for this SDK. This should almost always be :value:`go_sdk` if you want the SDK | 390| to be used by toolchains. | 391+--------------------------------+-----------------------------+-----------------------------------+ 392| :param:`path` | :type:`string` | :value:`""` | 393+--------------------------------+-----------------------------+-----------------------------------+ 394| The local path to a pre-installed Go SDK. The path must contain the go binary, the tools it | 395| invokes and the standard library sources. | 396+--------------------------------+-----------------------------+-----------------------------------+ 397| :param:`version` | :type:`string` | :value:`None` | 398+--------------------------------+-----------------------------+-----------------------------------+ 399| The version of the Go SDK. If specified, `go_local_sdk` will create its repository only when the | 400| build uses a Go toolchain and `toolchain resolution`_ results in this SDK being chosen. | 401| Otherwise it will be created unconditionally. | 402+--------------------------------+-----------------------------+-----------------------------------+ 403| :param:`experiments` | :type:`string_list` | :value:`[]` | 404+--------------------------------+-----------------------------+-----------------------------------+ 405| Go experiments to enable via `GOEXPERIMENT`. | 406+--------------------------------+-----------------------------+-----------------------------------+ 407 408 409go_wrap_sdk 410~~~~~~~~~~~ 411 412This configures an SDK that was downloaded or located with another repository 413rule. 414 415+--------------------------------+-----------------------------+-----------------------------------+ 416| **Name** | **Type** | **Default value** | 417+--------------------------------+-----------------------------+-----------------------------------+ 418| :param:`name` | :type:`string` | |mandatory| | 419+--------------------------------+-----------------------------+-----------------------------------+ 420| A unique name for this SDK. This should almost always be :value:`go_sdk` if you want the SDK | 421| to be used by toolchains. | 422+--------------------------------+-----------------------------+-----------------------------------+ 423| :param:`root_file` | :type:`label` | :value:`None` | 424+--------------------------------+-----------------------------+-----------------------------------+ 425| A Bazel label referencing a file in the root directory of the SDK. Used to | 426| determine the GOROOT for the SDK. This attribute and `root_files` cannot be both provided. | 427+--------------------------------+-----------------------------+-----------------------------------+ 428| :param:`root_files` | :type:`string_dict` | :value:`None` | 429+--------------------------------+-----------------------------+-----------------------------------+ 430| A set of mappings from the host platform to a Bazel label referencing a file in the SDK's root | 431| directory. This attribute and `root_file` cannot be both provided. | 432+--------------------------------+-----------------------------+-----------------------------------+ 433| :param:`version` | :type:`string` | :value:`None` | 434+--------------------------------+-----------------------------+-----------------------------------+ 435| The version of the Go SDK. If specified, `go_wrap_sdk` will create its repository only when the | 436| build uses a Go toolchain and `toolchain resolution`_ results in this SDK being chosen. | 437| Otherwise it will be created unconditionally. | 438+--------------------------------+-----------------------------+-----------------------------------+ 439| :param:`experiments` | :type:`string_list` | :value:`[]` | 440+--------------------------------+-----------------------------+-----------------------------------+ 441| Go experiments to enable via `GOEXPERIMENT`. | 442+--------------------------------+-----------------------------+-----------------------------------+ 443 444 445**Example:** 446 447.. code:: bzl 448 449 load( 450 "@io_bazel_rules_go//go:deps.bzl", 451 "go_register_toolchains", 452 "go_rules_dependencies", 453 "go_wrap_sdk", 454 ) 455 456 go_wrap_sdk( 457 name = "go_sdk", 458 root_file = "@other_repo//go:README.md", 459 ) 460 461 go_rules_dependencies() 462 463 go_register_toolchains() 464 465go_toolchain 466~~~~~~~~~~~~ 467 468This declares a toolchain that may be used with toolchain type 469:value:`"@io_bazel_rules_go//go:toolchain"`. 470 471Normally, ``go_toolchain`` rules are declared and registered in repositories 472configured with `go_download_sdk`_, `go_host_sdk`_, `go_local_sdk`_, or 473`go_wrap_sdk`_. You usually won't need to declare these explicitly. 474 475+--------------------------------+-----------------------------+-----------------------------------+ 476| **Name** | **Type** | **Default value** | 477+--------------------------------+-----------------------------+-----------------------------------+ 478| :param:`name` | :type:`string` | |mandatory| | 479+--------------------------------+-----------------------------+-----------------------------------+ 480| A unique name for the toolchain. | 481+--------------------------------+-----------------------------+-----------------------------------+ 482| :param:`goos` | :type:`string` | |mandatory| | 483+--------------------------------+-----------------------------+-----------------------------------+ 484| The target operating system. Must be a standard ``GOOS`` value. | 485+--------------------------------+-----------------------------+-----------------------------------+ 486| :param:`goarch` | :type:`string` | |mandatory| | 487+--------------------------------+-----------------------------+-----------------------------------+ 488| The target architecture. Must be a standard ``GOARCH`` value. | 489+--------------------------------+-----------------------------+-----------------------------------+ 490| :param:`sdk` | :type:`label` | |mandatory| | 491+--------------------------------+-----------------------------+-----------------------------------+ 492| The SDK this toolchain is based on. The target must provide `GoSDK`_. This is | 493| usually a `go_sdk`_ rule. | 494+--------------------------------+-----------------------------+-----------------------------------+ 495| :param:`link_flags` | :type:`string_list` | :value:`[]` | 496+--------------------------------+-----------------------------+-----------------------------------+ 497| Flags passed to the Go external linker. | 498+--------------------------------+-----------------------------+-----------------------------------+ 499| :param:`cgo_link_flags` | :type:`string_list` | :value:`[]` | 500+--------------------------------+-----------------------------+-----------------------------------+ 501| Flags passed to the external linker (if it is used). | 502+--------------------------------+-----------------------------+-----------------------------------+ 503 504go_context 505~~~~~~~~~~ 506 507This collects the information needed to form and return a :type:`GoContext` from 508a rule ctx. It uses the attributes and the toolchains. 509 510.. code:: bzl 511 512 def _my_rule_impl(ctx): 513 go = go_context(ctx) 514 ... 515 516 517+--------------------------------+-----------------------------+-----------------------------------+ 518| **Name** | **Type** | **Default value** | 519+--------------------------------+-----------------------------+-----------------------------------+ 520| :param:`ctx` | :type:`ctx` | |mandatory| | 521+--------------------------------+-----------------------------+-----------------------------------+ 522| The Bazel ctx object for the current rule. | 523+--------------------------------+-----------------------------+-----------------------------------+ 524 525The context object 526~~~~~~~~~~~~~~~~~~ 527 528``GoContext`` is never returned by a rule, instead you build one using 529``go_context(ctx)`` in the top of any custom starlark rule that wants to interact 530with the go rules. It provides all the information needed to create go actions, 531and create or interact with the other go providers. 532 533When you get a ``GoContext`` from a context it exposes a number of fields 534and methods. 535 536All methods take the ``GoContext`` as the only positional argument. All other 537arguments must be passed as keyword arguments. This allows us to re-order and 538deprecate individual parameters over time. 539 540Fields 541^^^^^^ 542 543+--------------------------------+-----------------------------------------------------------------+ 544| **Name** | **Type** | 545+--------------------------------+-----------------------------------------------------------------+ 546| :param:`toolchain` | :type:`ToolchainInfo` | 547+--------------------------------+-----------------------------------------------------------------+ 548| The underlying toolchain. This should be considered an opaque type subject to change. | 549+--------------------------------+-----------------------------------------------------------------+ 550| :param:`sdk` | :type:`GoSDK` | 551+--------------------------------+-----------------------------------------------------------------+ 552| The SDK in use. This may be used to access sources, packages, and tools. | 553+--------------------------------+-----------------------------------------------------------------+ 554| :param:`mode` | :type:`Mode` | 555+--------------------------------+-----------------------------------------------------------------+ 556| Controls the compilation setup affecting things like enabling profilers and sanitizers. | 557| See `compilation modes`_ for more information about the allowed values. | 558+--------------------------------+-----------------------------------------------------------------+ 559| :param:`root` | :type:`string` | 560+--------------------------------+-----------------------------------------------------------------+ 561| Path of the effective GOROOT. If :param:`stdlib` is set, this is the same | 562| as ``go.stdlib.root_file.dirname``. Otherwise, this is the same as | 563| ``go.sdk.root_file.dirname``. | 564+--------------------------------+-----------------------------------------------------------------+ 565| :param:`go` | :type:`File` | 566+--------------------------------+-----------------------------------------------------------------+ 567| The main "go" binary used to run go sdk tools. | 568+--------------------------------+-----------------------------------------------------------------+ 569| :param:`stdlib` | :type:`GoStdLib` | 570+--------------------------------+-----------------------------------------------------------------+ 571| The standard library and tools to use in this build mode. This may be the | 572| pre-compiled standard library that comes with the SDK, or it may be compiled | 573| in a different directory for this mode. | 574+--------------------------------+-----------------------------------------------------------------+ 575| :param:`actions` | :type:`ctx.actions` | 576+--------------------------------+-----------------------------------------------------------------+ 577| The actions structure from the Bazel context, which has all the methods for building new | 578| bazel actions. | 579+--------------------------------+-----------------------------------------------------------------+ 580| :param:`exe_extension` | :type:`string` | 581+--------------------------------+-----------------------------------------------------------------+ 582| The suffix to use for all executables in this build mode. Mostly used when generating the output | 583| filenames of binary rules. | 584+--------------------------------+-----------------------------------------------------------------+ 585| :param:`shared_extension` | :type:`string` | 586+--------------------------------+-----------------------------------------------------------------+ 587| The suffix to use for shared libraries in this build mode. Mostly used when | 588| generating output filenames of binary rules. | 589+--------------------------------+-----------------------------------------------------------------+ 590| :param:`crosstool` | :type:`list of File` | 591+--------------------------------+-----------------------------------------------------------------+ 592| The files you need to add to the inputs of an action in order to use the cc toolchain. | 593+--------------------------------+-----------------------------------------------------------------+ 594| :param:`package_list` | :type:`File` | 595+--------------------------------+-----------------------------------------------------------------+ 596| A file that contains the package list of the standard library. | 597+--------------------------------+-----------------------------------------------------------------+ 598| :param:`env` | :type:`dict of string to string` | 599+--------------------------------+-----------------------------------------------------------------+ 600| Environment variables to pass to actions. Includes ``GOARCH``, ``GOOS``, | 601| ``GOROOT``, ``GOROOT_FINAL``, ``CGO_ENABLED``, and ``PATH``. | 602+--------------------------------+-----------------------------------------------------------------+ 603| :param:`tags` | :type:`list of string` | 604+--------------------------------+-----------------------------------------------------------------+ 605| List of build tags used to filter source files. | 606+--------------------------------+-----------------------------------------------------------------+ 607 608Methods 609^^^^^^^ 610 611* Action generators 612 613 * archive_ 614 * binary_ 615 * link_ 616 617* Helpers 618 619 * args_ 620 * `declare_file`_ 621 * `library_to_source`_ 622 * `new_library`_ 623 624 625archive 626+++++++ 627 628This emits actions to compile Go code into an archive. It supports embedding, 629cgo dependencies, coverage, and assembling and packing .s files. 630 631It returns a GoArchive_. 632 633+--------------------------------+-----------------------------+-----------------------------------+ 634| **Name** | **Type** | **Default value** | 635+--------------------------------+-----------------------------+-----------------------------------+ 636| :param:`go` | :type:`GoContext` | |mandatory| | 637+--------------------------------+-----------------------------+-----------------------------------+ 638| This must be the same GoContext object you got this function from. | 639+--------------------------------+-----------------------------+-----------------------------------+ 640| :param:`source` | :type:`GoSource` | |mandatory| | 641+--------------------------------+-----------------------------+-----------------------------------+ 642| The GoSource_ that should be compiled into an archive. | 643+--------------------------------+-----------------------------+-----------------------------------+ 644 645 646binary 647++++++ 648 649This emits actions to compile and link Go code into a binary. It supports 650embedding, cgo dependencies, coverage, and assembling and packing .s files. 651 652It returns a tuple containing GoArchive_, the output executable file, and 653a ``runfiles`` object. 654 655+--------------------------------+-----------------------------+-----------------------------------+ 656| **Name** | **Type** | **Default value** | 657+--------------------------------+-----------------------------+-----------------------------------+ 658| :param:`go` | :type:`GoContext` | |mandatory| | 659+--------------------------------+-----------------------------+-----------------------------------+ 660| This must be the same GoContext object you got this function from. | 661+--------------------------------+-----------------------------+-----------------------------------+ 662| :param:`name` | :type:`string` | :value:`""` | 663+--------------------------------+-----------------------------+-----------------------------------+ 664| The base name of the generated binaries. Required if :param:`executable` is not given. | 665+--------------------------------+-----------------------------+-----------------------------------+ 666| :param:`source` | :type:`GoSource` | |mandatory| | 667+--------------------------------+-----------------------------+-----------------------------------+ 668| The GoSource_ that should be compiled and linked. | 669+--------------------------------+-----------------------------+-----------------------------------+ 670| :param:`test_archives` | :type:`list GoArchiveData` | :value:`[]` | 671+--------------------------------+-----------------------------+-----------------------------------+ 672| List of archives for libraries under test. See link_. | 673+--------------------------------+-----------------------------+-----------------------------------+ 674| :param:`gc_linkopts` | :type:`string_list` | :value:`[]` | 675+--------------------------------+-----------------------------+-----------------------------------+ 676| Go link options. | 677+--------------------------------+-----------------------------+-----------------------------------+ 678| :param:`version_file` | :type:`File` | :value:`None` | 679+--------------------------------+-----------------------------+-----------------------------------+ 680| Version file used for link stamping. See link_. | 681+--------------------------------+-----------------------------+-----------------------------------+ 682| :param:`info_file` | :type:`File` | :value:`None` | 683+--------------------------------+-----------------------------+-----------------------------------+ 684| Info file used for link stamping. See link_. | 685+--------------------------------+-----------------------------+-----------------------------------+ 686| :param:`executable` | :type:`File` | :value:`None` | 687+--------------------------------+-----------------------------+-----------------------------------+ 688| Optional output file to write. If not set, ``binary`` will generate an output | 689| file name based on ``name``, the target platform, and the link mode. | 690+--------------------------------+-----------------------------+-----------------------------------+ 691 692 693link 694++++ 695 696The link function adds an action that runs ``go tool link`` on a library. 697 698It does not return anything. 699 700+--------------------------------+-----------------------------+-----------------------------------+ 701| **Name** | **Type** | **Default value** | 702+--------------------------------+-----------------------------+-----------------------------------+ 703| :param:`go` | :type:`GoContext` | |mandatory| | 704+--------------------------------+-----------------------------+-----------------------------------+ 705| This must be the same GoContext object you got this function from. | 706+--------------------------------+-----------------------------+-----------------------------------+ 707| :param:`archive` | :type:`GoArchive` | |mandatory| | 708+--------------------------------+-----------------------------+-----------------------------------+ 709| The library to link. | 710+--------------------------------+-----------------------------+-----------------------------------+ 711| :param:`test_archives` | :type:`GoArchiveData list` | :value:`[]` | 712+--------------------------------+-----------------------------+-----------------------------------+ 713| List of archives for libraries under test. These are excluded from linking | 714| if transitive dependencies of :param:`archive` have the same package paths. | 715| This is useful for linking external test archives that depend internal test | 716| archives. | 717+--------------------------------+-----------------------------+-----------------------------------+ 718| :param:`executable` | :type:`File` | |mandatory| | 719+--------------------------------+-----------------------------+-----------------------------------+ 720| The binary to produce. | 721+--------------------------------+-----------------------------+-----------------------------------+ 722| :param:`gc_linkopts` | :type:`string_list` | :value:`[]` | 723+--------------------------------+-----------------------------+-----------------------------------+ 724| Basic link options, these may be adjusted by the :param:`mode`. | 725+--------------------------------+-----------------------------+-----------------------------------+ 726| :param:`version_file` | :type:`File` | :value:`None` | 727+--------------------------------+-----------------------------+-----------------------------------+ 728| Version file used for link stamping. | 729+--------------------------------+-----------------------------+-----------------------------------+ 730| :param:`info_file` | :type:`File` | :value:`None` | 731+--------------------------------+-----------------------------+-----------------------------------+ 732| Info file used for link stamping. | 733+--------------------------------+-----------------------------+-----------------------------------+ 734 735 736args 737++++ 738 739This creates a new Args_ object, using the ``ctx.actions.args`` method. The 740object is pre-populated with standard arguments used by all the go toolchain 741builders. 742 743+--------------------------------+-----------------------------+-----------------------------------+ 744| **Name** | **Type** | **Default value** | 745+--------------------------------+-----------------------------+-----------------------------------+ 746| :param:`go` | :type:`GoContext` | |mandatory| | 747+--------------------------------+-----------------------------+-----------------------------------+ 748| This must be the same GoContext object you got this function from. | 749+--------------------------------+-----------------------------+-----------------------------------+ 750 751declare_file 752++++++++++++ 753 754This is the equivalent of ``ctx.actions.declare_file``. It uses the 755current build mode to make the filename unique between configurations. 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| :param:`path` | :type:`string` | :value:`""` | 765+--------------------------------+-----------------------------+-----------------------------------+ 766| A path for this file, including the basename of the file. | 767+--------------------------------+-----------------------------+-----------------------------------+ 768| :param:`ext` | :type:`string` | :value:`""` | 769+--------------------------------+-----------------------------+-----------------------------------+ 770| The extension to use for the file. | 771+--------------------------------+-----------------------------+-----------------------------------+ 772| :param:`name` | :type:`string` | :value:`""` | 773+--------------------------------+-----------------------------+-----------------------------------+ 774| A name to use for this file. If path is not present, this becomes a prefix to the path. | 775| If this is not set, the current rule name is used in it's place. | 776+--------------------------------+-----------------------------+-----------------------------------+ 777 778library_to_source 779+++++++++++++++++ 780 781This is used to build a GoSource object for a given GoLibrary in the current 782build mode. 783 784+--------------------------------+-----------------------------+-----------------------------------+ 785| **Name** | **Type** | **Default value** | 786+--------------------------------+-----------------------------+-----------------------------------+ 787| :param:`go` | :type:`GoContext` | |mandatory| | 788+--------------------------------+-----------------------------+-----------------------------------+ 789| This must be the same GoContext object you got this function from. | 790+--------------------------------+-----------------------------+-----------------------------------+ 791| :param:`attr` | :type:`ctx.attr` | |mandatory| | 792+--------------------------------+-----------------------------+-----------------------------------+ 793| The attributes of the target being analyzed. For most rules, this should be | 794| ``ctx.attr``. Rules can also pass in a ``struct`` with the same fields. | 795| | 796| ``library_to_source`` looks for fields corresponding to the attributes of | 797| ``go_library`` and ``go_binary``. This includes ``srcs``, ``deps``, ``embed``, | 798| and so on. All fields are optional (and may not be defined in the struct | 799| argument at all), but if they are present, they must have the same types and | 800| allowed values as in ``go_library`` and ``go_binary``. For example, ``srcs`` | 801| must be a list of ``Targets``; ``gc_goopts`` must be a list of strings. | 802| | 803| As an exception, ``deps``, if present, must be a list containing either | 804| ``Targets`` or ``GoArchives``. | 805+--------------------------------+-----------------------------+-----------------------------------+ 806| :param:`library` | :type:`GoLibrary` | |mandatory| | 807+--------------------------------+-----------------------------+-----------------------------------+ 808| The GoLibrary_ that you want to build a GoSource_ object for in the current build mode. | 809+--------------------------------+-----------------------------+-----------------------------------+ 810| :param:`coverage_instrumented` | :type:`bool` | |mandatory| | 811+--------------------------------+-----------------------------+-----------------------------------+ 812| This controls whether cover is enabled for this specific library in this mode. | 813| This should generally be the value of ctx.coverage_instrumented() | 814+--------------------------------+-----------------------------+-----------------------------------+ 815 816new_library 817+++++++++++ 818 819This creates a new GoLibrary. You can add extra fields to the go library by 820providing extra named parameters to this function, they will be visible to the 821resolver when it is invoked. 822 823+--------------------------------+-----------------------------+-----------------------------------+ 824| **Name** | **Type** | **Default value** | 825+--------------------------------+-----------------------------+-----------------------------------+ 826| :param:`go` | :type:`GoContext` | |mandatory| | 827+--------------------------------+-----------------------------+-----------------------------------+ 828| This must be the same GoContext object you got this function from. | 829+--------------------------------+-----------------------------+-----------------------------------+ 830| :param:`resolver` | :type:`function` | :value:`None` | 831+--------------------------------+-----------------------------+-----------------------------------+ 832| This is the function that gets invoked when converting from a GoLibrary to a GoSource. | 833| The function's signature must be | 834| | 835| .. code:: bzl | 836| | 837| def _stdlib_library_to_source(go, attr, source, merge) | 838| | 839| attr is the attributes of the rule being processed | 840| source is the dictionary of GoSource fields being generated | 841| merge is a helper you can call to merge | 842+--------------------------------+-----------------------------+-----------------------------------+ 843| :param:`importable` | :type:`bool` | |mandatory| | 844+--------------------------------+-----------------------------+-----------------------------------+ 845| This controls whether the GoLibrary_ is supposed to be importable. This is generally only false | 846| for the "main" libraries that are built just before linking. | 847+--------------------------------+-----------------------------+-----------------------------------+ 848