github.com/ajguerrer/rules_go@v0.20.3/go/core.rst (about) 1 Core go rules 2 ============= 3 4 .. _test_filter: https://docs.bazel.build/versions/master/user-manual.html#flag--test_filter 5 .. _test_arg: https://docs.bazel.build/versions/master/user-manual.html#flag--test_arg 6 .. _Gazelle: https://github.com/bazelbuild/bazel-gazelle 7 .. _GoLibrary: providers.rst#GoLibrary 8 .. _GoSource: providers.rst#GoSource 9 .. _GoArchive: providers.rst#GoArchive 10 .. _GoPath: providers.rst#GoPath 11 .. _cgo: http://golang.org/cmd/cgo/ 12 .. _"Make variable": https://docs.bazel.build/versions/master/be/make-variables.html 13 .. _Bourne shell tokenization: https://docs.bazel.build/versions/master/be/common-definitions.html#sh-tokenization 14 .. _data dependencies: https://docs.bazel.build/versions/master/build-ref.html#data 15 .. _cc library deps: https://docs.bazel.build/versions/master/be/c-cpp.html#cc_library.deps 16 .. _shard_count: https://docs.bazel.build/versions/master/be/common-definitions.html#test.shard_count 17 .. _pure: modes.rst#pure 18 .. _static: modes.rst#static 19 .. _goos: modes.rst#goos 20 .. _goarch: modes.rst#goarch 21 .. _mode attributes: modes.rst#mode-attributes 22 .. _write a CROSSTOOL file: https://github.com/bazelbuild/bazel/wiki/Yet-Another-CROSSTOOL-Writing-Tutorial 23 .. _build constraints: https://golang.org/pkg/go/build/#hdr-Build_Constraints 24 .. _select: https://docs.bazel.build/versions/master/be/functions.html#select 25 .. _config_setting: https://docs.bazel.build/versions/master/be/general.html#config_setting 26 .. _nogo: nogo.rst#nogo 27 28 .. role:: param(kbd) 29 .. role:: type(emphasis) 30 .. role:: value(code) 31 .. |mandatory| replace:: **mandatory value** 32 33 These are the core go rules, required for basic operation. 34 The intent is that theses rules are sufficient to match the capabilities of the normal go tools. 35 36 .. contents:: :depth: 2 37 38 ----- 39 40 Design 41 ------ 42 43 Defines and stamping 44 ~~~~~~~~~~~~~~~~~~~~ 45 46 In order to provide build time information to go code without data files, we 47 support the concept of stamping. 48 49 Stamping asks the linker to substitute the value of a global variable with a 50 string determined at link time. Stamping only happens when linking a binary, not 51 when compiling a package. This means that changing a value results only in 52 re-linking, not re-compilation and thus does not cause cascading changes. 53 54 Link values are set in the :param:`x_defs` attribute of any Go rule. This is a 55 map of string to string, where keys are the names of variables to substitute, 56 and values are the string to use. Keys may be names of variables in the package 57 being compiled, or they may be fully qualified names of variables in another 58 package. 59 60 These mappings are collected up across the entire transitive dependancies of a 61 binary. This means you can set a value using :param:`x_defs` in a 62 ``go_library``, and any binary that links that library will be stamped with that 63 value. You can also override stamp values from libraries using :param:`x_defs` 64 on the ``go_binary`` rule if needed. The ``--[no]stamp`` option controls whether 65 stamping of workspace variables is enabled. 66 67 Example 68 ^^^^^^^ 69 70 Suppose we have a small library that contains the current version. 71 72 .. code:: go 73 74 package version 75 76 var Version = "redacted" 77 78 We can set the version in the ``go_library`` rule for this library. 79 80 .. code:: bzl 81 82 go_library( 83 name = "go_default_library", 84 srcs = ["version.go"], 85 importpath = "example.com/repo/version", 86 x_defs = {"Version": "0.9"}, 87 ) 88 89 Binaries that depend on this library may also set this value. 90 91 .. code:: bzl 92 93 go_binary( 94 name = "cmd", 95 srcs = ["main.go"], 96 deps = ["//version:go_default_library"], 97 x_defs = {"example.com/repo/version.Version": "0.9"}, 98 ) 99 100 Stamping with the workspace status script 101 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 102 103 You can use values produced by the workspace status command in your link stamp. 104 To use this functionality, write a script that prints key-value pairs, separated 105 by spaces, one per line. For example: 106 107 .. code:: bash 108 109 #!/usr/bin/env bash 110 111 echo STABLE_GIT_COMMIT $(git rev-parse HEAD) 112 113 **NOTE:** keys that start with ``STABLE_`` will trigger a re-link when they change. 114 Other keys will NOT trigger a re-link. 115 116 You can reference these in :param:`x_defs` using curly braces. 117 118 .. code:: bzl 119 120 go_binary( 121 name = "cmd", 122 srcs = ["main.go"], 123 deps = ["//version:go_default_library"], 124 x_defs = {"example.com/repo/version.Version": "{STABLE_GIT_COMMIT}"}, 125 ) 126 127 You can build using the status script using the ``--workspace_status_command`` 128 argument on the command line: 129 130 .. code:: bash 131 132 $ bazel build --stamp --workspace_status_command=./status.sh //:cmd 133 134 Embedding 135 ~~~~~~~~~ 136 137 The sources, dependencies, and data of a ``go_library`` may be *embedded* 138 within another ``go_library``, ``go_binary``, or ``go_test`` using the ``embed`` 139 attribute. The embedding package will be compiled into a single archive 140 file. The embedded package may still be compiled as a separate target. 141 142 A minimal example of embedding is below. In this example, the command ``bazel 143 build :foo_and_bar`` will compile ``foo.go`` and ``bar.go`` into a single 144 archive. ``bazel build :bar`` will compile only ``bar.go``. Both libraries must 145 have the same ``importpath``. 146 147 .. code:: bzl 148 149 go_library( 150 name = "foo_and_bar", 151 srcs = ["foo.go"], 152 embed = [":bar"], 153 importpath = "example.com/foo", 154 ) 155 156 go_library( 157 name = "bar", 158 srcs = ["bar.go"], 159 importpath = "example.com/foo", 160 ) 161 162 Embedding is most frequently used for tests and binaries. Go supports two 163 different kinds of tests. *Internal tests* (e.g., ``package foo``) are compiled 164 into the same archive as the library under test and can reference unexported 165 definitions in that library. *External tests* (e.g., ``package foo_test``) are 166 compiled into separate archives and may depend on exported definitions from the 167 internal test archive. 168 169 In order to compile the internal test archive, we *embed* the ``go_library`` 170 under test into a ``go_test`` that contains the test sources. The ``go_test`` 171 rule can automatically distinguish internal and external test sources, so they 172 can be listed together in ``srcs``. The ``go_library`` under test does not 173 contain test sources. Other ``go_binary`` and ``go_library`` targets can depend 174 on it or embed it. 175 176 .. code:: bzl 177 178 go_library( 179 name = "go_default_library", 180 srcs = ["foo.go"], 181 importpath = "example.com/foo", 182 ) 183 184 go_binary( 185 name = "foo", 186 embed = [":go_default_library"], 187 ) 188 189 go_test( 190 name = "go_default_test", 191 srcs = [ 192 "foo_external_test.go", 193 "foo_internal_test.go", 194 ], 195 embed = [":go_default_library"], 196 ) 197 198 Embedding may also be used to add extra sources sources to a 199 ``go_proto_library``. 200 201 .. code:: bzl 202 203 proto_library( 204 name = "foo_proto", 205 srcs = ["foo.proto"], 206 ) 207 208 go_proto_library( 209 name = "foo_go_proto", 210 importpath = "example.com/foo", 211 proto = ":foo_proto", 212 ) 213 214 go_library( 215 name = "go_default_library", 216 srcs = ["extra.go"], 217 embed = [":foo_go_proto"], 218 importpath = "example.com/foo", 219 ) 220 221 API 222 --- 223 224 go_library 225 ~~~~~~~~~~ 226 227 This builds a Go library from a set of source files that are all part of 228 the same package. 229 230 Providers 231 ^^^^^^^^^ 232 233 * GoLibrary_ 234 * GoSource_ 235 * GoArchive_ 236 237 Attributes 238 ^^^^^^^^^^ 239 240 +----------------------------+-----------------------------+---------------------------------------+ 241 | **Name** | **Type** | **Default value** | 242 +----------------------------+-----------------------------+---------------------------------------+ 243 | :param:`name` | :type:`string` | |mandatory| | 244 +----------------------------+-----------------------------+---------------------------------------+ 245 | A unique name for this rule. | 246 | | 247 | To interoperate cleanly with Gazelle_ right now this should be :value:`go_default_library`. | 248 +----------------------------+-----------------------------+---------------------------------------+ 249 | :param:`importpath` | :type:`string` | |mandatory| | 250 +----------------------------+-----------------------------+---------------------------------------+ 251 | The source import path of this library. Other libraries can import this | 252 | library using this path. This must either be specified in ``go_library`` or | 253 | inherited from one of the libraries in ``embed``. | 254 +----------------------------+-----------------------------+---------------------------------------+ 255 | :param:`importmap` | :type:`string` | :value:`""` | 256 +----------------------------+-----------------------------+---------------------------------------+ 257 | The actual import path of this library. This is mostly only visible to the | 258 | compiler and linker, but it may also be seen in stack traces. This may be set | 259 | to prevent a binary from linking multiple packages with the same import path | 260 | e.g., from different vendor directories. | 261 +----------------------------+-----------------------------+---------------------------------------+ 262 | :param:`srcs` | :type:`label_list` | :value:`None` | 263 +----------------------------+-----------------------------+---------------------------------------+ 264 | The list of Go source files that are compiled to create the package. | 265 | Only :value:`.go` files are permitted, unless the cgo attribute is set, in which case the | 266 | following file types are permitted: :value:`.go, .c, .s, .S .h`. | 267 | The files may contain Go-style `build constraints`_. | 268 +----------------------------+-----------------------------+---------------------------------------+ 269 | :param:`x_defs` | :type:`string_dict` | :value:`{}` | 270 +----------------------------+-----------------------------+---------------------------------------+ 271 | Map of defines to add to the go link command. | 272 | See `Defines and stamping`_ for examples of how to use these. | 273 +----------------------------+-----------------------------+---------------------------------------+ 274 | :param:`deps` | :type:`label_list` | :value:`None` | 275 +----------------------------+-----------------------------+---------------------------------------+ 276 | List of Go libraries this library imports directly. | 277 | These may be go_library rules or compatible rules with the GoLibrary_ provider. | 278 +----------------------------+-----------------------------+---------------------------------------+ 279 | :param:`embed` | :type:`label_list` | :value:`None` | 280 +----------------------------+-----------------------------+---------------------------------------+ 281 | List of Go libraries whose sources should be compiled together with this | 282 | library's sources. Labels listed here must name ``go_library``, | 283 | ``go_proto_library``, or other compatible targets with the GoLibrary_ and | 284 | GoSource_ providers. Embedded libraries must have the same ``importpath`` as | 285 | the embedding library. At most one embedded library may have ``cgo = True``, | 286 | and the embedding library may not also have ``cgo = True``. See Embedding_ | 287 | for more information. | 288 +----------------------------+-----------------------------+---------------------------------------+ 289 | :param:`data` | :type:`label_list` | :value:`None` | 290 +----------------------------+-----------------------------+---------------------------------------+ 291 | The list of files needed by this rule at runtime. Targets named in the data attribute will | 292 | appear in the *.runfiles area of this rule, if it has one. This may include data files needed | 293 | by the binary, or other programs needed by it. See `data dependencies`_ for more information | 294 | about how to depend on and use data files. | 295 +----------------------------+-----------------------------+---------------------------------------+ 296 | :param:`gc_goopts` | :type:`string_list` | :value:`[]` | 297 +----------------------------+-----------------------------+---------------------------------------+ 298 | List of flags to add to the Go compilation command when using the gc compiler. | 299 | Subject to `"Make variable"`_ substitution and `Bourne shell tokenization`_. | 300 +----------------------------+-----------------------------+---------------------------------------+ 301 | :param:`cgo` | :type:`boolean` | :value:`False` | 302 +----------------------------+-----------------------------+---------------------------------------+ 303 | If :value:`True`, the package uses cgo_. | 304 | The cgo tool permits Go code to call C code and vice-versa. | 305 | This does not support calling C++. | 306 | When cgo is set, :param:`srcs` may contain C, C++, Objective-C, Objective-C++, | 307 | and assembly files. These files will be compiled with the compiler from | 308 | the configured C/C++ toolchain. The compiled objects are included in | 309 | the package. | 310 +----------------------------+-----------------------------+---------------------------------------+ 311 | :param:`cdeps` | :type:`label_list` | :value:`None` | 312 +----------------------------+-----------------------------+---------------------------------------+ 313 | The list of other libraries that the c code depends on. | 314 | This can be anything that would be allowed in `cc library deps`_ | 315 | Only valid if :param:`cgo` = :value:`True`. | 316 +----------------------------+-----------------------------+---------------------------------------+ 317 | :param:`copts` | :type:`string_list` | :value:`[]` | 318 +----------------------------+-----------------------------+---------------------------------------+ 319 | List of flags to add to the C compilation command. | 320 | Subject to `"Make variable"`_ substitution and `Bourne shell tokenization`_. | 321 | Only valid if :param:`cgo` = :value:`True`. | 322 +----------------------------+-----------------------------+---------------------------------------+ 323 | :param:`cxxopts` | :type:`string_list` | :value:`[]` | 324 +----------------------------+-----------------------------+---------------------------------------+ 325 | List of flags to add to the C++ compilation command. | 326 | Subject to `"Make variable"`_ substitution and `Bourne shell tokenization`_. | 327 | Only valid if :param:`cgo` = :value:`True`. | 328 +----------------------------+-----------------------------+---------------------------------------+ 329 | :param:`cppopts` | :type:`string_list` | :value:`[]` | 330 +----------------------------+-----------------------------+---------------------------------------+ 331 | List of flags to add to the C/C++ preprocessor command. | 332 | Subject to `"Make variable"`_ substitution and `Bourne shell tokenization`_. | 333 | Only valid if :param:`cgo` = :value:`True`. | 334 +----------------------------+-----------------------------+---------------------------------------+ 335 | :param:`clinkopts` | :type:`string_list` | :value:`[]` | 336 +----------------------------+-----------------------------+---------------------------------------+ 337 | List of flags to add to the C link command. | 338 | Subject to `"Make variable"`_ substitution and `Bourne shell tokenization`_. | 339 | Only valid if :param:`cgo` = :value:`True`. | 340 +----------------------------+-----------------------------+---------------------------------------+ 341 342 Example 343 ^^^^^^^ 344 345 .. code:: bzl 346 347 go_library( 348 name = "go_default_library", 349 srcs = [ 350 "foo.go", 351 "bar.go", 352 ], 353 deps = [ 354 "//tools:go_default_library", 355 "@org_golang_x_utils//stuff:go_default_library", 356 ], 357 importpath = "github.com/example/project/foo", 358 visibility = ["//visibility:public"], 359 ) 360 361 go_tool_library 362 ~~~~~~~~~~~~~~~ 363 364 This builds a Go library from a set of source files that are all part of 365 the same package. 366 367 This rule is a limited variant of ``go_library`` which may be used to 368 bootstrap tools used by rules_go. This avoids a circular dependency. 369 If you are building analyzers to be linked into a `nogo`_ binary, you'll 370 need to use ``go_tool_library`` since ``go_library`` depends on `nogo`_ 371 implicitly. 372 373 Providers 374 ^^^^^^^^^ 375 376 * GoLibrary_ 377 * GoSource_ 378 * GoArchive_ 379 380 Attributes 381 ^^^^^^^^^^ 382 383 +----------------------------+-----------------------------+---------------------------------------+ 384 | **Name** | **Type** | **Default value** | 385 +----------------------------+-----------------------------+---------------------------------------+ 386 | :param:`name` | :type:`string` | |mandatory| | 387 +----------------------------+-----------------------------+---------------------------------------+ 388 | A unique name for this rule. | 389 +----------------------------+-----------------------------+---------------------------------------+ 390 | :param:`srcs` | :type:`label_list` | :value:`None` | 391 +----------------------------+-----------------------------+---------------------------------------+ 392 | The list of Go source files that are compiled to create the package. | 393 | Only :value:`.go` files are permitted. Cgo, assembly, and build constraints | 394 | are not supported. | 395 +----------------------------+-----------------------------+---------------------------------------+ 396 | :param:`deps` | :type:`label_list` | :value:`None` | 397 +----------------------------+-----------------------------+---------------------------------------+ 398 | List of Go libraries this library imports directly. | 399 | These must be ``go_tool_library`` targets to avoid circular dependencies. | 400 +----------------------------+-----------------------------+---------------------------------------+ 401 | :param:`embed` | :type:`label_list` | :value:`None` | 402 +----------------------------+-----------------------------+---------------------------------------+ 403 | List of Go libraries whose sources should be compiled together with this | 404 | library's sources. Labels listed here must name ``go_tool_library`` targets. | 405 | Embedded libraries must have the same ``importpath`` as the embedding library. | 406 | See Embedding_ for more information. | 407 +----------------------------+-----------------------------+---------------------------------------+ 408 | :param:`data` | :type:`label_list` | :value:`None` | 409 +----------------------------+-----------------------------+---------------------------------------+ 410 | The list of files needed by this rule at runtime. Targets named in the data attribute will | 411 | appear in the *.runfiles area of this rule, if it has one. This may include data files needed | 412 | by the binary, or other programs needed by it. See `data dependencies`_ for more information | 413 | about how to depend on and use data files. | 414 +----------------------------+-----------------------------+---------------------------------------+ 415 416 Example 417 ^^^^^^^ 418 419 .. code:: bzl 420 421 go_tool_library( 422 name = "importunsafe", 423 srcs = ["importunsafe.go"], 424 importpath = "importunsafe", 425 deps = ["@org_golang_x_tools//go/analysis:go_tool_library"], 426 visibility = ["//visibility:public"], 427 ) 428 429 go_binary 430 ~~~~~~~~~ 431 432 This builds an executable from a set of source files, which must all be 433 in the ``main`` package. You can run the binary with ``bazel run``, or you can 434 build it with ``bazel build`` and run it directly. 435 436 Providers 437 ^^^^^^^^^ 438 439 * GoLibrary_ 440 * GoSource_ 441 * GoArchive_ 442 443 Attributes 444 ^^^^^^^^^^ 445 446 +----------------------------+-----------------------------+---------------------------------------+ 447 | **Name** | **Type** | **Default value** | 448 +----------------------------+-----------------------------+---------------------------------------+ 449 | :param:`name` | :type:`string` | |mandatory| | 450 +----------------------------+-----------------------------+---------------------------------------+ 451 | A unique name for this rule. | 452 | | 453 | This should be named the same as the desired name of the generated binary . | 454 +----------------------------+-----------------------------+---------------------------------------+ 455 | :param:`srcs` | :type:`label_list` | :value:`None` | 456 +----------------------------+-----------------------------+---------------------------------------+ 457 | The list of Go source files that are compiled to create the binary. | 458 | Only :value:`.go` files are permitted, unless the cgo attribute is set, in which case the | 459 | following file types are permitted: :value:`.go, .c, .s, .S .h`. | 460 | The files may contain Go-style `build constraints`_. | 461 +----------------------------+-----------------------------+---------------------------------------+ 462 | :param:`deps` | :type:`label_list` | :value:`None` | 463 +----------------------------+-----------------------------+---------------------------------------+ 464 | List of Go libraries this binary imports directly. | 465 | These may be go_library rules or compatible rules with the GoLibrary_ provider. | 466 +----------------------------+-----------------------------+---------------------------------------+ 467 | :param:`embed` | :type:`label_list` | :value:`None` | 468 +----------------------------+-----------------------------+---------------------------------------+ 469 | List of Go libraries whose sources should be compiled together with this | 470 | binary's sources. Labels listed here must name ``go_library``, | 471 | ``go_proto_library``, or other compatible targets with the GoLibrary_ and | 472 | GoSource_ providers. Embedded libraries must all have the same ``importpath``, | 473 | which must match the ``importpath`` for this ``go_binary`` if one is | 474 | specified. At most one embedded library may have ``cgo = True``, and the | 475 | embedding binary may not also have ``cgo = True``. See Embedding_ for | 476 | more information. | 477 +----------------------------+-----------------------------+---------------------------------------+ 478 | :param:`data` | :type:`label_list` | :value:`None` | 479 +----------------------------+-----------------------------+---------------------------------------+ 480 | The list of files needed by this rule at runtime. Targets named in the data attribute will | 481 | appear in the *.runfiles area of this rule, if it has one. This may include data files needed | 482 | by the binary, or other programs needed by it. See `data dependencies`_ for more information | 483 | about how to depend on and use data files. | 484 +----------------------------+-----------------------------+---------------------------------------+ 485 | :param:`importpath` | :type:`string` | :value:`""` | 486 +----------------------------+-----------------------------+---------------------------------------+ 487 | The import path of this binary. Binaries can't actually be imported, but this | 488 | may be used by `go_path`_ and other tools to report the location of source | 489 | files. This may be inferred from embedded libraries. | 490 +----------------------------+-----------------------------+---------------------------------------+ 491 | :param:`pure` | :type:`string` | :value:`auto` | 492 +----------------------------+-----------------------------+---------------------------------------+ 493 | This is one of the `mode attributes`_ that controls whether to link in pure_ mode. | 494 | It should be one of :value:`on`, :value:`off` or :value:`auto`. | 495 +----------------------------+-----------------------------+---------------------------------------+ 496 | :param:`static` | :type:`string` | :value:`auto` | 497 +----------------------------+-----------------------------+---------------------------------------+ 498 | This is one of the `mode attributes`_ that controls whether to link in static_ mode. | 499 | It should be one of :value:`on`, :value:`off` or :value:`auto`. | 500 +----------------------------+-----------------------------+---------------------------------------+ 501 | :param:`race` | :type:`string` | :value:`auto` | 502 +----------------------------+-----------------------------+---------------------------------------+ 503 | This is one of the `mode attributes`_ that controls whether to instrument | 504 | code for data race detection. It may be :value:`on`, :value:`off`, or | 505 | :value:`auto`. In most cases, it's better to enable race detection globally | 506 | with ``--features=race`` on the command line. | 507 +----------------------------+-----------------------------+---------------------------------------+ 508 | :param:`msan` | :type:`string` | :value:`auto` | 509 +----------------------------+-----------------------------+---------------------------------------+ 510 | This is one of the `mode attributes`_ that controls whether to instrument | 511 | code for memory santization. It may be :value:`on`, :value:`off`, or | 512 | :value:`auto`. In most cases, it's better to enable memory sanitization | 513 | globally with ``--features=msan`` on the command line. | 514 +----------------------------+-----------------------------+---------------------------------------+ 515 | :param:`goos` | :type:`string` | :value:`auto` | 516 +----------------------------+-----------------------------+---------------------------------------+ 517 | This is one of the `mode attributes`_ that controls which goos_ to compile and link for. | 518 | | 519 | If set to anything other than :value:`auto` this overrides the default as set by the current | 520 | target platform and allows for single builds to make binaries for multiple architectures. | 521 | | 522 | Because this has no control over the cc toolchain, it does not work for cgo, so if this | 523 | attribute is set then :param:`pure` must be set to :value:`on`. | 524 | | 525 | This attribute has several limitations and should only be used in situations where the | 526 | ``--platforms`` flag does not work. See `Cross compilation`_ and `Note on goos and goarch | 527 | attributes`_ for more information. | 528 +----------------------------+-----------------------------+---------------------------------------+ 529 | :param:`goarch` | :type:`string` | :value:`auto` | 530 +----------------------------+-----------------------------+---------------------------------------+ 531 | This is one of the `mode attributes`_ that controls which goarch_ to compile and link for. | 532 | | 533 | If set to anything other than :value:`auto` this overrides the default as set by the current | 534 | target platform and allows for single builds to make binaries for multiple architectures. | 535 | | 536 | Because this has no control over the cc toolchain, it does not work for cgo, so if this | 537 | attribute is set then :param:`pure` must be set to :value:`on`. | 538 | | 539 | This attribute has several limitations and should only be used in situations where the | 540 | ``--platforms`` flag does not work. See `Cross compilation`_ and `Note on goos and goarch | 541 | attributes`_ for more information. | 542 +----------------------------+-----------------------------+---------------------------------------+ 543 | :param:`gc_goopts` | :type:`string_list` | :value:`[]` | 544 +----------------------------+-----------------------------+---------------------------------------+ 545 | List of flags to add to the Go compilation command when using the gc compiler. | 546 | Subject to `"Make variable"`_ substitution and `Bourne shell tokenization`_. | 547 +----------------------------+-----------------------------+---------------------------------------+ 548 | :param:`gc_linkopts` | :type:`string_list` | :value:`[]` | 549 +----------------------------+-----------------------------+---------------------------------------+ 550 | List of flags to add to the Go link command when using the gc compiler. | 551 | Subject to `"Make variable"`_ substitution and `Bourne shell tokenization`_. | 552 +----------------------------+-----------------------------+---------------------------------------+ 553 | :param:`x_defs` | :type:`string_dict` | :value:`{}` | 554 +----------------------------+-----------------------------+---------------------------------------+ 555 | Map of defines to add to the go link command. | 556 | See `Defines and stamping`_ for examples of how to use these. | 557 +----------------------------+-----------------------------+---------------------------------------+ 558 | :param:`cgo` | :type:`boolean` | :value:`False` | 559 +----------------------------+-----------------------------+---------------------------------------+ 560 | If :value:`True`, the binary uses cgo_. | 561 | The cgo tool permits Go code to call C code and vice-versa. | 562 | This does not support calling C++. | 563 | When cgo is set, :param:`srcs` may contain C, C++, Objective-C, Objective-C++, | 564 | and assembly files. These files will be compiled with the compiler from | 565 | the configured C/C++ toolchain. The compiled objects are included in | 566 | the package. | 567 +----------------------------+-----------------------------+---------------------------------------+ 568 | :param:`cdeps` | :type:`label_list` | :value:`None` | 569 +----------------------------+-----------------------------+---------------------------------------+ 570 | The list of other libraries that the c code depends on. | 571 | This can be anything that would be allowed in `cc library deps`_ | 572 | Only valid if :param:`cgo` = :value:`True`. | 573 +----------------------------+-----------------------------+---------------------------------------+ 574 | :param:`copts` | :type:`string_list` | :value:`[]` | 575 +----------------------------+-----------------------------+---------------------------------------+ 576 | List of flags to add to the C compilation command. | 577 | Subject to `"Make variable"`_ substitution and `Bourne shell tokenization`_. | 578 | Only valid if :param:`cgo` = :value:`True`. | 579 +----------------------------+-----------------------------+---------------------------------------+ 580 | :param:`cxxopts` | :type:`string_list` | :value:`[]` | 581 +----------------------------+-----------------------------+---------------------------------------+ 582 | List of flags to add to the C++ compilation command. | 583 | Subject to `"Make variable"`_ substitution and `Bourne shell tokenization`_. | 584 | Only valid if :param:`cgo` = :value:`True`. | 585 +----------------------------+-----------------------------+---------------------------------------+ 586 | :param:`cppopts` | :type:`string_list` | :value:`[]` | 587 +----------------------------+-----------------------------+---------------------------------------+ 588 | List of flags to add to the C/C++ preprocessor command. | 589 | Subject to `"Make variable"`_ substitution and `Bourne shell tokenization`_. | 590 | Only valid if :param:`cgo` = :value:`True`. | 591 +----------------------------+-----------------------------+---------------------------------------+ 592 | :param:`clinkopts` | :type:`string_list` | :value:`[]` | 593 +----------------------------+-----------------------------+---------------------------------------+ 594 | List of flags to add to the C link command. | 595 | Subject to `"Make variable"`_ substitution and `Bourne shell tokenization`_. | 596 | Only valid if :param:`cgo` = :value:`True`. | 597 +----------------------------+-----------------------------+---------------------------------------+ 598 | :param:`linkmode` | :type:`string` | :value:`"normal"` | 599 +----------------------------+-----------------------------+---------------------------------------+ 600 | Determines how the binary should be built and linked. This accepts some of | 601 | the same values as ``go build -buildmode`` and works the same way. | 602 | | 603 | :value:`normal` | 604 | Builds a normal executable with position-dependent code. | 605 | :value:`pie` | 606 | Builds a position-independent executable. | 607 | :value:`plugin` | 608 | Builds a shared library that can be loaded as a Go plugin. Only supported | 609 | on platforms that support plugins. | 610 | :value:`c-shared` | 611 | Builds a shared library that can be linked into a C program. | 612 | :value:`c-archive` | 613 | Builds an archive that can be linked into a C program. | 614 +----------------------------+-----------------------------+---------------------------------------+ 615 | :param:`out` | :type:`string` | :value:`""` | 616 +----------------------------+-----------------------------+---------------------------------------+ 617 | Sets the output filename for the generated executable. When set, ``go_binary`` | 618 | will write this file without mode-specific directory prefixes, without | 619 | linkmode-specific prefixes like "lib", and without platform-specific suffixes | 620 | like ".exe". Note that without a mode-specific directory prefix, the | 621 | output file (but not its dependencies) will be invalidated in Bazel's cache | 622 | when changing configurations. | 623 +----------------------------+-----------------------------+---------------------------------------+ 624 625 go_test 626 ~~~~~~~ 627 628 This builds a set of tests that can be run with ``bazel test``. 629 630 To run all tests in the workspace, and print output on failure (the 631 equivalent of ``go test ./...``), run 632 633 :: 634 635 bazel test --test_output=errors //... 636 637 To run a Go benchmark test, run 638 639 :: 640 641 bazel run //path/to:test -- -test.bench=. 642 643 You can run specific tests by passing the `--test_filter=pattern <test_filter_>`_ argument to Bazel. 644 You can pass arguments to tests by passing `--test_arg=arg <test_arg_>`_ arguments to Bazel. 645 646 Attributes 647 ^^^^^^^^^^ 648 649 +----------------------------+-----------------------------+---------------------------------------+ 650 | **Name** | **Type** | **Default value** | 651 +----------------------------+-----------------------------+---------------------------------------+ 652 | :param:`name` | :type:`string` | |mandatory| | 653 +----------------------------+-----------------------------+---------------------------------------+ 654 | A unique name for this rule. | 655 | | 656 | To interoperate cleanly with Gazelle_ right now this should be :value:`go_default_test` for | 657 | internal tests and :value:`go_default_xtest` for external tests. | 658 +----------------------------+-----------------------------+---------------------------------------+ 659 | :param:`importpath` | :type:`string` | :value:`""` | 660 +----------------------------+-----------------------------+---------------------------------------+ 661 | The import path of this test. Tests can't actually be imported, but this | 662 | may be used by `go_path`_ and other tools to report the location of source | 663 | files. This may be inferred from embedded libraries. | 664 +----------------------------+-----------------------------+---------------------------------------+ 665 | :param:`srcs` | :type:`label_list` | :value:`None` | 666 +----------------------------+-----------------------------+---------------------------------------+ 667 | The list of Go source files that are compiled to create the test. | 668 | Only :value:`.go` files are permitted, unless the cgo attribute is set, in which case the | 669 | following file types are permitted: :value:`.go, .c, .s, .S .h`. | 670 | The files may contain Go-style `build constraints`_. | 671 +----------------------------+-----------------------------+---------------------------------------+ 672 | :param:`deps` | :type:`label_list` | :value:`None` | 673 +----------------------------+-----------------------------+---------------------------------------+ 674 | List of Go libraries this test imports directly. | 675 | These may be go_library rules or compatible rules with the GoLibrary_ provider. | 676 +----------------------------+-----------------------------+---------------------------------------+ 677 | :param:`embed` | :type:`label_list` | :value:`None` | 678 +----------------------------+-----------------------------+---------------------------------------+ 679 | List of Go libraries whose sources should be compiled together with this | 680 | test's sources. Labels listed here must name ``go_library``, | 681 | ``go_proto_library``, or other compatible targets with the GoLibrary_ and | 682 | GoSource_ providers. Embedded libraries must have the same ``importpath`` as | 683 | the embedding test, if one is specified. At most one embedded library may | 684 | have ``cgo = True``, and the embedding test may not also have ``cgo = True``. | 685 | See Embedding_ for more information. | 686 +----------------------------+-----------------------------+---------------------------------------+ 687 | :param:`data` | :type:`label_list` | :value:`None` | 688 +----------------------------+-----------------------------+---------------------------------------+ 689 | The list of files needed by this rule at runtime. Targets named in the data attribute will | 690 | appear in the *.runfiles area of this rule, if it has one. This may include data files needed | 691 | by the binary, or other programs needed by it. See `data dependencies`_ for more information | 692 | about how to depend on and use data files. | 693 +----------------------------+-----------------------------+---------------------------------------+ 694 | :param:`importpath` | :type:`string` | :value:`""` | 695 +----------------------------+-----------------------------+---------------------------------------+ 696 | The import path of this test. Tests can't actually be imported, but this | 697 | may be used by `go_path`_ and other tools to report the location of source | 698 | files. This may be inferred from embedded libraries. | 699 +----------------------------+-----------------------------+---------------------------------------+ 700 | :param:`pure` | :type:`string` | :value:`auto` | 701 +----------------------------+-----------------------------+---------------------------------------+ 702 | This is one of the `mode attributes`_ that controls whether to link in pure_ mode. | 703 | It should be one of :value:`on`, :value:`off` or :value:`auto`. | 704 +----------------------------+-----------------------------+---------------------------------------+ 705 | :param:`static` | :type:`string` | :value:`auto` | 706 +----------------------------+-----------------------------+---------------------------------------+ 707 | This is one of the `mode attributes`_ that controls whether to link in static_ mode. | 708 | It should be one of :value:`on`, :value:`off` or :value:`auto`. | 709 +----------------------------+-----------------------------+---------------------------------------+ 710 | :param:`race` | :type:`string` | :value:`auto` | 711 +----------------------------+-----------------------------+---------------------------------------+ 712 | This is one of the `mode attributes`_ that controls whether to instrument | 713 | code for data race detection. It may be :value:`on`, :value:`off`, or | 714 | :value:`auto`. In most cases, it's better to enable race detection globally | 715 | with ``--features=race`` on the command line. | 716 +----------------------------+-----------------------------+---------------------------------------+ 717 | :param:`msan` | :type:`string` | :value:`auto` | 718 +----------------------------+-----------------------------+---------------------------------------+ 719 | This is one of the `mode attributes`_ that controls whether to instrument | 720 | code for memory santization. It may be :value:`on`, :value:`off`, or | 721 | :value:`auto`. In most cases, it's better to enable memory sanitization | 722 | globally with ``--features=msan`` on the command line. | 723 +----------------------------+-----------------------------+---------------------------------------+ 724 | :param:`goos` | :type:`string` | :value:`auto` | 725 +----------------------------+-----------------------------+---------------------------------------+ 726 | This is one of the `mode attributes`_ that controls which goos_ to compile and link for. | 727 | | 728 | If set to anything other than :value:`auto` this overrides the default as set by the current | 729 | target platform and allows for single builds to make binaries for multiple architectures. | 730 | | 731 | Because this has no control over the cc toolchain, it does not work for cgo, so if this | 732 | attribute is set then :param:`pure` must be set to :value:`on`. | 733 | | 734 | This attribute has several limitations and should only be used in situations where the | 735 | ``--platforms`` flag does not work. See `Cross compilation`_ and `Note on goos and goarch | 736 | attributes`_ for more information. | 737 +----------------------------+-----------------------------+---------------------------------------+ 738 | :param:`goarch` | :type:`string` | :value:`auto` | 739 +----------------------------+-----------------------------+---------------------------------------+ 740 | This is one of the `mode attributes`_ that controls which goarch_ to compile and link for. | 741 | | 742 | If set to anything other than :value:`auto` this overrides the default as set by the current | 743 | target platform and allows for single builds to make binaries for multiple architectures. | 744 | | 745 | Because this has no control over the cc toolchain, it does not work for cgo, so if this | 746 | attribute is set then :param:`pure` must be set to :value:`on`. | 747 | | 748 | This attribute has several limitations and should only be used in situations where the | 749 | ``--platforms`` flag does not work. See `Cross compilation`_ and `Note on goos and goarch | 750 | attributes`_ for more information. | 751 +----------------------------+-----------------------------+---------------------------------------+ 752 | :param:`gc_goopts` | :type:`string_list` | :value:`[]` | 753 +----------------------------+-----------------------------+---------------------------------------+ 754 | List of flags to add to the Go compilation command when using the gc compiler. | 755 | Subject to `"Make variable"`_ substitution and `Bourne shell tokenization`_. | 756 +----------------------------+-----------------------------+---------------------------------------+ 757 | :param:`gc_linkopts` | :type:`string_list` | :value:`[]` | 758 +----------------------------+-----------------------------+---------------------------------------+ 759 | List of flags to add to the Go link command when using the gc compiler. | 760 | Subject to `"Make variable"`_ substitution and `Bourne shell tokenization`_. | 761 +----------------------------+-----------------------------+---------------------------------------+ 762 | :param:`x_defs` | :type:`string_dict` | :value:`{}` | 763 +----------------------------+-----------------------------+---------------------------------------+ 764 | Map of defines to add to the go link command. | 765 | See `Defines and stamping`_ for examples of how to use these. | 766 +----------------------------+-----------------------------+---------------------------------------+ 767 | :param:`cgo` | :type:`boolean` | :value:`False` | 768 +----------------------------+-----------------------------+---------------------------------------+ 769 | If :value:`True`, the binary uses cgo_. | 770 | The cgo tool permits Go code to call C code and vice-versa. | 771 | This does not support calling C++. | 772 | When cgo is set, :param:`srcs` may contain C, C++, Objective-C, Objective-C++, | 773 | and assembly files. These files will be compiled with the compiler from | 774 | the configured C/C++ toolchain. The compiled objects are included in | 775 | the package. | 776 +----------------------------+-----------------------------+---------------------------------------+ 777 | :param:`cdeps` | :type:`label_list` | :value:`None` | 778 +----------------------------+-----------------------------+---------------------------------------+ 779 | The list of other libraries that the c code depends on. | 780 | This can be anything that would be allowed in `cc library deps`_ | 781 | Only valid if :param:`cgo` = :value:`True`. | 782 +----------------------------+-----------------------------+---------------------------------------+ 783 | :param:`copts` | :type:`string_list` | :value:`[]` | 784 +----------------------------+-----------------------------+---------------------------------------+ 785 | List of flags to add to the C compilation command. | 786 | Subject to `"Make variable"`_ substitution and `Bourne shell tokenization`_. | 787 | Only valid if :param:`cgo` = :value:`True`. | 788 +----------------------------+-----------------------------+---------------------------------------+ 789 | :param:`cxxopts` | :type:`string_list` | :value:`[]` | 790 +----------------------------+-----------------------------+---------------------------------------+ 791 | List of flags to add to the C++ compilation command. | 792 | Subject to `"Make variable"`_ substitution and `Bourne shell tokenization`_. | 793 | Only valid if :param:`cgo` = :value:`True`. | 794 +----------------------------+-----------------------------+---------------------------------------+ 795 | :param:`cppopts` | :type:`string_list` | :value:`[]` | 796 +----------------------------+-----------------------------+---------------------------------------+ 797 | List of flags to add to the C/C++ preprocessor command. | 798 | Subject to `"Make variable"`_ substitution and `Bourne shell tokenization`_. | 799 | Only valid if :param:`cgo` = :value:`True`. | 800 +----------------------------+-----------------------------+---------------------------------------+ 801 | :param:`clinkopts` | :type:`string_list` | :value:`[]` | 802 +----------------------------+-----------------------------+---------------------------------------+ 803 | List of flags to add to the C link command. | 804 | Subject to `"Make variable"`_ substitution and `Bourne shell tokenization`_. | 805 | Only valid if :param:`cgo` = :value:`True`. | 806 +----------------------------+-----------------------------+---------------------------------------+ 807 | :param:`rundir` | :type:`string` | The package path | 808 +----------------------------+-----------------------------+---------------------------------------+ 809 | A directory to cd to before the test is run. | 810 | This should be a path relative to the execution dir of the test. | 811 | | 812 | The default behaviour is to change to the workspace relative path, this replicates the normal | 813 | behaviour of ``go test`` so it is easy to write compatible tests. | 814 | | 815 | Setting it to :value:`.` makes the test behave the normal way for a bazel test. | 816 +----------------------------+-----------------------------+---------------------------------------+ 817 | :param:`shard_count` | :type:`integer` | :value:`None` | 818 +----------------------------+-----------------------------+---------------------------------------+ 819 | Non-negative integer less than or equal to 50, optional. | 820 | | 821 | Specifies the number of parallel shards to run the test. Test methods will be split across the | 822 | shards in a round-robin fashion. | 823 | | 824 | For more details on this attribute, consult the official Bazel documentation for shard_count_. | 825 +----------------------------+-----------------------------+---------------------------------------+ 826 827 To write an internal test, reference the library being tested with the :param:`embed` 828 instead of :param:`deps`. This will compile the test sources into the same package as the library 829 sources. 830 831 Internal test example 832 ^^^^^^^^^^^^^^^^^^^^^ 833 834 This builds a test that can use the internal interface of the package being tested. 835 836 In the normal go toolchain this would be the kind of tests formed by adding writing 837 ``<file>_test.go`` files in the same package. 838 839 It references the library being tested with :param:`embed`. 840 841 842 .. code:: bzl 843 844 go_library( 845 name = "go_default_library", 846 srcs = ["lib.go"], 847 ) 848 849 go_test( 850 name = "go_default_test", 851 srcs = ["lib_test.go"], 852 embed = [":go_default_library"], 853 ) 854 855 External test example 856 ^^^^^^^^^^^^^^^^^^^^^ 857 858 This builds a test that can only use the public interface(s) of the packages being tested. 859 860 In the normal go toolchain this would be the kind of tests formed by adding an ``<name>_test`` 861 package. 862 863 It references the library(s) being tested with :param:`deps`. 864 865 .. code:: bzl 866 867 go_library( 868 name = "go_default_library", 869 srcs = ["lib.go"], 870 ) 871 872 go_test( 873 name = "go_default_xtest", 874 srcs = ["lib_x_test.go"], 875 deps = [":go_default_library"], 876 ) 877 878 go_source 879 ~~~~~~~~~ 880 881 This declares a set of source files and related dependencies that can be embedded into one of the 882 other rules. 883 This is used as a way of easily declaring a common set of sources re-used in multiple rules. 884 885 Providers 886 ^^^^^^^^^ 887 888 * GoLibrary_ 889 * GoSource_ 890 891 Attributes 892 ^^^^^^^^^^ 893 894 +----------------------------+-----------------------------+---------------------------------------+ 895 | **Name** | **Type** | **Default value** | 896 +----------------------------+-----------------------------+---------------------------------------+ 897 | :param:`name` | :type:`string` | |mandatory| | 898 +----------------------------+-----------------------------+---------------------------------------+ 899 | A unique name for this rule. | 900 +----------------------------+-----------------------------+---------------------------------------+ 901 | :param:`srcs` | :type:`label_list` | :value:`None` | 902 +----------------------------+-----------------------------+---------------------------------------+ 903 | The list of Go source files that are compiled to create the package. | 904 | The following file types are permitted: :value:`.go, .c, .s, .S .h`. | 905 | The files may contain Go-style `build constraints`_. | 906 +----------------------------+-----------------------------+---------------------------------------+ 907 | :param:`deps` | :type:`label_list` | :value:`None` | 908 +----------------------------+-----------------------------+---------------------------------------+ 909 | List of Go libraries this source list imports directly. | 910 | These may be go_library rules or compatible rules with the GoLibrary_ provider. | 911 +----------------------------+-----------------------------+---------------------------------------+ 912 | :param:`embed` | :type:`label_list` | :value:`None` | 913 +----------------------------+-----------------------------+---------------------------------------+ 914 | List of sources to directly embed in this list. | 915 | These may be go_library rules or compatible rules with the GoSource_ provider. | 916 | These can provide both :param:`srcs` and :param:`deps` to this library. | 917 | See Embedding_ for more information about how and when to use this. | 918 +----------------------------+-----------------------------+---------------------------------------+ 919 | :param:`data` | :type:`label_list` | :value:`None` | 920 +----------------------------+-----------------------------+---------------------------------------+ 921 | The list of files needed by this rule at runtime. Targets named in the data attribute will | 922 | appear in the *.runfiles area of this rule, if it has one. This may include data files needed | 923 | by the binary, or other programs needed by it. See `data dependencies`_ for more information | 924 | about how to depend on and use data files. | 925 +----------------------------+-----------------------------+---------------------------------------+ 926 | :param:`gc_goopts` | :type:`string_list` | :value:`[]` | 927 +----------------------------+-----------------------------+---------------------------------------+ 928 | List of flags to add to the Go compilation command when using the gc compiler. | 929 | Subject to `"Make variable"`_ substitution and `Bourne shell tokenization`_. | 930 +----------------------------+-----------------------------+---------------------------------------+ 931 932 go_path 933 ~~~~~~~ 934 935 ``go_path`` builds a directory structure that can be used with tools that 936 understand the ``GOPATH`` directory layout. This directory structure can be 937 built by zipping, copying, or linking files. 938 939 ``go_path`` can depend on one or more Go targets (i.e., `go_library`_, 940 `go_binary`_, or `go_test`_). It will include packages from those targets, as 941 well as their transitive dependencies. Packages will be in subdirectories named 942 after their ``importpath`` or ``importmap`` attributes under a ``src/`` 943 directory. 944 945 Attributes 946 ^^^^^^^^^^ 947 948 +----------------------------+-----------------------------+---------------------------------------+ 949 | **Name** | **Type** | **Default value** | 950 +----------------------------+-----------------------------+---------------------------------------+ 951 | :param:`name` | :type:`string` | |mandatory| | 952 +----------------------------+-----------------------------+---------------------------------------+ 953 | A unique name for this rule. | 954 +----------------------------+-----------------------------+---------------------------------------+ 955 | :param:`deps` | :type:`label_list` | :value:`[]` | 956 +----------------------------+-----------------------------+---------------------------------------+ 957 | A list of targets that build Go packages. A directory will be generated from | 958 | files in these targets and their transitive dependencies. All targets must | 959 | provide GoArchive_ (`go_library`_, `go_binary`_, `go_test`_, and similar | 960 | rules have this). | 961 | | 962 | Only targets with explicit ``importpath`` attributes will be included in the | 963 | generated directory. Synthetic packages (like the main package produced by | 964 | `go_test`_) and packages with inferred import paths will not be | 965 | included. The values of ``importmap`` attributes may influence the placement | 966 | of packages within the generated directory (for example, in vendor | 967 | directories). | 968 | | 969 | The generated directory will contain original source files, including .go, | 970 | .s, .h, and .c files compiled by cgo. It will not contain files generated by | 971 | tools like cover and cgo, but it will contain generated files passed in | 972 | ``srcs`` attributes like .pb.go files. The generated directory will also | 973 | contain runfiles found in ``data`` attributes. | 974 +----------------------------+-----------------------------+---------------------------------------+ 975 | :param:`data` | :type:`label_list` | :value:`[]` | 976 +----------------------------+-----------------------------+---------------------------------------+ 977 | A list of targets producing data files that will be stored next to the | 978 | ``src/`` directory. Useful for including things like licenses and readmes. | 979 +----------------------------+-----------------------------+---------------------------------------+ 980 | :param:`mode` | :type:`string` | :value:`"copy"` | 981 +----------------------------+-----------------------------+---------------------------------------+ 982 | Determines how the generated directory is provided. May be one of: | 983 | | 984 | * ``"archive"``: The generated directory is packaged as a single .zip file. | 985 | * ``"copy"``: The generated directory is a single tree artifact. Source files | 986 | are copied into the tree. | 987 | * ``"link"``: Source files are symlinked into the tree. All of the symlink | 988 | files are provided as separate output files. | 989 | | 990 | **NOTE:** In ``"copy"`` mode, when a ``GoPath`` is consumed as a set of input | 991 | files or run files, Bazel may provide symbolic links instead of regular files. | 992 | Any program that consumes these files should dereference links, e.g., if you | 993 | run ``tar``, use the ``--dereference`` flag. | 994 +----------------------------+-----------------------------+---------------------------------------+ 995 | :param:`include_data` | :type:`bool` | :value:`True` | 996 +----------------------------+-----------------------------+---------------------------------------+ 997 | When true, data files referenced by libraries, binaries, and tests will be | 998 | included in the output directory. Files listed in the :param:`data` attribute | 999 | for this rule will be included regardless of this attribute. | 1000 +----------------------------+-----------------------------+---------------------------------------+ 1001 1002 go_rule 1003 ~~~~~~~ 1004 1005 This is a wrapper around the normal rule function. 1006 It modifies the attrs and toolchains attributes to make sure everything needed to build a go_context 1007 is present. 1008 1009 Cross compilation 1010 ----------------- 1011 1012 rules_go can cross-compile Go projects to any platform the Go toolchain 1013 supports. The simplest way to do this is by setting the ``--platforms`` flag on 1014 the command line. 1015 1016 .. code:: 1017 1018 $ bazel build --platforms=@io_bazel_rules_go//go/toolchain:linux_amd64 //my/project 1019 1020 You can replace ``linux_amd64`` in the example above with any valid 1021 GOOS / GOARCH pair. To list all platforms, run this command: 1022 1023 .. code:: 1024 1025 $ bazel query 'kind(platform, @io_bazel_rules_go//go/toolchain:all)' 1026 1027 By default, cross-compilation will cause Go targets to be built in "pure mode", 1028 which disables cgo; cgo files will not be compiled, and C/C++ dependencies will 1029 not be compiled or linked. 1030 1031 Cross-compiling cgo code is possible, but not fully supported. You will need to 1032 `write a CROSSTOOL file`_ that describes your C/C++ toolchain. You'll need to 1033 ensure it works by building ``cc_binary`` and ``cc_library`` targets with the 1034 ``--cpu`` command line flag set. Then, to build a mixed Go / C / C++ project, 1035 add ``pure = "off"`` to your ``go_binary`` target and run Bazel with ``--cpu`` 1036 and ``--platforms``. 1037 1038 Platform-specific dependencies 1039 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1040 1041 When cross-compiling, you may have some platform-specific sources and 1042 dependencies. Source files from all platforms can be mixed freely in a single 1043 ``srcs`` list. Source files are filtered using `build constraints`_ (filename 1044 suffixes and ``+build`` tags) before being passed to the compiler. 1045 1046 Platform-specific dependencies are another story. For example, if you are 1047 building a binary for Linux, and it has dependency that should only be built 1048 when targeting Windows, you will need to filter it out using Bazel `select`_ 1049 expressions: 1050 1051 .. code:: bzl 1052 1053 go_binary( 1054 name = "cmd", 1055 srcs = [ 1056 "foo_linux.go", 1057 "foo_windows.go", 1058 ], 1059 deps = [ 1060 # platform agnostic dependencies 1061 "//bar:go_default_library", 1062 ] + select({ 1063 # OS-specific dependencies 1064 "@io_bazel_rules_go//go/platform:linux": [ 1065 "//baz_linux:go_default_library", 1066 ], 1067 "@io_bazel_rules_go//go/platform:windows": [ 1068 "//quux_windows:go_default_library", 1069 ], 1070 "//conditions:default": [], 1071 }), 1072 ) 1073 1074 ``select`` accepts a dictionary argument. The keys are labels that reference 1075 `config_setting`_ rules. The values are lists of labels. Exactly one of these 1076 lists will be selected, depending on the target configuration. rules_go has 1077 pre-declared ``config_setting`` rules for each OS, architecture, and 1078 OS-architecture pair. For a full list, run this command: 1079 1080 .. code:: 1081 1082 $ bazel query 'kind(config_setting, @io_bazel_rules_go//go/platform:all)' 1083 1084 `Gazelle`_ will generate dependencies in this format automatically. 1085 1086 Note on goos and goarch attributes 1087 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1088 1089 It is possible to cross-compile ``go_binary`` and ``go_test`` targets by 1090 setting the ``goos`` and ``goarch`` attributes to the target platform. These 1091 attributes were added for projects that cross-compile binaries for multiple 1092 platforms in the same build, then package the resulting executables. 1093 1094 Bazel does not have a native understanding of the ``goos`` and ``goarch`` 1095 attributes, so values do not affect `select`_ expressions. This means if you use 1096 these attributes with a target that has any transitive platform-specific 1097 dependencies, ``select`` may choose the wrong set of dependencies. Consequently, 1098 if you use ``goos`` or ``goarch`` attributes, you will not be able to safely 1099 generate build files with Gazelle or ``go_repository``. 1100 1101 Additionally, setting ``goos`` and ``goarch`` will not automatically disable 1102 cgo. You should almost always set ``pure = "on"`` together with these 1103 attributes. 1104 1105 Because of these limitations, it's almost always better to cross-compile by 1106 setting ``--platforms`` on the command line instead.