github.com/bazelbuild/rules_go@v0.47.2-0.20240515105122-e7ddb9ea474e/go/providers.rst (about) 1 Go 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 26 The providers_ are the outputs of the rules. You generaly get them by having a 27 dependency on a rule, and then asking for a provider of a specific type. 28 29 .. contents:: :depth: 2 30 31 ----- 32 33 Design 34 ------ 35 36 The Go providers are designed primarily for the efficiency of the Go rules. The 37 information they share is mostly there because it is required for the core rules 38 to work. 39 40 All the providers are designed to hold only immutable data. This is partly 41 because its a cleaner design choice to be able to assume a provider will never 42 change, but also because only immutable objects are allowed to be stored in a 43 depset, and it's really useful to have depsets of providers. Specifically the 44 :param:`direct` and :param:`transitive` fields on GoLibrary_ only work because 45 it is immutable. 46 47 API 48 --- 49 50 GoLibrary 51 ~~~~~~~~~ 52 53 ``GoLibrary`` contains metadata about an individual library. It is provided 54 by the `go_library`_ rule and other compatible rules. In general, you should 55 build ``GoLibrary`` with the `new_library`_ helper method. ``GoLibrary`` is 56 an 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 110 GoSource 111 ~~~~~~~~ 112 113 GoSource represents a GoLibrary_ after mode-specific processing, ready to build 114 a GoArchive_. This is produced by calling the `library_to_source`_ helper 115 method. 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 212 GoArchiveData 213 ~~~~~~~~~~~~~ 214 215 GoArchiveData contains information about a compiled Go package. GoArchiveData 216 only contains immutable information about a package itself. It does not contain 217 any information about dependencies or references to other providers. This makes 218 it suitable to include in depsets. GoArchiveData is not directly returned by any 219 rule. 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 288 GoArchive 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 293 libraries and binaries. It is produced by the archive_ toolchain function. 294 295 Most of the metadata about the archive itself is available in GoArchiveData_, 296 which 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 344 GoPath 345 ~~~~~~ 346 347 GoPath is produced by the `go_path`_ rule. It gives a list of packages used to 348 build the ``go_path`` directory and provides a list of original files for each 349 package. 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 380 GoSDK 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 427 GoStdLib 428 ~~~~~~~~ 429 430 ``GoStdLib`` contains information about the standard library being used for 431 compiling and linking. The standard library may be the pre-compiled library 432 from 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 +--------------------------------+-----------------------------------------------------------------+