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