Skip to content

Latest commit

 

History

History
418 lines (385 loc) · 34.1 KB

providers.rst

File metadata and controls

418 lines (385 loc) · 34.1 KB
Raw

Go providers

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

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 direct and 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
name string
The name of the library. Usually, this is the name attribute.
label Label
The full label for the library.
importpath string
The string used in import declarations in Go source code to import this library. Usually, this is the importpath attribute.
importmap 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.
pathtype string

Information about the source of the importpath. Possible values are:

explicit
The importpath was explicitly supplied by the user and the library is importable. This is the normal case.
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)
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.
resolve function (optional)
A function called by library_to_source that can be used to resolve this library to a mode-specific GoSource.
is_main bool
Indicates whether the library should be compiled as a main package. main packages may have arbitrary importpath and importmap values, but the compiler and linker must see them as main.

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
library GoLibrary
The go library that this GoSource was generated from.
mode GoConfigInfo
The mode this library is being built for.
srcs list of File
The sources to compile into the archive.
embedsrcs list of File
Files that may be embedded into the compiled package using //go:embed directives. All files must be in the same logical directory or a subdirectory as source files. However, it's okay to mix static and generated source files and static and generated embeddable files.
cover list of File
List of source files to instrument for code coverage.
x_defs string_dict
Map of defines to add to the go link command.
deps list of GoArchive
The direct dependencies needed by this library.
gc_goopts 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.
runfiles Runfiles
The set of files needed by code in these sources at runtime.
cgo bool
True if the library may contain cgo sources or C/C++/ObjC sources. If true and cgo is enabled, cgo sources will be processed with cgo, and C/C++/ObjC will be compiled with the appropriate toolchain and packed into the final archive. If true and cgo is disabled, cgo sources are filtered out, and sources with // +build !cgo are included.
cdeps list of Target
List of cc_library and objc_library targets this library depends on.
cppopts list of string
List of additional flags to pass to the C preprocessor when invoking the C/C++/ObjC compilers.
copts list of string
List of additional flags to pass to the C compiler.
cxxopts list of string
List of additional flags to pass to the C++ compiler.
clinkopts list of string
List of additional flags to pass to the external linker.
cc_info CcInfo
The result of merging the ``CcInfo``s of all deps and cdeps

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
name string
The name of the library. Usually the same as the name attribute.
label Label
The full label for the library.
importpath string
The string used in import declarations in Go source code to import this library. Usually, this is the importpath attribute.
importmap 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.
pathtype string

Information about the source of the importpath. Possible values are:

explicit
The importpath was explicitly supplied by the user and the library is importable. This is the normal case.
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)
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.
file File
The archive file for the linker produced when this library is compiled.
export_file File
The archive file for compilation of dependent libraries produced when this library is compiled.
facts_file File
The serialized facts for this library produced when nogo ran for this library.
srcs tuple of File
The .go sources compiled into the archive. May have been generated or transformed with tools like cgo and cover.
runfiles runfiles
Data files that should be available at runtime to binaries and tests built from this archive.

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 data field.

Name Type
source GoSource
The source provider this GoArchive was compiled from.
data GoArchiveData
The non transitive data for this archive.
direct list of GoArchive
The direct dependencies of this archive.
libs depset of File
The transitive set of libraries needed to link with this archive.
transitive depset of GoArchiveData
The full set of transitive dependencies. This includes data for this archive and all data members transitively reachable through direct.
x_defs string_dict
The full transitive set of defines to add to the go link command.
cgo_deps 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.
cgo_exports depset of GoSource
The transitive set of c headers needed to reference exports of this archive.
runfiles runfiles
The files needed to run anything that includes this library.

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
gopath string
The short path to the output file or directory. Useful for constructing runfiles paths.
gopath_file 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.
packages 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
goos string
The host operating system the SDK was built for.
goarch string
The host architecture the SDK was built for.
root_file File
A file in the SDK root directory. Used to determine GOROOT.
libs depset of File
Pre-compiled .a files for the standard library, built for the execution platform.
headers depset of File
.h files from pkg/include that may be included in assembly sources.
srcs depset of File
Source files for importable packages in the standard library. Internal, vendored, and tool packages might not be included.
package_list File
A file containing a list of importable packages in the standard library.
tools depset of File
Executable files from pkg/tool built for the execution platform.
go 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.