github.com/ajguerrer/rules_go@v0.20.3/go/toolchains.rst (about) 1 Go toolchains 2 ============= 3 4 .. _core: core.bzl 5 .. _forked version of Go: `Registering a custom SDK`_ 6 .. _control the version: `Forcing the Go version`_ 7 .. _installed SDK: `Using the installed Go sdk`_ 8 .. _go sdk rules: `The SDK`_ 9 .. _Go website: https://golang.org/ 10 .. _binary distribution: https://golang.org/dl/ 11 .. _register: Registration_ 12 .. _register_toolchains: https://docs.bazel.build/versions/master/skylark/lib/globals.html#register_toolchains 13 .. _compilation modes: modes.rst#compilation-modes 14 .. _go assembly: https://golang.org/doc/asm 15 .. _GoLibrary: providers.rst#golibrary 16 .. _GoSource: providers.rst#gosource 17 .. _GoArchive: providers.rst#goarchive 18 .. _GoSDK: providers.rst#gosdk 19 .. _go/platform/list.bzl: platform/list.bzl 20 .. _Args: https://docs.bazel.build/versions/master/skylark/lib/Args.html 21 .. _nogo: nogo.rst#nogo 22 23 .. role:: param(kbd) 24 .. role:: type(emphasis) 25 .. role:: value(code) 26 .. |mandatory| replace:: **mandatory value** 27 28 The Go toolchain is at the heart of the Go rules, and is the mechanism used to 29 customize the behavior of the core_ Go rules. 30 31 .. contents:: :depth: 2 32 33 ----- 34 35 Design 36 ------ 37 38 The Go toolchain consists of three main layers, `the SDK`_ and `the toolchain`_ 39 and `the context`_. 40 41 The SDK 42 ~~~~~~~ 43 44 At the bottom is the Go SDK. This is the same thing you would get if you go to 45 the main `Go website`_ and download a `binary distribution`_. 46 47 In the past, this has always been a repository rule bound to ``@go_sdk``, but 48 we are moving away from this as part of an effort to enable the use of multiple 49 SDKs in remote execution. It's best to access this through the toolchain. 50 51 The `go_download_sdk`_, `go_host_sdk`_, `go_local_sdk`_, and `go_wrap_sdk`_ 52 rules are responsible for downloading / locating and configuring an SDK by 53 adding just enough of a build file to expose the contents to Bazel. 54 55 SDKs are specific to a host platform (e.g., ``linux_amd64``) and a version of 56 Go. They may target all platforms that Go supports. The Go SDK is naturally 57 cross compiling. 58 59 SDKs are declared to Bazel with the `go_sdk`_ rule, which gathers information 60 about the SDK into the `GoSDK`_ provider, which may be consumed by other 61 rules through `the context`_. 62 63 If you haven't declared an SDK before calling ``go_register_toolchains()``, 64 a `go_download_sdk`_ rule will be declared automatically. This is good enough 65 in more situations, but if you need a `forked version of Go`_, 66 want to `control the version`_, or use the `installed SDK`_, declare 67 a Go SDK repository before calling ``go_register_toolchains``. 68 69 The toolchain 70 ~~~~~~~~~~~~~ 71 72 This a wrapper over the SDK that provides extra information about the 73 target platform. 74 75 Toolchains are declared with the `go_toolchain`_ rule inside an SDK repository. 76 They are registered within the macro that declares the SDK repository. Bazel 77 will select a toolchain based on the target platform (specified with 78 ``--platforms`` on the command line). 79 80 The toolchain itself should be considered opaque. You should only access 81 its contents through `the context`_. 82 83 The context 84 ~~~~~~~~~~~ 85 86 The context is the type you need if you are writing custom rules that need 87 to be compatible with rules_go. It provides information about the SDK, the 88 toolchain, and the standard library. It also provides a convenient way to 89 declare mode-specific files, and to create actions for compiling, linking, 90 and more. 91 92 Customizing 93 ----------- 94 95 Normal usage 96 ~~~~~~~~~~~~ 97 98 This is an example of normal usage for the other examples to be compared 99 against. This will download and use the latest Go SDK that was available when 100 the version of rules_go you're using was released. 101 102 .. code:: bzl 103 # WORKSPACE 104 105 load("@io_bazel_rules_go//go:deps.bzl", "go_rules_dependencies", "go_register_toolchains") 106 107 go_rules_dependencies() 108 go_register_toolchains() 109 110 111 Forcing the Go version 112 ~~~~~~~~~~~~~~~~~~~~~~ 113 114 You can select the version of the Go SDK to use by specifying it when you call 115 `go_register_toolchains`_ but you must use a value that matches a known 116 toolchain. 117 118 .. code:: bzl 119 # WORKSPACE 120 121 load("@io_bazel_rules_go//go:deps.bzl", "go_rules_dependencies", "go_register_toolchains") 122 123 go_rules_dependencies() 124 go_register_toolchains(go_version="1.10.3") 125 126 127 Using the installed Go SDK 128 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 129 130 You can use the Go SDK that's installed on the system where Bazel is running. 131 This may result in faster builds, since there's no need to download an SDK, 132 but builds won't be reproducible across systems with different SDKs installed. 133 134 .. code:: bzl 135 # WORKSPACE 136 137 load("@io_bazel_rules_go//go:deps.bzl", "go_rules_dependencies", "go_register_toolchains") 138 139 go_rules_dependencies() 140 go_register_toolchains(go_version="host") 141 142 143 Registering a custom SDK 144 ~~~~~~~~~~~~~~~~~~~~~~~~ 145 146 If you download the SDK through another repository rule, you can configure 147 it with ``go_wrap_sdk``. It must still be named ``go_sdk``, but this is a 148 temporary limitation that will be removed in the future. 149 150 .. code:: bzl 151 # WORKSPACE 152 153 load("@io_bazel_rules_go//go:deps.bzl", "go_rules_dependencies", "go_register_toolchains", "go_wrap_sdk") 154 155 unknown_download_sdk( 156 name = "go", 157 ..., 158 ) 159 160 go_wrap_sdk( 161 name = "go_sdk", 162 root_file = "@go//:README.md", 163 ) 164 165 go_rules_dependencies() 166 go_register_toolchains() 167 168 169 Writing new Go rules 170 ~~~~~~~~~~~~~~~~~~~~ 171 172 If you are writing a new rule that wants to use the Go toolchain, you need to do 173 a couple of things. First, you have to declare that you want to consume the 174 toolchain on the rule declaration. The easiest way to do this is to use the 175 `go_rule`_ wrapper, which adds in the toolchain and some hidden attributes that 176 it consumes. 177 178 .. code:: bzl 179 180 load("@io_bazel_rules_go//go:def.bzl", "go_context", "go_rule") 181 182 my_rule = go_rule( 183 _my_rule_impl, 184 attrs = { 185 ... 186 }, 187 ) 188 189 And then in the rule body, call `go_context`_ to get the context object. 190 This will give you access to the toolchain and the SDK. 191 192 .. code:: bzl 193 194 def _my_rule_impl(ctx): 195 go = go_context(ctx) 196 197 198 API 199 --- 200 201 go_register_toolchains 202 ~~~~~~~~~~~~~~~~~~~~~~ 203 204 Installs the Go toolchains. If :param:`go_version` is specified, it sets the 205 SDK version to use (for example, :value:`"1.10.3"`). By default, the latest 206 SDK will be used. 207 208 +--------------------------------+-----------------------------+-----------------------------------+ 209 | **Name** | **Type** | **Default value** | 210 +--------------------------------+-----------------------------+-----------------------------------+ 211 | :param:`go_version` | :type:`string` | latest release | 212 +--------------------------------+-----------------------------+-----------------------------------+ 213 | This specifies the version of the Go SDK to download. This is only used if | 214 | no SDK has been declared with the name :value:`go_sdk` before the call to | 215 | ``go_register_toolchains``. The default version is the latest version of Go | 216 | that was released at the time the rules_go release you're using was tagged. | 217 +--------------------------------+-----------------------------+-----------------------------------+ 218 | :param:`nogo` | :type:`label` | :value:`None` | 219 +--------------------------------+-----------------------------+-----------------------------------+ 220 | The ``nogo`` attribute refers to a nogo_ rule that builds a binary | 221 | used for static analysis. The ``nogo`` binary will be used alongside the | 222 | Go compiler when building packages. | 223 +--------------------------------+-----------------------------+-----------------------------------+ 224 225 go_download_sdk 226 ~~~~~~~~~~~~~~~ 227 228 This downloads a Go SDK for use in toolchains. 229 230 +--------------------------------+-----------------------------+---------------------------------------------+ 231 | **Name** | **Type** | **Default value** | 232 +--------------------------------+-----------------------------+---------------------------------------------+ 233 | :param:`name` | :type:`string` | |mandatory| | 234 +--------------------------------+-----------------------------+---------------------------------------------+ 235 | A unique name for this SDK. This should almost always be :value:`go_sdk` if you want the SDK | 236 | to be used by toolchains. | 237 +--------------------------------+-----------------------------+---------------------------------------------+ 238 | :param:`goos` | :type:`string` | :value:`None` | 239 +--------------------------------+-----------------------------+---------------------------------------------+ 240 | The operating system the binaries in the SDK are intended to run on. | 241 | By default, this is detected automatically, but if you're building on | 242 | an unusual platform, or if you're using remote execution and the execution | 243 | platform is different than the host, you may need to specify this explictly. | 244 +--------------------------------+-----------------------------+---------------------------------------------+ 245 | :param:`goarch` | :type:`string` | :value:`None` | 246 +--------------------------------+-----------------------------+---------------------------------------------+ 247 | The architecture the binaries in the SDK are intended to run on. | 248 | By default, this is detected automatically, but if you're building on | 249 | an unusual platform, or if you're using remote execution and the execution | 250 | platform is different than the host, you may need to specify this explictly. | 251 +--------------------------------+-----------------------------+---------------------------------------------+ 252 | :param:`version` | :type:`string` | :value:`latest Go version` | 253 +--------------------------------+-----------------------------+---------------------------------------------+ 254 | The version of Go to download, for example ``1.12.5``. If unspecified, | 255 | ``go_download_sdk`` will download the latest version of Go that rules_go | 256 | supports. Go versions that rules_go doesn't support may not be specified, | 257 | since the download SHA-256 sums are not known. | 258 +--------------------------------+-----------------------------+---------------------------------------------+ 259 | :param:`urls` | :type:`string_list` | :value:`[https://dl.google.com/go/{}` | 260 +--------------------------------+-----------------------------+---------------------------------------------+ 261 | A list of mirror urls to the binary distribution of a Go SDK. These must contain the `{}` | 262 | used to substitute the sdk filename being fetched (using `.format`. | 263 | It defaults to the official repository :value:`"https://dl.google.com/go/{}"`. | 264 | | 265 | This attribute is seldom used. It is only needed for downloading Go from | 266 | an alternative location (for example, an internal mirror). | 267 +--------------------------------+-----------------------------+---------------------------------------------+ 268 | :param:`strip_prefix` | :type:`string` | :value:`"go"` | 269 +--------------------------------+-----------------------------+---------------------------------------------+ 270 | A directory prefix to strip from the extracted files. | 271 | Used with ``urls``. | 272 +--------------------------------+-----------------------------+---------------------------------------------+ 273 | :param:`sdks` | :type:`string_list_dict` | :value:`see description` | 274 +--------------------------------+-----------------------------+---------------------------------------------+ 275 | This consists of a set of mappings from the host platform tuple to a list of filename and | 276 | sha256 for that file. The filename is combined the :param:`urls` to produce the final download | 277 | urls to use. | 278 | | 279 | This option is seldom used. It is only needed for downloading a modified | 280 | Go distribution (with a different SHA-256 sum) or a version of Go | 281 | not supported by rules_go (for example, a beta or release candidate). | 282 +--------------------------------+-----------------------------+---------------------------------------------+ 283 284 **Example**: 285 286 .. code:: bzl 287 288 load( 289 "@io_bazel_rules_go//go:deps.bzl", 290 "go_download_sdk", 291 "go_register_toolchains", 292 "go_rules_dependencies", 293 ) 294 295 go_download_sdk( 296 name = "go_sdk", 297 goos = "linux", 298 goarch = "amd64", 299 version = "1.12.5", 300 ) 301 302 go_rules_dependencies() 303 304 go_register_toolchains() 305 306 go_host_sdk 307 ~~~~~~~~~~~ 308 309 This detects and configures the host Go SDK for use in toolchains. 310 311 If the ``GOROOT`` environment variable is set, the SDK in that directory is 312 used. Otherwise, ``go env GOROOT`` is used. 313 314 +--------------------------------+-----------------------------+-----------------------------------+ 315 | **Name** | **Type** | **Default value** | 316 +--------------------------------+-----------------------------+-----------------------------------+ 317 | :param:`name` | :type:`string` | |mandatory| | 318 +--------------------------------+-----------------------------+-----------------------------------+ 319 | A unique name for this SDK. This should almost always be :value:`go_sdk` if you want the SDK | 320 | to be used by toolchains. | 321 +--------------------------------+-----------------------------+-----------------------------------+ 322 323 324 go_local_sdk 325 ~~~~~~~~~~~~ 326 327 This prepares a local path to use as the Go SDK in toolchains. 328 329 +--------------------------------+-----------------------------+-----------------------------------+ 330 | **Name** | **Type** | **Default value** | 331 +--------------------------------+-----------------------------+-----------------------------------+ 332 | :param:`name` | :type:`string` | |mandatory| | 333 +--------------------------------+-----------------------------+-----------------------------------+ 334 | A unique name for this SDK. This should almost always be :value:`go_sdk` if you want the SDK | 335 | to be used by toolchains. | 336 +--------------------------------+-----------------------------+-----------------------------------+ 337 | :param:`path` | :type:`string` | :value:`""` | 338 +--------------------------------+-----------------------------+-----------------------------------+ 339 | The local path to a pre-installed Go SDK. The path must contain the go binary, the tools it | 340 | invokes and the standard library sources. | 341 +--------------------------------+-----------------------------+-----------------------------------+ 342 343 344 go_wrap_sdk 345 ~~~~~~~~~~~ 346 347 This configures an SDK that was downloaded or located with another repository 348 rule. 349 350 +--------------------------------+-----------------------------+-----------------------------------+ 351 | **Name** | **Type** | **Default value** | 352 +--------------------------------+-----------------------------+-----------------------------------+ 353 | :param:`name` | :type:`string` | |mandatory| | 354 +--------------------------------+-----------------------------+-----------------------------------+ 355 | A unique name for this SDK. This should almost always be :value:`go_sdk` if you want the SDK | 356 | to be used by toolchains. | 357 +--------------------------------+-----------------------------+-----------------------------------+ 358 | :param:`root_file` | :type:`label` | |mandatory| | 359 +--------------------------------+-----------------------------+-----------------------------------+ 360 | A Bazel label referencing a file in the root directory of the SDK. Used to | 361 | determine the GOROOT for the SDK. | 362 +--------------------------------+-----------------------------+-----------------------------------+ 363 364 **Example:** 365 366 .. code:: bzl 367 368 load( 369 "@io_bazel_rules_go//go:deps.bzl", 370 "go_register_toolchains", 371 "go_rules_dependencies", 372 "go_wrap_sdk", 373 ) 374 375 go_wrap_sdk( 376 name = "go_sdk", 377 root_file = "@other_repo//go:README.md", 378 ) 379 380 go_rules_dependencies() 381 382 go_register_toolchains() 383 384 go_sdk 385 ~~~~~~ 386 387 ``go_sdk`` collects information about a Go SDK. The SDK must have a normal 388 GOROOT directory structure. 389 390 Normally, ``go_sdk`` rules are declared in repositories configured with 391 `go_download_sdk`_, `go_host_sdk`_, `go_local_sdk`_, or `go_wrap_sdk`_. You 392 usually won't need to declare this rule explicitly. 393 394 +--------------------------------+-----------------------------+-----------------------------------+ 395 | **Name** | **Type** | **Default value** | 396 +--------------------------------+-----------------------------+-----------------------------------+ 397 | :param:`name` | :type:`string` | |mandatory| | 398 +--------------------------------+-----------------------------+-----------------------------------+ 399 | A unique name for the SDK rule. Typically ``go_sdk``. | 400 +--------------------------------+-----------------------------+-----------------------------------+ 401 | :param:`goos` | :type:`string` | |mandatory| | 402 +--------------------------------+-----------------------------+-----------------------------------+ 403 | The host operating system the SDK was built for. See `go/platform/list.bzl`_ | 404 | for valid values. | 405 +--------------------------------+-----------------------------+-----------------------------------+ 406 | :param:`goarch` | :type:`string` | |mandatory| | 407 +--------------------------------+-----------------------------+-----------------------------------+ 408 | The host architecture the SDK was built for. See `go/platform/list.bzl`_ | 409 | for valid values. | 410 +--------------------------------+-----------------------------+-----------------------------------+ 411 | :param:`root_file` | :type:`label` | |mandatory| | 412 +--------------------------------+-----------------------------+-----------------------------------+ 413 | A file in the SDK root directory. Used to determine GOROOT. | 414 +--------------------------------+-----------------------------+-----------------------------------+ 415 | :param:`package_list` | :type:`label` | :value:`None` | 416 +--------------------------------+-----------------------------+-----------------------------------+ 417 | A text file containing a list of packages in the standard library that may | 418 | be imported. If unspecified, this will be generated from ``srcs``. | 419 +--------------------------------+-----------------------------+-----------------------------------+ 420 | :param:`libs` | :type:`label_list` | :value:`[]` | 421 +--------------------------------+-----------------------------+-----------------------------------+ 422 | Pre-compiled .a files for the standard library, built for the execution | 423 | platform. | 424 +--------------------------------+-----------------------------+-----------------------------------+ 425 | :param:`headers` | :type:`label_list` | :value:`[]` | 426 +--------------------------------+-----------------------------+-----------------------------------+ 427 | .h files from pkg/include that may be included in assembly sources. | 428 +--------------------------------+-----------------------------+-----------------------------------+ 429 | :param:`srcs` | :type:`label_list` | :value:`[]` | 430 +--------------------------------+-----------------------------+-----------------------------------+ 431 | Source files for packages in the standard library. | 432 +--------------------------------+-----------------------------+-----------------------------------+ 433 | :param:`tools` | :type:`label_list` | :value:`[]` | 434 +--------------------------------+-----------------------------+-----------------------------------+ 435 | Executable files from pkg/tool, built for the execution platform. | 436 +--------------------------------+-----------------------------+-----------------------------------+ 437 | :param:`go` | :type:`label` | |mandatory| | 438 +--------------------------------+-----------------------------+-----------------------------------+ 439 | The go binary. | 440 +--------------------------------+-----------------------------+-----------------------------------+ 441 442 go_toolchain 443 ~~~~~~~~~~~~ 444 445 This declares a toolchain that may be used with toolchain type 446 :value:`"@io_bazel_rules_go//go:toolchain"`. 447 448 Normally, ``go_toolchain`` rules are declared and registered in repositories 449 configured with `go_download_sdk`_, `go_host_sdk`_, `go_local_sdk`_, or 450 `go_wrap_sdk`_. You usually won't need to declare these explicitly. 451 452 +--------------------------------+-----------------------------+-----------------------------------+ 453 | **Name** | **Type** | **Default value** | 454 +--------------------------------+-----------------------------+-----------------------------------+ 455 | :param:`name` | :type:`string` | |mandatory| | 456 +--------------------------------+-----------------------------+-----------------------------------+ 457 | A unique name for the toolchain. | 458 +--------------------------------+-----------------------------+-----------------------------------+ 459 | :param:`goos` | :type:`string` | |mandatory| | 460 +--------------------------------+-----------------------------+-----------------------------------+ 461 | The target operating system. Must be a standard ``GOOS`` value. | 462 +--------------------------------+-----------------------------+-----------------------------------+ 463 | :param:`goarch` | :type:`string` | |mandatory| | 464 +--------------------------------+-----------------------------+-----------------------------------+ 465 | The target architecture. Must be a standard ``GOARCH`` value. | 466 +--------------------------------+-----------------------------+-----------------------------------+ 467 | :param:`sdk` | :type:`label` | |mandatory| | 468 +--------------------------------+-----------------------------+-----------------------------------+ 469 | The SDK this toolchain is based on. The target must provide `GoSDK`_. This is | 470 | usually a `go_sdk`_ rule. | 471 +--------------------------------+-----------------------------+-----------------------------------+ 472 | :param:`link_flags` | :type:`string_list` | :value:`[]` | 473 +--------------------------------+-----------------------------+-----------------------------------+ 474 | Flags passed to the Go external linker. | 475 +--------------------------------+-----------------------------+-----------------------------------+ 476 | :param:`cgo_link_flags` | :type:`string_list` | :value:`[]` | 477 +--------------------------------+-----------------------------+-----------------------------------+ 478 | Flags passed to the external linker (if it is used). | 479 +--------------------------------+-----------------------------+-----------------------------------+ 480 481 go_context 482 ~~~~~~~~~~ 483 484 This collects the information needed to form and return a :type:`GoContext` from 485 a rule ctx. It uses the attributes and the toolchains. It can only be used in 486 the implementation of a rule that has the go toolchain attached and the go 487 context data as an attribute. To do this declare the rule using the go_rule 488 wrapper. 489 490 .. code:: bzl 491 492 def _my_rule_impl(ctx): 493 go = go_context(ctx) 494 ... 495 496 my_rule = go_rule( 497 _my_rule_impl, 498 attrs = { 499 ... 500 }, 501 ) 502 503 504 +--------------------------------+-----------------------------+-----------------------------------+ 505 | **Name** | **Type** | **Default value** | 506 +--------------------------------+-----------------------------+-----------------------------------+ 507 | :param:`ctx` | :type:`ctx` | |mandatory| | 508 +--------------------------------+-----------------------------+-----------------------------------+ 509 | The Bazel ctx object for the current rule. | 510 +--------------------------------+-----------------------------+-----------------------------------+ 511 512 The context object 513 ~~~~~~~~~~~~~~~~~~ 514 515 ``GoContext`` is never returned by a rule, instead you build one using 516 ``go_context(ctx)`` in the top of any custom skylark rule that wants to interact 517 with the go rules. It provides all the information needed to create go actions, 518 and create or interact with the other go providers. 519 520 When you get a ``GoContext`` from a context it exposes a number of fields 521 and methods. 522 523 All methods take the ``GoContext`` as the only positional argument. All other 524 arguments must be passed as keyword arguments. This allows us to re-order and 525 deprecate individual parameters over time. 526 527 Fields 528 ^^^^^^ 529 530 +--------------------------------+-----------------------------------------------------------------+ 531 | **Name** | **Type** | 532 +--------------------------------+-----------------------------------------------------------------+ 533 | :param:`toolchain` | :type:`ToolchainInfo` | 534 +--------------------------------+-----------------------------------------------------------------+ 535 | The underlying toolchain. This should be considered an opaque type subject to change. | 536 +--------------------------------+-----------------------------------------------------------------+ 537 | :param:`sdk` | :type:`GoSDK` | 538 +--------------------------------+-----------------------------------------------------------------+ 539 | The SDK in use. This may be used to access sources, packages, and tools. | 540 +--------------------------------+-----------------------------------------------------------------+ 541 | :param:`mode` | :type:`Mode` | 542 +--------------------------------+-----------------------------------------------------------------+ 543 | Controls the compilation setup affecting things like enabling profilers and sanitizers. | 544 | See `compilation modes`_ for more information about the allowed values. | 545 +--------------------------------+-----------------------------------------------------------------+ 546 | :param:`root` | :type:`string` | 547 +--------------------------------+-----------------------------------------------------------------+ 548 | Path of the effective GOROOT. If :param:`stdlib` is set, this is the same | 549 | as ``go.stdlib.root_file.dirname``. Otherwise, this is the same as | 550 | ``go.sdk.root_file.dirname``. | 551 +--------------------------------+-----------------------------------------------------------------+ 552 | :param:`go` | :type:`File` | 553 +--------------------------------+-----------------------------------------------------------------+ 554 | The main "go" binary used to run go sdk tools. | 555 +--------------------------------+-----------------------------------------------------------------+ 556 | :param:`stdlib` | :type:`GoStdLib` | 557 +--------------------------------+-----------------------------------------------------------------+ 558 | The standard library and tools to use in this build mode. This may be the | 559 | pre-compiled standard library that comes with the SDK, or it may be compiled | 560 | in a different directory for this mode. | 561 +--------------------------------+-----------------------------------------------------------------+ 562 | :param:`actions` | :type:`ctx.actions` | 563 +--------------------------------+-----------------------------------------------------------------+ 564 | The actions structure from the Bazel context, which has all the methods for building new | 565 | bazel actions. | 566 +--------------------------------+-----------------------------------------------------------------+ 567 | :param:`exe_extension` | :type:`string` | 568 +--------------------------------+-----------------------------------------------------------------+ 569 | The suffix to use for all executables in this build mode. Mostly used when generating the output | 570 | filenames of binary rules. | 571 +--------------------------------+-----------------------------------------------------------------+ 572 | :param:`shared_extension` | :type:`string` | 573 +--------------------------------+-----------------------------------------------------------------+ 574 | The suffix to use for shared libraries in this build mode. Mostly used when | 575 | generating output filenames of binary rules. | 576 +--------------------------------+-----------------------------------------------------------------+ 577 | :param:`crosstool` | :type:`list of File` | 578 +--------------------------------+-----------------------------------------------------------------+ 579 | The files you need to add to the inputs of an action in order to use the cc toolchain. | 580 +--------------------------------+-----------------------------------------------------------------+ 581 | :param:`package_list` | :type:`File` | 582 +--------------------------------+-----------------------------------------------------------------+ 583 | A file that contains the package list of the standard library. | 584 +--------------------------------+-----------------------------------------------------------------+ 585 | :param:`env` | :type:`dict of string to string` | 586 +--------------------------------+-----------------------------------------------------------------+ 587 | Environment variables to pass to actions. Includes ``GOARCH``, ``GOOS``, | 588 | ``GOROOT``, ``GOROOT_FINAL``, ``CGO_ENABLED``, and ``PATH``. | 589 +--------------------------------+-----------------------------------------------------------------+ 590 | :param:`tags` | :type:`list of string` | 591 +--------------------------------+-----------------------------------------------------------------+ 592 | List of build tags used to filter source files. | 593 +--------------------------------+-----------------------------------------------------------------+ 594 595 Methods 596 ^^^^^^^ 597 598 * Action generators 599 600 * archive_ 601 * asm_ 602 * binary_ 603 * compile_ 604 * cover_ 605 * link_ 606 * pack_ 607 608 * Helpers 609 610 * args_ 611 * `declare_file`_ 612 * `library_to_source`_ 613 * `new_library`_ 614 615 616 archive 617 +++++++ 618 619 This emits actions to compile Go code into an archive. It supports embedding, 620 cgo dependencies, coverage, and assembling and packing .s files. 621 622 It returns a GoArchive_. 623 624 +--------------------------------+-----------------------------+-----------------------------------+ 625 | **Name** | **Type** | **Default value** | 626 +--------------------------------+-----------------------------+-----------------------------------+ 627 | :param:`go` | :type:`GoContext` | |mandatory| | 628 +--------------------------------+-----------------------------+-----------------------------------+ 629 | This must be the same GoContext object you got this function from. | 630 +--------------------------------+-----------------------------+-----------------------------------+ 631 | :param:`source` | :type:`GoSource` | |mandatory| | 632 +--------------------------------+-----------------------------+-----------------------------------+ 633 | The GoSource_ that should be compiled into an archive. | 634 +--------------------------------+-----------------------------+-----------------------------------+ 635 636 637 asm 638 +++ 639 640 The asm function adds an action that runs ``go tool asm`` on a source file to 641 produce an object, and returns the File of that object. 642 643 +--------------------------------+-----------------------------+-----------------------------------+ 644 | **Name** | **Type** | **Default value** | 645 +--------------------------------+-----------------------------+-----------------------------------+ 646 | :param:`go` | :type:`GoContext` | |mandatory| | 647 +--------------------------------+-----------------------------+-----------------------------------+ 648 | This must be the same GoContext object you got this function from. | 649 +--------------------------------+-----------------------------+-----------------------------------+ 650 | :param:`source` | :type:`File` | |mandatory| | 651 +--------------------------------+-----------------------------+-----------------------------------+ 652 | A source code artifact to assemble. | 653 | This must be a ``.s`` file that contains code in the platform neutral `go assembly`_ language. | 654 +--------------------------------+-----------------------------+-----------------------------------+ 655 | :param:`hdrs` | :type:`File iterable` | :value:`[]` | 656 +--------------------------------+-----------------------------+-----------------------------------+ 657 | The list of .h files that may be included by the source. | 658 +--------------------------------+-----------------------------+-----------------------------------+ 659 660 661 binary 662 ++++++ 663 664 This emits actions to compile and link Go code into a binary. It supports 665 embedding, cgo dependencies, coverage, and assembling and packing .s files. 666 667 It returns a tuple containing GoArchive_, the output executable file, and 668 a ``runfiles`` object. 669 670 +--------------------------------+-----------------------------+-----------------------------------+ 671 | **Name** | **Type** | **Default value** | 672 +--------------------------------+-----------------------------+-----------------------------------+ 673 | :param:`go` | :type:`GoContext` | |mandatory| | 674 +--------------------------------+-----------------------------+-----------------------------------+ 675 | This must be the same GoContext object you got this function from. | 676 +--------------------------------+-----------------------------+-----------------------------------+ 677 | :param:`name` | :type:`string` | :value:`""` | 678 +--------------------------------+-----------------------------+-----------------------------------+ 679 | The base name of the generated binaries. Required if :param:`executable` is not given. | 680 +--------------------------------+-----------------------------+-----------------------------------+ 681 | :param:`source` | :type:`GoSource` | |mandatory| | 682 +--------------------------------+-----------------------------+-----------------------------------+ 683 | The GoSource_ that should be compiled and linked. | 684 +--------------------------------+-----------------------------+-----------------------------------+ 685 | :param:`test_archives` | :type:`list GoArchiveData` | :value:`[]` | 686 +--------------------------------+-----------------------------+-----------------------------------+ 687 | List of archives for libraries under test. See link_. | 688 +--------------------------------+-----------------------------+-----------------------------------+ 689 | :param:`gc_linkopts` | :type:`string_list` | :value:`[]` | 690 +--------------------------------+-----------------------------+-----------------------------------+ 691 | Go link options. | 692 +--------------------------------+-----------------------------+-----------------------------------+ 693 | :param:`version_file` | :type:`File` | :value:`None` | 694 +--------------------------------+-----------------------------+-----------------------------------+ 695 | Version file used for link stamping. See link_. | 696 +--------------------------------+-----------------------------+-----------------------------------+ 697 | :param:`info_file` | :type:`File` | :value:`None` | 698 +--------------------------------+-----------------------------+-----------------------------------+ 699 | Info file used for link stamping. See link_. | 700 +--------------------------------+-----------------------------+-----------------------------------+ 701 | :param:`executable` | :type:`File` | :value:`None` | 702 +--------------------------------+-----------------------------+-----------------------------------+ 703 | Optional output file to write. If not set, ``binary`` will generate an output | 704 | file name based on ``name``, the target platform, and the link mode. | 705 +--------------------------------+-----------------------------+-----------------------------------+ 706 707 compile 708 +++++++ 709 710 The compile function adds an action that compiles a list of source files into 711 a package archive (.a file). 712 713 It does not return anything. 714 715 +--------------------------------+-----------------------------+-----------------------------------+ 716 | **Name** | **Type** | **Default value** | 717 +--------------------------------+-----------------------------+-----------------------------------+ 718 | :param:`go` | :type:`GoContext` | |mandatory| | 719 +--------------------------------+-----------------------------+-----------------------------------+ 720 | This must be the same GoContext object you got this function from. | 721 +--------------------------------+-----------------------------+-----------------------------------+ 722 | :param:`sources` | :type:`File iterable` | |mandatory| | 723 +--------------------------------+-----------------------------+-----------------------------------+ 724 | An iterable of source code artifacts. | 725 | These must be pure .go files, no assembly or cgo is allowed. | 726 +--------------------------------+-----------------------------+-----------------------------------+ 727 | :param:`importpath` | :type:`string` | :value:`""` | 728 +--------------------------------+-----------------------------+-----------------------------------+ 729 | The import path this package represents. This is passed to the -p flag. When the actual import | 730 | path is different than the source import path (i.e., when ``importmap`` is set in a | 731 | ``go_library`` rule), this should be the actual import path. | 732 +--------------------------------+-----------------------------+-----------------------------------+ 733 | :param:`archives` | :type:`GoArchive iterable` | :value:`[]` | 734 +--------------------------------+-----------------------------+-----------------------------------+ 735 | An iterable of all directly imported libraries. | 736 | The action will verify that all directly imported libraries were supplied, not allowing | 737 | transitive dependencies to satisfy imports. It will not check that all supplied libraries were | 738 | used though. | 739 +--------------------------------+-----------------------------+-----------------------------------+ 740 | :param:`out_lib` | :type:`File` | |mandatory| | 741 +--------------------------------+-----------------------------+-----------------------------------+ 742 | The archive file that should be produced. | 743 +--------------------------------+-----------------------------+-----------------------------------+ 744 | :param:`out_export` | :type:`File` | :value:`None` | 745 +--------------------------------+-----------------------------+-----------------------------------+ 746 | File where extra information about the package may be stored. This is used | 747 | by nogo to store serialized facts about definitions. In the future, it may | 748 | be used to store export data (instead of the .a file). | 749 +--------------------------------+-----------------------------+-----------------------------------+ 750 | :param:`gc_goopts` | :type:`string_list` | :value:`[]` | 751 +--------------------------------+-----------------------------+-----------------------------------+ 752 | Additional flags to pass to the compiler. | 753 +--------------------------------+-----------------------------+-----------------------------------+ 754 | :param:`testfilter` | :type:`string` | :value:`"off"` | 755 +--------------------------------+-----------------------------+-----------------------------------+ 756 | Controls how files with a ``_test`` suffix are filtered. | 757 | | 758 | * ``"off"`` - files with and without a ``_test`` suffix are compiled. | 759 | * ``"only"`` - only files with a ``_test`` suffix are compiled. | 760 | * ``"exclude"`` - only files without a ``_test`` suffix are compiled. | 761 +--------------------------------+-----------------------------+-----------------------------------+ 762 | :param:`asmhdr` | :type:`File` | :value:`None` | 763 +--------------------------------+-----------------------------+-----------------------------------+ 764 | If provided, the compiler will write an assembly header to this file. | 765 +--------------------------------+-----------------------------+-----------------------------------+ 766 767 768 cover 769 +++++ 770 771 The cover function adds an action that runs ``go tool cover`` on a set of source 772 files to produce copies with cover instrumentation. 773 774 Returns a covered GoSource_ with the required source files process for coverage. 775 776 Note that this removes most comments, including cgo comments. 777 778 +--------------------------------+-----------------------------+-----------------------------------+ 779 | **Name** | **Type** | **Default value** | 780 +--------------------------------+-----------------------------+-----------------------------------+ 781 | :param:`go` | :type:`GoContext` | |mandatory| | 782 +--------------------------------+-----------------------------+-----------------------------------+ 783 | This must be the same GoContext object you got this function from. | 784 +--------------------------------+-----------------------------+-----------------------------------+ 785 | :param:`source` | :type:`GoSource` | |mandatory| | 786 +--------------------------------+-----------------------------+-----------------------------------+ 787 | The source object to process. Any source files in the object that have been marked as needing | 788 | coverage will be processed and substiuted in the returned GoSource. | 789 +--------------------------------+-----------------------------+-----------------------------------+ 790 791 792 link 793 ++++ 794 795 The link function adds an action that runs ``go tool link`` on a library. 796 797 It does not return anything. 798 799 +--------------------------------+-----------------------------+-----------------------------------+ 800 | **Name** | **Type** | **Default value** | 801 +--------------------------------+-----------------------------+-----------------------------------+ 802 | :param:`go` | :type:`GoContext` | |mandatory| | 803 +--------------------------------+-----------------------------+-----------------------------------+ 804 | This must be the same GoContext object you got this function from. | 805 +--------------------------------+-----------------------------+-----------------------------------+ 806 | :param:`archive` | :type:`GoArchive` | |mandatory| | 807 +--------------------------------+-----------------------------+-----------------------------------+ 808 | The library to link. | 809 +--------------------------------+-----------------------------+-----------------------------------+ 810 | :param:`test_archives` | :type:`GoArchiveData list` | :value:`[]` | 811 +--------------------------------+-----------------------------+-----------------------------------+ 812 | List of archives for libraries under test. These are excluded from linking | 813 | if transitive dependencies of :param:`archive` have the same package paths. | 814 | This is useful for linking external test archives that depend internal test | 815 | archives. | 816 +--------------------------------+-----------------------------+-----------------------------------+ 817 | :param:`executable` | :type:`File` | |mandatory| | 818 +--------------------------------+-----------------------------+-----------------------------------+ 819 | The binary to produce. | 820 +--------------------------------+-----------------------------+-----------------------------------+ 821 | :param:`gc_linkopts` | :type:`string_list` | :value:`[]` | 822 +--------------------------------+-----------------------------+-----------------------------------+ 823 | Basic link options, these may be adjusted by the :param:`mode`. | 824 +--------------------------------+-----------------------------+-----------------------------------+ 825 | :param:`version_file` | :type:`File` | :value:`None` | 826 +--------------------------------+-----------------------------+-----------------------------------+ 827 | Version file used for link stamping. | 828 +--------------------------------+-----------------------------+-----------------------------------+ 829 | :param:`info_file` | :type:`File` | :value:`None` | 830 +--------------------------------+-----------------------------+-----------------------------------+ 831 | Info file used for link stamping. | 832 +--------------------------------+-----------------------------+-----------------------------------+ 833 834 pack 835 ++++ 836 837 The pack function adds an action that produces an archive from a base archive 838 and a collection of additional object files. 839 840 It does not return anything. 841 842 +--------------------------------+-----------------------------+-----------------------------------+ 843 | **Name** | **Type** | **Default value** | 844 +--------------------------------+-----------------------------+-----------------------------------+ 845 | :param:`go` | :type:`GoContext` | |mandatory| | 846 +--------------------------------+-----------------------------+-----------------------------------+ 847 | This must be the same GoContext object you got this function from. | 848 +--------------------------------+-----------------------------+-----------------------------------+ 849 | :param:`in_lib` | :type:`File` | |mandatory| | 850 +--------------------------------+-----------------------------+-----------------------------------+ 851 | The archive that should be copied and appended to. | 852 | This must always be an archive in the common ar form (like that produced by the go compiler). | 853 +--------------------------------+-----------------------------+-----------------------------------+ 854 | :param:`out_lib` | :type:`File` | |mandatory| | 855 +--------------------------------+-----------------------------+-----------------------------------+ 856 | The archive that should be produced. | 857 | This will always be an archive in the common ar form (like that produced by the go compiler). | 858 +--------------------------------+-----------------------------+-----------------------------------+ 859 | :param:`objects` | :type:`File iterable` | :value:`()` | 860 +--------------------------------+-----------------------------+-----------------------------------+ 861 | An iterable of object files to be added to the output archive file. | 862 +--------------------------------+-----------------------------+-----------------------------------+ 863 | :param:`archives` | :type:`list of File` | :value:`[]` | 864 +--------------------------------+-----------------------------+-----------------------------------+ 865 | Additional archives whose objects will be appended to the output. | 866 | These can be ar files in either common form or either the bsd or sysv variations. | 867 +--------------------------------+-----------------------------+-----------------------------------+ 868 869 args 870 ++++ 871 872 This creates a new Args_ object, using the ``ctx.actions.args`` method. The 873 object is pre-populated with standard arguments used by all the go toolchain 874 builders. 875 876 +--------------------------------+-----------------------------+-----------------------------------+ 877 | **Name** | **Type** | **Default value** | 878 +--------------------------------+-----------------------------+-----------------------------------+ 879 | :param:`go` | :type:`GoContext` | |mandatory| | 880 +--------------------------------+-----------------------------+-----------------------------------+ 881 | This must be the same GoContext object you got this function from. | 882 +--------------------------------+-----------------------------+-----------------------------------+ 883 884 declare_file 885 ++++++++++++ 886 887 This is the equivalent of ``ctx.actions.declare_file``. It uses the 888 current build mode to make the filename unique between configurations. 889 890 +--------------------------------+-----------------------------+-----------------------------------+ 891 | **Name** | **Type** | **Default value** | 892 +--------------------------------+-----------------------------+-----------------------------------+ 893 | :param:`go` | :type:`GoContext` | |mandatory| | 894 +--------------------------------+-----------------------------+-----------------------------------+ 895 | This must be the same GoContext object you got this function from. | 896 +--------------------------------+-----------------------------+-----------------------------------+ 897 | :param:`path` | :type:`string` | :value:`""` | 898 +--------------------------------+-----------------------------+-----------------------------------+ 899 | A path for this file, including the basename of the file. | 900 +--------------------------------+-----------------------------+-----------------------------------+ 901 | :param:`ext` | :type:`string` | :value:`""` | 902 +--------------------------------+-----------------------------+-----------------------------------+ 903 | The extension to use for the file. | 904 +--------------------------------+-----------------------------+-----------------------------------+ 905 | :param:`name` | :type:`string` | :value:`""` | 906 +--------------------------------+-----------------------------+-----------------------------------+ 907 | A name to use for this file. If path is not present, this becomes a prefix to the path. | 908 | If this is not set, the current rule name is used in it's place. | 909 +--------------------------------+-----------------------------+-----------------------------------+ 910 911 library_to_source 912 +++++++++++++++++ 913 914 This is used to build a GoSource object for a given GoLibrary in the current 915 build mode. 916 917 +--------------------------------+-----------------------------+-----------------------------------+ 918 | **Name** | **Type** | **Default value** | 919 +--------------------------------+-----------------------------+-----------------------------------+ 920 | :param:`go` | :type:`GoContext` | |mandatory| | 921 +--------------------------------+-----------------------------+-----------------------------------+ 922 | This must be the same GoContext object you got this function from. | 923 +--------------------------------+-----------------------------+-----------------------------------+ 924 | :param:`attr` | :type:`ctx.attr` | |mandatory| | 925 +--------------------------------+-----------------------------+-----------------------------------+ 926 | The attributes of the rule being processed. In a normal rule implementation this would be | 927 | ctx.attr. | 928 +--------------------------------+-----------------------------+-----------------------------------+ 929 | :param:`library` | :type:`GoLibrary` | |mandatory| | 930 +--------------------------------+-----------------------------+-----------------------------------+ 931 | The GoLibrary_ that you want to build a GoSource_ object for in the current build mode. | 932 +--------------------------------+-----------------------------+-----------------------------------+ 933 | :param:`coverage_instrumented` | :type:`bool` | |mandatory| | 934 +--------------------------------+-----------------------------+-----------------------------------+ 935 | This controls whether cover is enabled for this specific library in this mode. | 936 | This should generally be the value of ctx.coverage_instrumented() | 937 +--------------------------------+-----------------------------+-----------------------------------+ 938 939 new_library 940 +++++++++++ 941 942 This creates a new GoLibrary. You can add extra fields to the go library by 943 providing extra named parameters to this function, they will be visible to the 944 resolver when it is invoked. 945 946 +--------------------------------+-----------------------------+-----------------------------------+ 947 | **Name** | **Type** | **Default value** | 948 +--------------------------------+-----------------------------+-----------------------------------+ 949 | :param:`go` | :type:`GoContext` | |mandatory| | 950 +--------------------------------+-----------------------------+-----------------------------------+ 951 | This must be the same GoContext object you got this function from. | 952 +--------------------------------+-----------------------------+-----------------------------------+ 953 | :param:`resolver` | :type:`function` | :value:`None` | 954 +--------------------------------+-----------------------------+-----------------------------------+ 955 | This is the function that gets invoked when converting from a GoLibrary to a GoSource. | 956 | The function's signature must be | 957 | | 958 | .. code:: bzl | 959 | | 960 | def _testmain_library_to_source(go, attr, source, merge) | 961 | | 962 | attr is the attributes of the rule being processed | 963 | source is the dictionary of GoSource fields being generated | 964 | merge is a helper you can call to merge | 965 +--------------------------------+-----------------------------+-----------------------------------+ 966 | :param:`importable` | :type:`bool` | |mandatory| | 967 +--------------------------------+-----------------------------+-----------------------------------+ 968 | This controls whether the GoLibrary_ is supposed to be importable. This is generally only false | 969 | for the "main" libraries that are built just before linking. | 970 +--------------------------------+-----------------------------+-----------------------------------+ 971 972 go_rule 973 ~~~~~~~ 974 975 ``go_rule`` is a wrapper for the ``rule`` function. It's used to declare rules 976 that have access to the Go toolchain and SDK. 977 978 **Example:** 979 980 .. code:: bzl 981 982 def _my_rule_impl(ctx): 983 go = go_context(ctx) 984 ... 985 986 my_rule = go_rule( 987 _my_rule_impl, 988 attrs = { 989 ... 990 }, 991 ) 992 993 +--------------------------------+-----------------------------+-----------------------------------+ 994 | **Name** | **Type** | **Default value** | 995 +--------------------------------+-----------------------------+-----------------------------------+ 996 | :param:`implementation` | :type:`function` | |mandatory| | 997 +--------------------------------+-----------------------------+-----------------------------------+ 998 | The implementation function for the rule. | 999 +--------------------------------+-----------------------------+-----------------------------------+ 1000 | :param:`attrs` | :type:`dict` | :value:`{}` | 1001 +--------------------------------+-----------------------------+-----------------------------------+ 1002 | Attributes the rule accepts. Additional implicit attributes may be added | 1003 | to this list. | 1004 +--------------------------------+-----------------------------+-----------------------------------+ 1005 | :param:`toolchains` | :type:`list` | See below | 1006 +--------------------------------+-----------------------------+-----------------------------------+ 1007 | List of toolchains types that Bazel should select when invoking this rule. | 1008 | ``"@io_bazel_rules_go//go:toolchain"`` is automatically added to this list, | 1009 | so that does not need to be specified explicitly. | 1010 +--------------------------------+-----------------------------+-----------------------------------+