go/providers.rst

Go providers
============

.. _providers: https://docs.bazel.build/versions/master/skylark/rules.html#providers

.. _go_library: core.rst#go_library
.. _go_binary: core.rst#go_binary
.. _go_test: core.rst#go_test
.. _go_path: core.rst#go_path
.. _cc_library: https://docs.bazel.build/versions/master/be/c-cpp.html#cc_library
.. _flatbuffers: http://google.github.io/flatbuffers/
.. _static linking: modes.rst#building-static-binaries
.. _race detector: modes.rst#using-the-race-detector
.. _runfiles: https://docs.bazel.build/versions/master/skylark/lib/runfiles.html
.. _File: https://docs.bazel.build/versions/master/skylark/lib/File.html
.. _new_library: toolchains.rst#new_library
.. _library_to_source: toolchains.rst#library_to_source
.. _archive: toolchains.rst#archive

.. role:: param(kbd)
.. role:: type(emphasis)
.. role:: value(code)
.. |mandatory| replace:: **mandatory value**


The providers_ are the outputs of the rules. You generaly get them by having a
dependency on a rule, and then asking for a provider of a specific type.

.. contents:: :depth: 2

-----

Design
------

The Go providers are designed primarily for the efficiency of the Go rules. The
information they share is mostly there because it is required for the core rules
to work.

All the providers are designed to hold only immutable data. This is partly
because its a cleaner design choice to be able to assume a provider will never
change, but also because only immutable objects are allowed to be stored in a
depset, and it's really useful to have depsets of providers.  Specifically the
:param:`direct` and :param:`transitive` fields on GoLibrary_ only work because
it is immutable.

API
---

GoLibrary
~~~~~~~~~

``GoLibrary`` contains metadata about an individual library. It is provided
by the `go_library`_ rule and other compatible rules. In general, you should
build ``GoLibrary`` with the `new_library`_ helper method. ``GoLibrary`` is
an input to the `library_to_source`_ helper method, which produces GoSource_.

+--------------------------------+-----------------------------------------------------------------+
| **Name**                       | **Type**                                                        |
+--------------------------------+-----------------------------------------------------------------+
| :param:`name`                  | :type:`string`                                                  |
+--------------------------------+-----------------------------------------------------------------+
| The name of the library. Usually, this is the ``name`` attribute.                                |
+--------------------------------+-----------------------------------------------------------------+
| :param:`label`                 | :type:`Label`                                                   |
+--------------------------------+-----------------------------------------------------------------+
| The full label for the library.                                                                  |
+--------------------------------+-----------------------------------------------------------------+
| :param:`importpath`            | :type:`string`                                                  |
+--------------------------------+-----------------------------------------------------------------+
| The string used in ``import`` declarations in Go source code to import                           |
| this library. Usually, this is the ``importpath`` attribute.                                     |
+--------------------------------+-----------------------------------------------------------------+
| :param:`importmap`             | :type:`string`                                                  |
+--------------------------------+-----------------------------------------------------------------+
| The package path for this library. The Go compiler and linker internally refer                   |
| to the library using this string. It must be unique in any binary the library                    |
| is linked into. This is usually the same as ``importpath``, but it may be                        |
| different, especially for vendored libraries.                                                    |
+--------------------------------+-----------------------------------------------------------------+
| :param:`pathtype`              | :type:`string`                                                  |
+--------------------------------+-----------------------------------------------------------------+
| Information about the source of the importpath. Possible values are:                             |
|                                                                                                  |
| :value:`explicit`                                                                                |
|     The importpath was explicitly supplied by the user and the library is importable.            |
|     This is the normal case.                                                                     |
| :value:`inferred`                                                                                |
|     The importpath was inferred from the directory structure and rule name. The library may be   |
|     importable.                                                                                  |
|     This is normally true for rules that do not expect to be compiled directly to a library,     |
|     embeded into another rule instead (source generators)                                        |
| :value:`export`                                                                                  |
|     The importpath was explicitly supplied by the user, but the library is                       |
|     not importable. This is the case for binaries and tests. The importpath                      |
|     may still be useful for `go_path`_ and other rules.                                          |
+--------------------------------+-----------------------------------------------------------------+
| :param:`resolve`               | :type:`function (optional)`                                     |
+--------------------------------+-----------------------------------------------------------------+
| A function called by `library_to_source`_ that can be used to resolve this                       |
| library to a mode-specific GoSource_.                                                            |
+--------------------------------+-----------------------------------------------------------------+

GoSource
~~~~~~~~

GoSource represents a GoLibrary_ after mode-specific processing, ready to build
a GoArchive_. This is produced by calling the `library_to_source`_ helper
method. In general, only rules_go should need to build or handle these.

+--------------------------------+-----------------------------------------------------------------+
| **Name**                       | **Type**                                                        |
+--------------------------------+-----------------------------------------------------------------+
| :param:`library`               | :type:`GoLibrary`                                               |
+--------------------------------+-----------------------------------------------------------------+
| The go library that this GoSource was generated from.                                            |
+--------------------------------+-----------------------------------------------------------------+
| :param:`mode`                  | :type:`Mode`                                                    |
+--------------------------------+-----------------------------------------------------------------+
| The mode this library is being built for.                                                        |
+--------------------------------+-----------------------------------------------------------------+
| :param:`srcs`                  | :type:`list of File`                                            |
+--------------------------------+-----------------------------------------------------------------+
| The sources to compile into the archive.                                                         |
+--------------------------------+-----------------------------------------------------------------+
| :param:`orig_srcs`             | :type:`list of File`                                            |
+--------------------------------+-----------------------------------------------------------------+
| The original source files this library is based on. This may differ from                         |
| :param:`srcs` if processing tools such as cgo or cover are applied.                              |
+--------------------------------+-----------------------------------------------------------------+
| :param:`orig_src_map`          | :type:`dict of File to File`                                    |
+--------------------------------+-----------------------------------------------------------------+
| Maps generated files in :param:`srcs` back to :param:`orig_srcs`. Not all                        |
| generated files may appear in here.                                                              |
+--------------------------------+-----------------------------------------------------------------+
| :param:`cover`                 | :type:`list of File`                                            |
+--------------------------------+-----------------------------------------------------------------+
| List of source files to instrument for code coverage.                                            |
+--------------------------------+-----------------------------------------------------------------+
| :param:`x_defs`                | :type:`string_dict`                                             |
+--------------------------------+-----------------------------------------------------------------+
| Map of defines to add to the go link command.                                                    |
+--------------------------------+-----------------------------------------------------------------+
| :param:`deps`                  | :type:`list of Target`                                          |
+--------------------------------+-----------------------------------------------------------------+
| The direct dependencies needed by this library.                                                  |
+--------------------------------+-----------------------------------------------------------------+
| :param:`gc_goopts`             | :type:`list of string`                                          |
+--------------------------------+-----------------------------------------------------------------+
| Go compilation options that should be used when compiling these sources.                         |
| In general these will be used for *all* sources of any library this provider is embedded into.   |
+--------------------------------+-----------------------------------------------------------------+
| :param:`runfiles`              | :type:`Runfiles`                                                |
+--------------------------------+-----------------------------------------------------------------+
| The set of files needed by code in these sources at runtime.                                     |
+--------------------------------+-----------------------------------------------------------------+
| :param:`cgo_deps`              | :type:`list of File`                                            |
+--------------------------------+-----------------------------------------------------------------+
| The direct cgo dependencies of this library.                                                     |
+--------------------------------+-----------------------------------------------------------------+
| :param:`cgo_exports`           | :type:`list of File`                                            |
+--------------------------------+-----------------------------------------------------------------+
| The exposed cc headers for these sources.                                                        |
+--------------------------------+-----------------------------------------------------------------+
| :param:`cgo_archives`          | :type:`list of File`                                            |
+--------------------------------+-----------------------------------------------------------------+
| The cgo archives to merge into a go archive for these sources.                                   |
+--------------------------------+-----------------------------------------------------------------+

GoArchiveData
~~~~~~~~~~~~~

GoArchiveData contains information about a compiled Go package. GoArchiveData
only contains immutable information about a package itself. It does not contain
any information about dependencies or references to other providers. This makes
it suitable to include in depsets. GoArchiveData is not directly returned by any
rule.  Instead, it's referenced in the ``data`` field of GoArchive_.

+--------------------------------+-----------------------------------------------------------------+
| **Name**                       | **Type**                                                        |
+--------------------------------+-----------------------------------------------------------------+
| :param:`name`                  | :type:`string`                                                  |
+--------------------------------+-----------------------------------------------------------------+
| The name of the library. Usually the same as the ``name`` attribute.                             |
+--------------------------------+-----------------------------------------------------------------+
| :param:`label`                 | :type:`Label`                                                   |
+--------------------------------+-----------------------------------------------------------------+
| The full label for the library.                                                                  |
+--------------------------------+-----------------------------------------------------------------+
| :param:`importpath`            | :type:`string`                                                  |
+--------------------------------+-----------------------------------------------------------------+
| The string used in ``import`` declarations in Go source code to import this                      |
| library. Usually, this is the ``importpath`` attribute.                                          |
+--------------------------------+-----------------------------------------------------------------+
| :param:`importmap`             | :type:`string`                                                  |
+--------------------------------+-----------------------------------------------------------------+
| The package path for this library. The Go compiler and linker internally refer                   |
| to the library using this string. It must be unique in any binary the library                    |
| is linked into. This is usually the same as ``importpath``, but it may be                        |
| different, especially for vendored libraries.                                                    |
+--------------------------------+-----------------------------------------------------------------+
| :param:`pathtype`              | :type:`string`                                                  |
+--------------------------------+-----------------------------------------------------------------+
| Information about the source of the importpath. Possible values are:                             |
|                                                                                                  |
| :value:`explicit`                                                                                |
|     The importpath was explicitly supplied by the user and the library is importable.            |
|     This is the normal case.                                                                     |
| :value:`inferred`                                                                                |
|     The importpath was inferred from the directory structure and rule name. The library may be   |
|     importable.                                                                                  |
|     This is normally true for rules that do not expect to be compiled directly to a library,     |
|     embeded into another rule instead (source generators)                                        |
| :value:`export`                                                                                  |
|     The importpath was explicitly supplied by the user, but the library is                       |
|     not importable. This is the case for binaries and tests. The importpath                      |
|     may still be useful for `go_path`_ and other rules.                                          |
+--------------------------------+-----------------------------------------------------------------+
| :param:`file`                  | :type:`File`                                                    |
+--------------------------------+-----------------------------------------------------------------+
| The archive file produced when this library is coimpiled.                                        |
+--------------------------------+-----------------------------------------------------------------+
| :param:`srcs`                  | :type:`tuple of File`                                           |
+--------------------------------+-----------------------------------------------------------------+
| The .go sources compiled into the archive. May have been generated or                            |
| transformed with tools like cgo and cover.                                                       |
+--------------------------------+-----------------------------------------------------------------+
| :param:`orig_srcs`             | :type:`tuple of File`                                           |
+--------------------------------+-----------------------------------------------------------------+
| The unmodified sources provided to the rule, including .go, .s, .h, .c files.                    |
+--------------------------------+-----------------------------------------------------------------+
| :param:`data_files`            | :type:`tuple of File`                                           |
+--------------------------------+-----------------------------------------------------------------+
| Data files that should be available at runtime to binaries and tests built                       |
| from this archive.                                                                               |
+--------------------------------+-----------------------------------------------------------------+
| :param:`searchpath`            | :type:`string`                                                  |
+--------------------------------+-----------------------------------------------------------------+
| **Deprecated:** The search path entry under which the :param:`lib` would be found.               |
+--------------------------------+-----------------------------------------------------------------+

GoArchive
~~~~~~~~~

``GoArchive`` contains information about a compiled archive and its dependencies
(both direct and transitive). This is used when compiling and linking Go
libraries and binaries. It is produced by the archive_ toolchain function.

Most of the metadata about the archive itself is available in GoArchiveData_,
which is available through the :param:`data` field.

+--------------------------------+-----------------------------------------------------------------+
| **Name**                       | **Type**                                                        |
+--------------------------------+-----------------------------------------------------------------+
| :param:`source`                | :type:`GoSource`                                                |
+--------------------------------+-----------------------------------------------------------------+
| The source provider this GoArchive was compiled from.                                            |
+--------------------------------+-----------------------------------------------------------------+
| :param:`data`                  | :type:`GoArchiveData`                                           |
+--------------------------------+-----------------------------------------------------------------+
| The non transitive data for this archive.                                                        |
+--------------------------------+-----------------------------------------------------------------+
| :param:`direct`                | :type:`list of GoArchive`                                       |
+--------------------------------+-----------------------------------------------------------------+
| The direct dependencies of this archive.                                                         |
+--------------------------------+-----------------------------------------------------------------+
| :param:`searchpaths`           | :type:`depset of string`                                        |
+--------------------------------+-----------------------------------------------------------------+
| **Deprecated:** The transitive set of search paths needed to link with this archive.             |
+--------------------------------+-----------------------------------------------------------------+
| :param:`libs`                  | :type:`depset of File`                                          |
+--------------------------------+-----------------------------------------------------------------+
| The transitive set of libraries needed to link with this archive.                                |
+--------------------------------+-----------------------------------------------------------------+
| :param:`transitive`            | :type:`depset of GoArchiveData`                                 |
+--------------------------------+-----------------------------------------------------------------+
| The full set of transitive dependencies. This includes ``data`` for this                         |
| archive and all ``data`` members transitively reachable through ``direct``.                      |
+--------------------------------+-----------------------------------------------------------------+
| :param:`x_defs`                | :type:`string_dict`                                             |
+--------------------------------+-----------------------------------------------------------------+
| The full transitive set of defines to add to the go link command.                                |
+--------------------------------+-----------------------------------------------------------------+
| :param:`cgo_deps`              | :type:`depset(cc_library)`                                      |
+--------------------------------+-----------------------------------------------------------------+
| The direct cgo dependencies of this library.                                                     |
| This has the same constraints as things that can appear in the deps of a cc_library_.            |
+--------------------------------+-----------------------------------------------------------------+
| :param:`cgo_exports`           | :type:`depset of GoSource`                                      |
+--------------------------------+-----------------------------------------------------------------+
| The the transitive set of c headers needed to reference exports of this archive.                 |
+--------------------------------+-----------------------------------------------------------------+
| :param:`runfiles`              | runfiles_                                                       |
+--------------------------------+-----------------------------------------------------------------+
| The files needed to run anything that includes this library.                                     |
+--------------------------------+-----------------------------------------------------------------+
| :param:`mode`                  | :type:`Mode`                                                    |
+--------------------------------+-----------------------------------------------------------------+
| The mode this archive was compiled in.                                                           |
+--------------------------------+-----------------------------------------------------------------+

GoPath
~~~~~~

GoPath is produced by the `go_path`_ rule. It gives a list of packages used to
build the ``go_path`` directory and provides a list of original files for each
package.

+--------------------------------+-----------------------------------------------------------------+
| **Name**                       | **Type**                                                        |
+--------------------------------+-----------------------------------------------------------------+
| :param:`gopath`                | :type:`string`                                                  |
+--------------------------------+-----------------------------------------------------------------+
| The short path to the output file or directory. Useful for constructing                          |
| ``runfiles`` paths.                                                                              |
+--------------------------------+-----------------------------------------------------------------+
| :param:`gopath_file`           | :type:`File`                                                    |
+--------------------------------+-----------------------------------------------------------------+
| A Bazel File_ that points to the output directory.                                               |
|                                                                                                  |
| * In ``archive`` mode, this is the archive.                                                      |
| * In ``copy`` mode, this is the output directory.                                                |
| * In ``link`` mode, this is an empty file inside the output directory, so                        |
|   you need to use .dirname to get the path to the directory.                                     |
+--------------------------------+-----------------------------------------------------------------+
| :param:`packages`              | :type:`list of struct`                                          |
+--------------------------------+-----------------------------------------------------------------+
| A list of structs representing packages used to build the ``go_path``                            |
| directory. Each struct has the following fields:                                                 |
|                                                                                                  |
| * ``importpath``: the import path of the package.                                                |
| * ``dir``: the subdirectory of the package within the ``go_path``, including                     |
|   the ``src/`` prefix. May different from ``importpath`` due to vendoring.                       |
| * ``srcs``: list of source ``File``s.                                                            |
| * ``data``: list of data ``File``s.                                                              |
+--------------------------------+-----------------------------------------------------------------+

GoSDK
~~~~~

``GoSDK`` contains information about the Go SDK used in the toolchain.

+--------------------------------+-----------------------------------------------------------------+
| **Name**                       | **Type**                                                        |
+--------------------------------+-----------------------------------------------------------------+
| :param:`goos`                  | :type:`string`                                                  |
+--------------------------------+-----------------------------------------------------------------+
| The host operating system the SDK was built for.                                                 |
+--------------------------------+-----------------------------------------------------------------+
| :param:`goarch`                | :type:`string`                                                  |
+--------------------------------+-----------------------------------------------------------------+
| The host architecture the SDK was built for.                                                     |
+--------------------------------+-----------------------------------------------------------------+
| :param:`root_file`             | :type:`File`                                                    |
+--------------------------------+-----------------------------------------------------------------+
| A file in the SDK root directory. Used to determine ``GOROOT``.                                  |
+--------------------------------+-----------------------------------------------------------------+
| :param:`libs`                  | :type:`list of File`                                            |
+--------------------------------+-----------------------------------------------------------------+
| Pre-compiled .a files for the standard library, built for the                                    |
| execution platform.                                                                              |
+--------------------------------+-----------------------------------------------------------------+
| :param:`headers`               | :type:`list of File`                                            |
+--------------------------------+-----------------------------------------------------------------+
| .h files from pkg/include that may be included in assembly sources.                              |
+--------------------------------+-----------------------------------------------------------------+
| :param:`srcs`                  | :type:`list of File`                                            |
+--------------------------------+-----------------------------------------------------------------+
| Source files for importable packages in the standard library.                                    |
| Internal, vendored, and tool packages might not be included.                                     |
+--------------------------------+-----------------------------------------------------------------+
| :param:`package_list`          | :type:`File`                                                    |
+--------------------------------+-----------------------------------------------------------------+
| A file containing a list of importable packages in the standard library.                         |
+--------------------------------+-----------------------------------------------------------------+
| :param:`tools`                 | :type:`list of File`                                            |
+--------------------------------+-----------------------------------------------------------------+
| Executable files from pkg/tool built for the execution platform.                                 |
+--------------------------------+-----------------------------------------------------------------+
| :param:`go`                    | :type:`File`                                                    |
+--------------------------------+-----------------------------------------------------------------+
| The go binary file.                                                                              |
+--------------------------------+-----------------------------------------------------------------+

GoStdLib
~~~~~~~~

``GoStdLib`` contains information about the standard library being used for
compiling and linking. The standard library may be the pre-compiled library
from GoSDK_, or it may be another library compiled for the target mode.

+--------------------------------+-----------------------------------------------------------------+
| **Name**                       | **Type**                                                        |
+--------------------------------+-----------------------------------------------------------------+
| :param:`root_file`             | :type:`File`                                                    |
+--------------------------------+-----------------------------------------------------------------+
| A file in the standard library root directory. Used to determine ``GOROOT``.                     |
+--------------------------------+-----------------------------------------------------------------+
| :param:`libs`                  | :type:`list of File`                                            |
+--------------------------------+-----------------------------------------------------------------+
| .a files for the standard library, built for the target platform.                                |
+--------------------------------+-----------------------------------------------------------------+