1Go providers
2============
3
4.. _providers: https://docs.bazel.build/versions/master/skylark/rules.html#providers
5
6.. _go_library: /docs/go/core/rules.md#go_library
7.. _go_binary: /docs/go/core/rules.md#go_binary
8.. _go_test: /docs/go/core/rules.md#go_test
9.. _go_path: /docs/go/core/rules.md#go_path
10.. _cc_library: https://docs.bazel.build/versions/master/be/c-cpp.html#cc_library
11.. _flatbuffers: http://google.github.io/flatbuffers/
12.. _static linking: modes.rst#building-static-binaries
13.. _race detector: modes.rst#using-the-race-detector
14.. _runfiles: https://docs.bazel.build/versions/master/skylark/lib/runfiles.html
15.. _File: https://docs.bazel.build/versions/master/skylark/lib/File.html
16.. _new_library: toolchains.rst#new_library
17.. _library_to_source: toolchains.rst#library_to_source
18.. _archive: toolchains.rst#archive
19
20.. role:: param(kbd)
21.. role:: type(emphasis)
22.. role:: value(code)
23.. |mandatory| replace:: **mandatory value**
24
25
26The providers_ are the outputs of the rules. You generaly get them by having a
27dependency on a rule, and then asking for a provider of a specific type.
28
29.. contents:: :depth: 2
30
31-----
32
33Design
34------
35
36The Go providers are designed primarily for the efficiency of the Go rules. The
37information they share is mostly there because it is required for the core rules
38to work.
39
40All the providers are designed to hold only immutable data. This is partly
41because its a cleaner design choice to be able to assume a provider will never
42change, but also because only immutable objects are allowed to be stored in a
43depset, and it's really useful to have depsets of providers. Specifically the
44:param:`direct` and :param:`transitive` fields on GoLibrary_ only work because
45it is immutable.
46
47API
48---
49
50GoLibrary
51~~~~~~~~~
52
53``GoLibrary`` contains metadata about an individual library. It is provided
54by the `go_library`_ rule and other compatible rules. In general, you should
55build ``GoLibrary`` with the `new_library`_ helper method. ``GoLibrary`` is
56an input to the `library_to_source`_ helper method, which produces GoSource_.
57
58+--------------------------------+-----------------------------------------------------------------+
59| **Name** | **Type** |
60+--------------------------------+-----------------------------------------------------------------+
61| :param:`name` | :type:`string` |
62+--------------------------------+-----------------------------------------------------------------+
63| The name of the library. Usually, this is the ``name`` attribute. |
64+--------------------------------+-----------------------------------------------------------------+
65| :param:`label` | :type:`Label` |
66+--------------------------------+-----------------------------------------------------------------+
67| The full label for the library. |
68+--------------------------------+-----------------------------------------------------------------+
69| :param:`importpath` | :type:`string` |
70+--------------------------------+-----------------------------------------------------------------+
71| The string used in ``import`` declarations in Go source code to import |
72| this library. Usually, this is the ``importpath`` attribute. |
73+--------------------------------+-----------------------------------------------------------------+
74| :param:`importmap` | :type:`string` |
75+--------------------------------+-----------------------------------------------------------------+
76| The package path for this library. The Go compiler and linker internally refer |
77| to the library using this string. It must be unique in any binary the library |
78| is linked into. This is usually the same as ``importpath``, but it may be |
79| different, especially for vendored libraries. |
80+--------------------------------+-----------------------------------------------------------------+
81| :param:`pathtype` | :type:`string` |
82+--------------------------------+-----------------------------------------------------------------+
83| Information about the source of the importpath. Possible values are: |
84| |
85| :value:`explicit` |
86| The importpath was explicitly supplied by the user and the library is importable. |
87| This is the normal case. |
88| :value:`inferred` |
89| The importpath was inferred from the directory structure and rule name. The library may be |
90| importable. |
91| This is normally true for rules that do not expect to be compiled directly to a library, |
92| embeded into another rule instead (source generators) |
93| :value:`export` |
94| The importpath was explicitly supplied by the user, but the library is |
95| not importable. This is the case for binaries and tests. The importpath |
96| may still be useful for `go_path`_ and other rules. |
97+--------------------------------+-----------------------------------------------------------------+
98| :param:`resolve` | :type:`function (optional)` |
99+--------------------------------+-----------------------------------------------------------------+
100| A function called by `library_to_source`_ that can be used to resolve this |
101| library to a mode-specific GoSource_. |
102+--------------------------------+-----------------------------------------------------------------+
103| :param:`is_main` | :type:`bool` |
104+--------------------------------+-----------------------------------------------------------------+
105| Indicates whether the library should be compiled as a `main` package. |
106| `main` packages may have arbitrary `importpath` and `importmap` values, |
107| but the compiler and linker must see them as `main`. |
108+--------------------------------+-----------------------------------------------------------------+
109
110GoSource
111~~~~~~~~
112
113GoSource represents a GoLibrary_ after mode-specific processing, ready to build
114a GoArchive_. This is produced by calling the `library_to_source`_ helper
115method. In general, only rules_go should need to build or handle these.
116
117+--------------------------------+-----------------------------------------------------------------+
118| **Name** | **Type** |
119+--------------------------------+-----------------------------------------------------------------+
120| :param:`library` | :type:`GoLibrary` |
121+--------------------------------+-----------------------------------------------------------------+
122| The go library that this GoSource was generated from. |
123+--------------------------------+-----------------------------------------------------------------+
124| :param:`mode` | :type:`Mode` |
125+--------------------------------+-----------------------------------------------------------------+
126| The mode this library is being built for. |
127+--------------------------------+-----------------------------------------------------------------+
128| :param:`srcs` | :type:`list of File` |
129+--------------------------------+-----------------------------------------------------------------+
130| The sources to compile into the archive. |
131+--------------------------------+-----------------------------------------------------------------+
132| :param:`orig_srcs` | :type:`list of File` |
133+--------------------------------+-----------------------------------------------------------------+
134| The original source files this library is based on. This may differ from |
135| :param:`srcs` if processing tools such as cgo or cover are applied. |
136+--------------------------------+-----------------------------------------------------------------+
137| :param:`orig_src_map` | :type:`dict of File to File` |
138+--------------------------------+-----------------------------------------------------------------+
139| Maps generated files in :param:`srcs` back to :param:`orig_srcs`. Not all |
140| generated files may appear in here. |
141+--------------------------------+-----------------------------------------------------------------+
142| :param:`embedsrcs` | :type:`list of File` |
143+--------------------------------+-----------------------------------------------------------------+
144| Files that may be embedded into the compiled package using ``//go:embed`` |
145| directives. All files must be in the same logical directory or a subdirectory |
146| as source files. However, it's okay to mix static and generated source files |
147| and static and generated embeddable files. |
148+--------------------------------+-----------------------------------------------------------------+
149| :param:`cover` | :type:`list of File` |
150+--------------------------------+-----------------------------------------------------------------+
151| List of source files to instrument for code coverage. |
152+--------------------------------+-----------------------------------------------------------------+
153| :param:`x_defs` | :type:`string_dict` |
154+--------------------------------+-----------------------------------------------------------------+
155| Map of defines to add to the go link command. |
156+--------------------------------+-----------------------------------------------------------------+
157| :param:`deps` | :type:`list of Target` |
158+--------------------------------+-----------------------------------------------------------------+
159| The direct dependencies needed by this library. |
160+--------------------------------+-----------------------------------------------------------------+
161| :param:`gc_goopts` | :type:`list of string` |
162+--------------------------------+-----------------------------------------------------------------+
163| Go compilation options that should be used when compiling these sources. |
164| In general these will be used for *all* sources of any library this provider is embedded into. |
165+--------------------------------+-----------------------------------------------------------------+
166| :param:`runfiles` | :type:`Runfiles` |
167+--------------------------------+-----------------------------------------------------------------+
168| The set of files needed by code in these sources at runtime. |
169+--------------------------------+-----------------------------------------------------------------+
170| :param:`cgo` | :type:`bool` |
171+--------------------------------+-----------------------------------------------------------------+
172| True if the library may contain cgo sources or C/C++/ObjC sources. |
173| If true and cgo is enabled, cgo sources will be processed with cgo, and |
174| C/C++/ObjC will be compiled with the appropriate toolchain and packed into |
175| the final archive. If true and cgo is disabled, cgo sources are filtered |
176| out, and sources with ``// +build !cgo`` are included. |
177+--------------------------------+-----------------------------------------------------------------+
178| :param:`cdeps` | :type:`list of Target` |
179+--------------------------------+-----------------------------------------------------------------+
180| List of ``cc_library`` and ``objc_library`` targets this library depends on. |
181+--------------------------------+-----------------------------------------------------------------+
182| :param:`cppopts` | :type:`list of string` |
183+--------------------------------+-----------------------------------------------------------------+
184| List of additional flags to pass to the C preprocessor when invoking the |
185| C/C++/ObjC compilers. |
186+--------------------------------+-----------------------------------------------------------------+
187| :param:`copts` | :type:`list of string` |
188+--------------------------------+-----------------------------------------------------------------+
189| List of additional flags to pass to the C compiler. |
190+--------------------------------+-----------------------------------------------------------------+
191| :param:`cxxopts` | :type:`list of string` |
192+--------------------------------+-----------------------------------------------------------------+
193| List of additional flags to pass to the C++ compiler. |
194+--------------------------------+-----------------------------------------------------------------+
195| :param:`clinkopts` | :type:`list of string` |
196+--------------------------------+-----------------------------------------------------------------+
197| List of additional flags to pass to the external linker. |
198+--------------------------------+-----------------------------------------------------------------+
199| :param:`cgo_deps` | :type:`list of File` |
200+--------------------------------+-----------------------------------------------------------------+
201| Deprecated; use ``cdeps`` instead. The direct cgo dependencies of this library. |
202+--------------------------------+-----------------------------------------------------------------+
203| :param:`cgo_exports` | :type:`list of File` |
204+--------------------------------+-----------------------------------------------------------------+
205| The exposed cc headers for these sources. |
206+--------------------------------+-----------------------------------------------------------------+
207| :param:`cc_info` | :type:`CcInfo` |
208+--------------------------------+-----------------------------------------------------------------+
209| The result of merging the ``CcInfo``s of all `deps` and `cdeps` |
210+--------------------------------+-----------------------------------------------------------------+
211
212GoArchiveData
213~~~~~~~~~~~~~
214
215GoArchiveData contains information about a compiled Go package. GoArchiveData
216only contains immutable information about a package itself. It does not contain
217any information about dependencies or references to other providers. This makes
218it suitable to include in depsets. GoArchiveData is not directly returned by any
219rule. Instead, it's referenced in the ``data`` field of GoArchive_.
220
221+--------------------------------+-----------------------------------------------------------------+
222| **Name** | **Type** |
223+--------------------------------+-----------------------------------------------------------------+
224| :param:`name` | :type:`string` |
225+--------------------------------+-----------------------------------------------------------------+
226| The name of the library. Usually the same as the ``name`` attribute. |
227+--------------------------------+-----------------------------------------------------------------+
228| :param:`label` | :type:`Label` |
229+--------------------------------+-----------------------------------------------------------------+
230| The full label for the library. |
231+--------------------------------+-----------------------------------------------------------------+
232| :param:`importpath` | :type:`string` |
233+--------------------------------+-----------------------------------------------------------------+
234| The string used in ``import`` declarations in Go source code to import this |
235| library. Usually, this is the ``importpath`` attribute. |
236+--------------------------------+-----------------------------------------------------------------+
237| :param:`importmap` | :type:`string` |
238+--------------------------------+-----------------------------------------------------------------+
239| The package path for this library. The Go compiler and linker internally refer |
240| to the library using this string. It must be unique in any binary the library |
241| is linked into. This is usually the same as ``importpath``, but it may be |
242| different, especially for vendored libraries. |
243+--------------------------------+-----------------------------------------------------------------+
244| :param:`pathtype` | :type:`string` |
245+--------------------------------+-----------------------------------------------------------------+
246| Information about the source of the importpath. Possible values are: |
247| |
248| :value:`explicit` |
249| The importpath was explicitly supplied by the user and the library is importable. |
250| This is the normal case. |
251| :value:`inferred` |
252| The importpath was inferred from the directory structure and rule name. The library may be |
253| importable. |
254| This is normally true for rules that do not expect to be compiled directly to a library, |
255| embeded into another rule instead (source generators) |
256| :value:`export` |
257| The importpath was explicitly supplied by the user, but the library is |
258| not importable. This is the case for binaries and tests. The importpath |
259| may still be useful for `go_path`_ and other rules. |
260+--------------------------------+-----------------------------------------------------------------+
261| :param:`file` | :type:`File` |
262+--------------------------------+-----------------------------------------------------------------+
263| The archive file for the linker produced when this library is compiled. |
264+--------------------------------+-----------------------------------------------------------------+
265| :param:`export_file` | :type:`File` |
266+--------------------------------+-----------------------------------------------------------------+
267| The archive file for compilation of dependent libraries produced when this library is compiled. |
268+--------------------------------+-----------------------------------------------------------------+
269| :param:`facts_file` | :type:`File` |
270+--------------------------------+-----------------------------------------------------------------+
271| The serialized facts for this library produced when nogo ran for this library. |
272+--------------------------------+-----------------------------------------------------------------+
273| :param:`srcs` | :type:`tuple of File` |
274+--------------------------------+-----------------------------------------------------------------+
275| The .go sources compiled into the archive. May have been generated or |
276| transformed with tools like cgo and cover. |
277+--------------------------------+-----------------------------------------------------------------+
278| :param:`orig_srcs` | :type:`tuple of File` |
279+--------------------------------+-----------------------------------------------------------------+
280| The unmodified sources provided to the rule, including .go, .s, .h, .c files. |
281+--------------------------------+-----------------------------------------------------------------+
282| :param:`data_files` | :type:`tuple of File` |
283+--------------------------------+-----------------------------------------------------------------+
284| Data files that should be available at runtime to binaries and tests built |
285| from this archive. |
286+--------------------------------+-----------------------------------------------------------------+
287
288GoArchive
289~~~~~~~~~
290
291``GoArchive`` contains information about a compiled archive and its dependencies
292(both direct and transitive). This is used when compiling and linking Go
293libraries and binaries. It is produced by the archive_ toolchain function.
294
295Most of the metadata about the archive itself is available in GoArchiveData_,
296which is available through the :param:`data` field.
297
298+--------------------------------+-----------------------------------------------------------------+
299| **Name** | **Type** |
300+--------------------------------+-----------------------------------------------------------------+
301| :param:`source` | :type:`GoSource` |
302+--------------------------------+-----------------------------------------------------------------+
303| The source provider this GoArchive was compiled from. |
304+--------------------------------+-----------------------------------------------------------------+
305| :param:`data` | :type:`GoArchiveData` |
306+--------------------------------+-----------------------------------------------------------------+
307| The non transitive data for this archive. |
308+--------------------------------+-----------------------------------------------------------------+
309| :param:`direct` | :type:`list of GoArchive` |
310+--------------------------------+-----------------------------------------------------------------+
311| The direct dependencies of this archive. |
312+--------------------------------+-----------------------------------------------------------------+
313| :param:`libs` | :type:`depset of File` |
314+--------------------------------+-----------------------------------------------------------------+
315| The transitive set of libraries needed to link with this archive. |
316+--------------------------------+-----------------------------------------------------------------+
317| :param:`transitive` | :type:`depset of GoArchiveData` |
318+--------------------------------+-----------------------------------------------------------------+
319| The full set of transitive dependencies. This includes ``data`` for this |
320| archive and all ``data`` members transitively reachable through ``direct``. |
321+--------------------------------+-----------------------------------------------------------------+
322| :param:`x_defs` | :type:`string_dict` |
323+--------------------------------+-----------------------------------------------------------------+
324| The full transitive set of defines to add to the go link command. |
325+--------------------------------+-----------------------------------------------------------------+
326| :param:`cgo_deps` | :type:`depset(cc_library)` |
327+--------------------------------+-----------------------------------------------------------------+
328| The direct cgo dependencies of this library. |
329| This has the same constraints as things that can appear in the deps of a cc_library_. |
330+--------------------------------+-----------------------------------------------------------------+
331| :param:`cgo_exports` | :type:`depset of GoSource` |
332+--------------------------------+-----------------------------------------------------------------+
333| The the transitive set of c headers needed to reference exports of this archive. |
334+--------------------------------+-----------------------------------------------------------------+
335| :param:`runfiles` | runfiles_ |
336+--------------------------------+-----------------------------------------------------------------+
337| The files needed to run anything that includes this library. |
338+--------------------------------+-----------------------------------------------------------------+
339| :param:`mode` | :type:`Mode` |
340+--------------------------------+-----------------------------------------------------------------+
341| The mode this archive was compiled in. |
342+--------------------------------+-----------------------------------------------------------------+
343
344GoPath
345~~~~~~
346
347GoPath is produced by the `go_path`_ rule. It gives a list of packages used to
348build the ``go_path`` directory and provides a list of original files for each
349package.
350
351+--------------------------------+-----------------------------------------------------------------+
352| **Name** | **Type** |
353+--------------------------------+-----------------------------------------------------------------+
354| :param:`gopath` | :type:`string` |
355+--------------------------------+-----------------------------------------------------------------+
356| The short path to the output file or directory. Useful for constructing |
357| ``runfiles`` paths. |
358+--------------------------------+-----------------------------------------------------------------+
359| :param:`gopath_file` | :type:`File` |
360+--------------------------------+-----------------------------------------------------------------+
361| A Bazel File_ that points to the output directory. |
362| |
363| * In ``archive`` mode, this is the archive. |
364| * In ``copy`` mode, this is the output directory. |
365| * In ``link`` mode, this is an empty file inside the output directory, so |
366| you need to use .dirname to get the path to the directory. |
367+--------------------------------+-----------------------------------------------------------------+
368| :param:`packages` | :type:`list of struct` |
369+--------------------------------+-----------------------------------------------------------------+
370| A list of structs representing packages used to build the ``go_path`` |
371| directory. Each struct has the following fields: |
372| |
373| * ``importpath``: the import path of the package. |
374| * ``dir``: the subdirectory of the package within the ``go_path``, including |
375| the ``src/`` prefix. May different from ``importpath`` due to vendoring. |
376| * ``srcs``: list of source ``File``s. |
377| * ``data``: list of data ``File``s. |
378+--------------------------------+-----------------------------------------------------------------+
379
380GoSDK
381~~~~~
382
383``GoSDK`` contains information about the Go SDK used in the toolchain.
384
385+--------------------------------+-----------------------------------------------------------------+
386| **Name** | **Type** |
387+--------------------------------+-----------------------------------------------------------------+
388| :param:`goos` | :type:`string` |
389+--------------------------------+-----------------------------------------------------------------+
390| The host operating system the SDK was built for. |
391+--------------------------------+-----------------------------------------------------------------+
392| :param:`goarch` | :type:`string` |
393+--------------------------------+-----------------------------------------------------------------+
394| The host architecture the SDK was built for. |
395+--------------------------------+-----------------------------------------------------------------+
396| :param:`root_file` | :type:`File` |
397+--------------------------------+-----------------------------------------------------------------+
398| A file in the SDK root directory. Used to determine ``GOROOT``. |
399+--------------------------------+-----------------------------------------------------------------+
400| :param:`libs` | :type:`list of File` |
401+--------------------------------+-----------------------------------------------------------------+
402| Pre-compiled .a files for the standard library, built for the |
403| execution platform. |
404+--------------------------------+-----------------------------------------------------------------+
405| :param:`headers` | :type:`list of File` |
406+--------------------------------+-----------------------------------------------------------------+
407| .h files from pkg/include that may be included in assembly sources. |
408+--------------------------------+-----------------------------------------------------------------+
409| :param:`srcs` | :type:`list of File` |
410+--------------------------------+-----------------------------------------------------------------+
411| Source files for importable packages in the standard library. |
412| Internal, vendored, and tool packages might not be included. |
413+--------------------------------+-----------------------------------------------------------------+
414| :param:`package_list` | :type:`File` |
415+--------------------------------+-----------------------------------------------------------------+
416| A file containing a list of importable packages in the standard library. |
417+--------------------------------+-----------------------------------------------------------------+
418| :param:`tools` | :type:`list of File` |
419+--------------------------------+-----------------------------------------------------------------+
420| Executable files from pkg/tool built for the execution platform. |
421+--------------------------------+-----------------------------------------------------------------+
422| :param:`go` | :type:`File` |
423+--------------------------------+-----------------------------------------------------------------+
424| The go binary file. |
425+--------------------------------+-----------------------------------------------------------------+
426
427GoStdLib
428~~~~~~~~
429
430``GoStdLib`` contains information about the standard library being used for
431compiling and linking. The standard library may be the pre-compiled library
432from GoSDK_, or it may be another library compiled for the target mode.
433
434+--------------------------------+-----------------------------------------------------------------+
435| **Name** | **Type** |
436+--------------------------------+-----------------------------------------------------------------+
437| :param:`root_file` | :type:`File` |
438+--------------------------------+-----------------------------------------------------------------+
439| A file or directory in the standard library root directory. Used to determine ``GOROOT``. |
440+--------------------------------+-----------------------------------------------------------------+
441| :param:`libs` | :type:`list of File` |
442+--------------------------------+-----------------------------------------------------------------+
443| .a files for the standard library, built for the target platform. |
444+--------------------------------+-----------------------------------------------------------------+
View as plain text