Skip to content

Latest commit

 

History

History
313 lines (281 loc) · 24.2 KB

providers.rst

File metadata and controls

313 lines (281 loc) · 24.2 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 is the provider exposed by the go_library rule, or anything that wants to behave like one. In general you should build these using the new_go_library helper function. It provides all the information requried as inputs to building an archive. It can also be used to just provide sources and deps (for use in the embed attribute). There are two main uses for this. This is a non build mode specific provider.

  1. Recompiling a library with additional sources. go_library returns a GoLibrary provider with the original sources and deps that it was consuming. go_test uses this to recompile the library with additional test files, to build the test version of the library. You can use the same feature to recompile a proto library with additional sources that were not generated by the proto compiler.
  2. Providing the dependencies for generated code. If you wanted to use flatbuffers in your code, and you had a custom rule that ran the flatbuffers compiler to generate the serialization functions, you might hit the issue that the only thing that knows you depend on github.com/google/flatbuffers/go is the generated code. You can instead have the generator return a GoLibrary provider instead of just the generated files, allowing you to tie the generated files to the additional dependencies they add to any package trying to compile them.
Name Type
name The package name for the sources.
The direct depencancies of the library.
label The label of the rule that generated the library.
The direct depencancies of the library.
importpath string
The import path for this library. Will always be set.
pathtype string

Information about the source of the importpath. It's values can be 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 is used for generated file names, but the library should not be imported by that name. This is the case for the implied "main" library of a binary or test, where the import path is not relevant as the package cannot be imported.
resolve function
The function that can be called to resolve this library to a mode specific GoSource.

GoSource

GoSource represents a GoLibrary after mode specific processing, ready to build a GoArchive. 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.
srcs list of File
The sources to compile into the archive.
cover list of File
The set of sources that should have coverage applied.
x_defs string_dict
Map of defines to add to the go link command.
deps list of GoLibrary
The direct dependencies needed by the srcs.
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_deps list of cc_library
The direct cgo dependencies of this library.
cgo_exports list of File
The exposed cc headers for these sources.
cgo_archive File
The cgo archive to merge into a go archive for these sources.

GoArchiveData

GoArchiveData represents the compiled form of a package.

Name Type
name The package name for the sources.
The direct depencancies of the library.
label The label of the rule that generated the library.
The direct depencancies of the library.
importpath string
The import path for this library. Will always be set.
importmap string
The package path for this library. The compiler and linker use this to disambiguoate packages with the same importpath. It's usually the same as importpath, but is frequently different for vendored libraries.
pathtype string

Indicates how importpath was determined. May be one of:

  • "explicit": was explicitly set.
  • "inferred": was inferred based on label name.
  • "export": a special name for synthetic packages. Not importable.
file compiled archive file
The archive file representing the library compiled in a specific mode ready for linking into binaries.
srcs list of File
The .go sources compiled into the archive. May have been generated or transformed with tools like cgo and cover.
orig_srcs list of File
The unmodified sources provided to the rule, including .go, .s, .h, .c files.
data_files list of File
Data files which should be available at runtime to binaries and tests built from this archive.
searchpath string
Deprecated: The search path entry under which the lib would be found.

GoArchive

GoArchive is a provider that exposes a compiled library along with it's full transitive dependencies. This is used when compiling and linking dependant libraries or binaries.

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.
searchpaths depset of string
Deprecated: The transitive set of search paths needed to link with 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 the transitive set of c headers needed to reference exports of this archive.
cover_vars list of string
The cover variables added to this library.
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.