github.com/wolfd/bazel-gazelle@v0.14.0/README.rst (about) 1 Gazelle build file generator 2 ============================ 3 4 .. All external links are here 5 .. _Architecture of Gazelle: Design.rst 6 .. _Repository rules: repository.rst 7 .. _go_repository: repository.rst#go_repository 8 .. _git_repository: repository.rst#git_repository 9 .. _http_archive: repository.rst#http_archive 10 .. _Gazelle in rules_go: https://github.com/bazelbuild/rules_go/tree/master/go/tools/gazelle 11 .. _fix: #fix-and-update 12 .. _update: #fix-and-update 13 .. _Avoiding conflicts with proto rules: https://github.com/bazelbuild/rules_go/blob/master/proto/core.rst#avoiding-conflicts 14 15 .. role:: cmd(code) 16 .. role:: flag(code) 17 .. role:: direc(code) 18 .. role:: param(kbd) 19 .. role:: type(emphasis) 20 .. role:: value(code) 21 .. |mandatory| replace:: **mandatory value** 22 .. End of directives 23 24 Gazelle is a build file generator for Go projects. It can create new 25 BUILD.bazel files for a project that follows "go build" conventions, and it 26 can update existing build files to include new files and options. Gazelle can 27 be invoked directly in a project workspace, or it can be run on an external 28 repository during the build as part of the `go_repository`_ rule. 29 30 *Gazelle is under active development. Its interface and the rules it generates 31 may change. Gazelle is not an official Google product.* 32 33 .. contents:: **Contents** 34 :depth: 2 35 36 **See also:** 37 38 * `Architecture of Gazelle`_ 39 * `Repository rules`_ 40 41 * `go_repository`_ 42 * `git_repository`_ 43 * `http_archive`_ 44 45 * `Avoiding conflicts with proto rules`_ 46 47 Setup 48 ----- 49 50 Running Gazelle with Bazel 51 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 52 53 To use Gazelle in a new project, add the ``bazel_gazelle`` repository and its 54 dependencies to your WORKSPACE file before ``go_rules_dependencies`` is called. 55 It should look like this: 56 57 .. code:: bzl 58 59 load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") 60 http_archive( 61 name = "io_bazel_rules_go", 62 urls = ["https://github.com/bazelbuild/rules_go/releases/download/0.13.0/rules_go-0.13.0.tar.gz"], 63 sha256 = "ba79c532ac400cefd1859cbc8a9829346aa69e3b99482cd5a54432092cbc3933", 64 ) 65 http_archive( 66 name = "bazel_gazelle", 67 urls = ["https://github.com/bazelbuild/bazel-gazelle/releases/download/0.13.0/bazel-gazelle-0.13.0.tar.gz"], 68 sha256 = "bc653d3e058964a5a26dcad02b6c72d7d63e6bb88d94704990b908a1445b8758", 69 ) 70 load("@io_bazel_rules_go//go:def.bzl", "go_rules_dependencies", "go_register_toolchains") 71 go_rules_dependencies() 72 go_register_toolchains() 73 load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies") 74 gazelle_dependencies() 75 76 Add the code below to the BUILD or BUILD.bazel file in the root directory 77 of your repository. Replace the string after ``prefix`` with the portion of 78 your import path that corresponds to your repository. 79 80 .. code:: bzl 81 82 load("@bazel_gazelle//:def.bzl", "gazelle") 83 84 # gazelle:prefix github.com/example/project 85 gazelle(name = "gazelle") 86 87 After adding this code, you can run Gazelle with Bazel. 88 89 .. code:: 90 91 $ bazel run //:gazelle 92 93 This will generate new BUILD.bazel files for your project. You can run the same 94 command in the future to update existing BUILD.bazel files to include new source 95 files or options. 96 97 You can pass additional arguments to Gazelle after a ``--`` argument. This 98 can be used to run alternate commands like ``update-repos`` that the ``gazelle`` 99 rule cannot run directly. 100 101 .. code:: 102 103 $ bazel run //:gazelle -- update-repos -from_file=Gopkg.lock 104 105 Running Gazelle with Go 106 ~~~~~~~~~~~~~~~~~~~~~~~ 107 108 If you have a Go SDK installed, you can install Gazelle in your ``GOPATH`` with 109 the command below: 110 111 .. code:: 112 113 go get -u github.com/bazelbuild/bazel-gazelle/cmd/gazelle 114 115 Make sure to re-run this command to upgrade Gazelle whenever you upgrade 116 rules_go in your repository. 117 118 To generate BUILD.bazel files in a new project, run the command below, replacing 119 the prefix with the portion of your import path that corresponds to your 120 repository. 121 122 .. code:: 123 124 gazelle -go_prefix github.com/my/project 125 126 Compatibility 127 ------------- 128 129 Gazelle generates build files that require a minimum version of ``rules_go`` 130 to build. Check the table below to ensure that you're using compatible versions. 131 132 +---------------------+------------------------------+------------------------------+ 133 | **Gazelle version** | **Minimum rules_go version** | **Maximum rules_go version** | 134 +=====================+==============================+==============================+ 135 | 0.8 | 0.8.0 | n/a | 136 +---------------------+------------------------------+------------------------------+ 137 | 0.9 | 0.9.0 | n/a | 138 +---------------------+------------------------------+------------------------------+ 139 | 0.10.0 | 0.9.0 | 0.11.0 | 140 +---------------------+------------------------------+------------------------------+ 141 | 0.11.0 | 0.11.0 | n/a | 142 +---------------------+------------------------------+------------------------------+ 143 | 0.12.0 | 0.11.0 | n/a | 144 +---------------------+------------------------------+------------------------------+ 145 | 0.13.0 | 0.13.0 | n/a | 146 +---------------------+------------------------------+------------------------------+ 147 148 Usage 149 ----- 150 151 Command line 152 ~~~~~~~~~~~~ 153 154 .. code:: 155 156 gazelle <command> [flags...] [package-dirs...] 157 158 The first argument to Gazelle may be one of the commands below. If no command 159 is specified, ``update`` is assumed. The remaining arguments are specific 160 to each command and are documented below. 161 162 update_ 163 Scans sources files, then generates and updates build files. 164 165 fix_ 166 Same as the ``update`` command, but it also fixes deprecated usage of rules. 167 168 update-repos_ 169 Adds and updates repository rules in the WORKSPACE file. 170 171 Bazel rule 172 ~~~~~~~~~~ 173 174 Gazelle may be run via a rule. See `Running Gazelle with Bazel`_ for setup 175 instructions. This rule builds Gazelle and generates a wrapper script that 176 executes Gazelle with baked-in set of arguments. You can run this script 177 with ``bazel run``, or you can copy it into your workspace and run it directly. 178 179 The following attributes are available on the ``gazelle`` rule. 180 181 +----------------------+---------------------+--------------------------------------+ 182 | **Name** | **Type** | **Default value** | 183 +======================+=====================+======================================+ 184 | :param:`gazelle` | :type:`label` | :value:`@bazel_gazelle//cmd/gazelle` | 185 +----------------------+---------------------+--------------------------------------+ 186 | The ``go_binary`` rule that builds Gazelle. You can substitute a modified | 187 | version of Gazelle with this. | 188 +----------------------+---------------------+--------------------------------------+ 189 | :param:`external` | :type:`string` | :value:`external` | 190 +----------------------+---------------------+--------------------------------------+ 191 | The method for resolving unknown imports to Bazel dependencies. May be | 192 | :value:`external` or :value:`vendored`. | 193 +----------------------+---------------------+--------------------------------------+ 194 | :param:`build_tags` | :type:`string_list` | :value:`[]` | 195 +----------------------+---------------------+--------------------------------------+ 196 | The last of Go build tags that Gazelle should consider to always be true. | 197 +----------------------+---------------------+--------------------------------------+ 198 | :param:`prefix` | :type:`string` | :value:`""` | 199 +----------------------+---------------------+--------------------------------------+ 200 | The import path that corresponds to the repository root directory. | 201 | | 202 | Note: It's usually better to write a directive like | 203 | ``# gazelle:prefix example.com/repo`` in your build file instead of setting | 204 | this attribute. | 205 +----------------------+---------------------+--------------------------------------+ 206 | :param:`extra_args` | :type:`string_list` | :value:`[]` | 207 +----------------------+---------------------+--------------------------------------+ 208 | A list of extra command line arguments passed to Gazelle. | 209 +----------------------+---------------------+--------------------------------------+ 210 | :param:`command` | :type:`string` | :value:`update` | 211 +----------------------+---------------------+--------------------------------------+ 212 | The Gazelle command to use. May be :value:`fix` or :value:`update`. To run | 213 | a different command, e.g., :value:`update-repos`, you'll need to copy the | 214 | invoke the generated wrapper script directly with explicit arguments. | 215 +----------------------+---------------------+--------------------------------------+ 216 217 ``fix`` and ``update`` 218 ~~~~~~~~~~~~~~~~~~~~~~ 219 220 The ``update`` command is the most common way of running Gazelle. Gazelle will 221 scan sources in directories throughout the repository, then create and update 222 build files. 223 224 The ``fix`` command does everything ``update`` does, but it also fixes 225 deprecated usage of rules, analogous to ``go fix``. For example, ``cgo_library`` 226 will be consolidated with ``go_library``. This command may delete or rename 227 rules, so it's not on by default. See `Fix command transformations`_ 228 for details. 229 230 Both commands accept a list of directories to process as positional arguments. 231 If no directories are specified, Gazelle will process the current directory. 232 Subdirectories will be processed recursively. 233 234 The following flags are accepted: 235 236 +--------------------------------------------------------------+-----------------------------------+ 237 | **Name** | **Default value** | 238 +==============================================================+===================================+ 239 | :flag:`-build_file_name file1,file2,...` | :value:`BUILD.bazel,BUILD` | 240 +--------------------------------------------------------------+-----------------------------------+ 241 | Comma-separated list of file names. Gazelle recognizes these files as Bazel | 242 | build files. New files will use the first name in this list. Use this if | 243 | your project contains non-Bazel files named ``BUILD`` (or ``build`` on | 244 | case-insensitive file systems). | 245 +--------------------------------------------------------------+-----------------------------------+ 246 | :flag:`-build_tags tag1,tag2` | | 247 +--------------------------------------------------------------+-----------------------------------+ 248 | List of Go build tags Gazelle will consider to be true. Gazelle applies | 249 | constraints when generating Go rules. It assumes certain tags are true on | 250 | certain platforms (for example, ``amd64,linux``). It assumes all Go release | 251 | tags are true (for example, ``go1.8``). It considers other tags to be false | 252 | (for example, ``ignore``). This flag overrides that behavior. | 253 | | 254 | Bazel may still filter sources with these tags. Use | 255 | ``bazel build --features gotags=foo,bar`` to set tags at build time. | 256 +--------------------------------------------------------------+-----------------------------------+ 257 | :flag:`-external external|vendored` | :value:`external` | 258 +--------------------------------------------------------------+-----------------------------------+ 259 | Determines how Gazelle resolves import paths. May be :value:`external` or | 260 | :value:`vendored`. Gazelle translates Go import paths to Bazel labels when | 261 | resolving library dependencies. Import paths that start with the | 262 | ``go_prefix`` are resolved to local labels, but other imports | 263 | are resolved based on this mode. In :value:`external` mode, paths are | 264 | resolved using an external dependency in the WORKSPACE file (Gazelle does | 265 | not create or maintain these dependencies yet). In :value:`vendored` mode, | 266 | paths are resolved to a library in the vendor directory. | 267 +--------------------------------------------------------------+-----------------------------------+ 268 | :flag:`-go_prefix example.com/repo` | | 269 +--------------------------------------------------------------+-----------------------------------+ 270 | A prefix of import paths for libraries in the repository that corresponds to | 271 | the repository root. Gazelle infers this from the ``go_prefix`` rule in the | 272 | root BUILD.bazel file, if it exists. If not, this option is mandatory. | 273 | | 274 | This prefix is used to determine whether an import path refers to a library | 275 | in the current repository or an external dependency. | 276 +--------------------------------------------------------------+-----------------------------------+ 277 | :flag:`-known_import example.com` | | 278 +--------------------------------------------------------------+-----------------------------------+ 279 | Skips import path resolution for a known domain. May be repeated. | 280 | | 281 | When Gazelle resolves an import path to an external dependency, it attempts | 282 | to discover the remote repository root over HTTP. Gazelle skips this | 283 | discovery step for a few well-known domains with predictable structure, like | 284 | golang.org and github.com. This flag specifies additional domains to skip, | 285 | which is useful in situations where the lookup would fail for some reason. | 286 +--------------------------------------------------------------+-----------------------------------+ 287 | :flag:`-mode fix|print|diff` | :value:`fix` | 288 +--------------------------------------------------------------+-----------------------------------+ 289 | Method for emitting merged build files. | 290 | | 291 | In ``fix`` mode, Gazelle writes generated and merged files to disk. In | 292 | ``print`` mode, it prints them to stdout. In ``diff`` mode, it prints a | 293 | unified diff. | 294 +--------------------------------------------------------------+-----------------------------------+ 295 | :flag:`-proto default|package|legacy|disable|disable_global` | :value:`default` | 296 +--------------------------------------------------------------+-----------------------------------+ 297 | Determines how Gazelle should generate rules for .proto files. See details | 298 | in `Directives`_ below. | 299 +--------------------------------------------------------------+-----------------------------------+ 300 | :flag:`-proto_group group` | :value:`""` | 301 +--------------------------------------------------------------+-----------------------------------+ 302 | Determines the proto option Gazelle uses to group .proto files into rules | 303 | when in ``package`` mode. See details in `Directives`_ below. | 304 +--------------------------------------------------------------+-----------------------------------+ 305 | :flag:`-repo_root dir` | | 306 +--------------------------------------------------------------+-----------------------------------+ 307 | The root directory of the repository. Gazelle normally infers this to be the | 308 | directory containing the WORKSPACE file. | 309 | | 310 | Gazelle will not process packages outside this directory. | 311 +--------------------------------------------------------------+-----------------------------------+ 312 313 ``update-repos`` 314 ~~~~~~~~~~~~~~~~ 315 316 The ``update-repos`` command updates repository rules in the WORKSPACE file. 317 It can be used to add new repository rules or update existing rules to the 318 latest version. It can also import repository rules from a dep Gopkg.lock file. 319 320 .. code:: bash 321 322 # Add or update a repository by import path 323 $ gazelle update-repos example.com/new/repo 324 325 # Import repositories from Gopkg.lock 326 $ gazelle update-repos -from_file=Gopkg.lock 327 328 :Note: ``update-repos`` is not directly supported by the ``gazelle`` rule. 329 You can run it through the ``gazelle`` rule by passing extra arguments after 330 ``--``. For example: 331 332 .. code:: 333 334 $ bazel run //:gazelle -- update-repos example.com/new/repo 335 336 The following flags are accepted: 337 338 +------------------------------+-----------------------------------------------+ 339 | **Name** | **Default value** | 340 +==============================+===============================================+ 341 | :flag:`-from_file lock-file` | | 342 +------------------------------+-----------------------------------------------+ 343 | Import repositories from a vendoring tool's lock file as `go_repository`_ | 344 | rules. These rules will be added to the bottom of WORKSPACE or merged with | 345 | existing rules. | 346 | | 347 | The lock file format is inferred from the file's base name. Currently, only | 348 | Gopkg.lock is supported. | 349 +------------------------------+-----------------------------------------------+ 350 | :flag:`-repo_root dir` | | 351 +------------------------------+-----------------------------------------------+ 352 | The root directory of the repository. Gazelle normally infers this to be the | 353 | directory containing the WORKSPACE file. | 354 | | 355 | Gazelle will not process packages outside this directory. | 356 +------------------------------+-----------------------------------------------+ 357 358 Bazel rule 359 ~~~~~~~~~~ 360 361 When Gazelle is run by Bazel, most of the flags above can be encoded in the 362 ``gazelle`` rule. For example: 363 364 .. code:: bzl 365 366 load("@bazel_gazelle//:def.bzl", "gazelle") 367 368 gazelle( 369 name = "gazelle", 370 command = "fix", 371 prefix = "github.com/example/project", 372 external = "vendored", 373 build_tags = [ 374 "integration", 375 "debug", 376 ], 377 extra_args = [ 378 "-build_file_name", 379 "BUILD,BUILD.bazel", 380 ], 381 ) 382 383 Directives 384 ~~~~~~~~~~ 385 386 Gazelle can be configured with *directives*, which are written as top-level 387 comments in build files. Most options that can be set on the command line 388 can also be set using directives. Some options can only be set with 389 directives. 390 391 Directive comments have the form ``# gazelle:key value``. For example: 392 393 .. code:: bzl 394 395 load("@io_bazel_rules_go//go:def.bzl", "go_library") 396 397 # gazelle:prefix github.com/example/project 398 # gazelle:build_file_name BUILD,BUILD.bazel 399 400 go_library( 401 name = "go_default_library", 402 srcs = ["example.go"], 403 importpath = "github.com/example/project", 404 visibility = ["//visibility:public"], 405 ) 406 407 Directives apply in the directory where they are set *and* in subdirectories. 408 This means, for example, if you set ``# gazelle:prefix`` in the build file 409 in your project's root directory, it affects your whole project. If you 410 set it in a subdirectory, it only affects rules in that subtree. 411 412 The following directives are recognized: 413 414 +------------------------------------------+-----------------------------------+ 415 | **Directive** | **Default value** | 416 +==========================================+===================================+ 417 | :direc:`# gazelle:build_file_name names` | :value:`BUILD.bazel,BUILD` | 418 +------------------------------------------+-----------------------------------+ 419 | Comma-separated list of file names. Gazelle recognizes these files as Bazel | 420 | build files. New files will use the first name in this list. Use this if | 421 | your project contains non-Bazel files named ``BUILD`` (or ``build`` on | 422 | case-insensitive file systems). | 423 +------------------------------------------+-----------------------------------+ 424 | :direc:`# gazelle:build_tags foo,bar` | none | 425 +------------------------------------------+-----------------------------------+ 426 | List of Go build tags Gazelle will consider to be true. Gazelle applies | 427 | constraints when generating Go rules. It assumes certain tags are true on | 428 | certain platforms (for example, ``amd64,linux``). It assumes all Go release | 429 | tags are true (for example, ``go1.8``). It considers other tags to be false | 430 | (for example, ``ignore``). This flag overrides that behavior. | 431 | | 432 | Bazel may still filter sources with these tags. Use | 433 | ``bazel build --features gotags=foo,bar`` to set tags at build time. | 434 +------------------------------------------+-----------------------------------+ 435 | :direc:`# gazelle:exclude path` | n/a | 436 +------------------------------------------+-----------------------------------+ 437 | Prevents Gazelle from processing a file or directory. If the path refers to | 438 | a source file, Gazelle won't include it in any rules. If the path refers to | 439 | a directory, Gazelle won't recurse into it. The path may refer to something | 440 | withinin a subdirectory, for example, a testdata directory somewhere in a | 441 | vendor tree. This directive may be repeated to exclude multiple paths, one | 442 | per line. | 443 +------------------------------------------+-----------------------------------+ 444 | :direc:`# gazelle:ignore` | n/a | 445 +------------------------------------------+-----------------------------------+ 446 | Prevents Gazelle from modifying the build file. Gazelle will still read | 447 | rules in the build file and may modify build files in subdirectories. | 448 +------------------------------------------+-----------------------------------+ 449 | :direc:`# gazelle:importmap_prefix path` | See below | 450 +------------------------------------------+-----------------------------------+ 451 | A prefix for ``importmap`` attributes in library rules. Gazelle will set | 452 | an ``importmap`` on a ``go_library`` or ``go_proto_library`` by | 453 | concatenating this with the relative path from the directory where the | 454 | prefix is set to the library. For example, if ``importmap_prefix`` is set | 455 | to ``"x/example.com/repo"`` in the build file ``//foo/bar:BUILD.bazel``, | 456 | then a library in ``foo/bar/baz`` will have the ``importmap`` of | 457 | ``"x/example.com/repo/baz"``. | 458 | | 459 | ``importmap`` is not set when it matches ``importpath``. | 460 | | 461 | As a special case, when Gazelle enters a directory named ``vendor``, it | 462 | sets ``importmap_prefix`` to a string based on the repository name and the | 463 | location of the vendor directory. If you wish to override this, you'll need | 464 | to set ``importmap_prefix`` explicitly in the vendor directory. | 465 +------------------------------------------+-----------------------------------+ 466 | :direc:`# gazelle:prefix path` | n/a | 467 +------------------------------------------+-----------------------------------+ 468 | A prefix for ``importpath`` attributes on library rules. Gazelle will set | 469 | an ``importpath`` on a ``go_library`` or ``go_proto_library`` by | 470 | concatenating this with the relative path from the directory where the | 471 | prefix is set to the library. Most commonly, ``prefix`` is set to the | 472 | name of a repository in the root directory of a repository. For example, | 473 | in this repository, ``prefix`` is set in ``//:BUILD.bazel`` to | 474 | ``github.com/bazelbuild/bazel-gazelle``. The ``go_library`` in | 475 | ``//cmd/gazelle`` is assigned the ``importpath`` | 476 | ``"github.com/bazelbuild/bazel-gazelle/cmd/gazelle"``. | 477 | | 478 | As a special case, when Gazelle enters a directory named ``vendor``, it sets | 479 | ``prefix`` to the empty string. This automatically gives vendored libraries | 480 | an intuitive ``importpath``. | 481 +------------------------------------------+-----------------------------------+ 482 | :direc:`# gazelle:proto mode` | :value:`default` | 483 +------------------------------------------+-----------------------------------+ 484 | Tells Gazelle how to generate rules for .proto files. Valid values are: | 485 | | 486 | * ``default``: ``proto_library``, ``go_proto_library``, and ``go_library`` | 487 | rules are generated using ``@io_bazel_rules_go//proto:def.bzl``. Only one | 488 | of each rule may be generated per directory. This is the default mode. | 489 | * ``package``: multiple ``proto_library`` and ``go_proto_library`` rules | 490 | may be generated in the same directory. .proto files are grouped into | 491 | rules based on their package name or another option (see ``proto_group``). | 492 | * ``legacy``: ``filegroup`` rules are generated for use by | 493 | ``@io_bazel_rules_go//proto:go_proto_library.bzl``. ``go_proto_library`` | 494 | rules must be written by hand. Gazelle will run in this mode automatically | 495 | if ``go_proto_library.bzl`` is loaded to avoid disrupting existing | 496 | projects, but this can be overridden with a directive. | 497 | * ``disable``: .proto files are ignored. Gazelle will run in this mode | 498 | automatically if ``go_proto_library`` is loaded from any other source, | 499 | but this can be overridden with a directive. | 500 | * ``disable_global``: like ``disable`` mode, but also prevents Gazelle from | 501 | using any special cases in dependency resolution for Well Known Types and | 502 | Google APIs. Useful for avoiding build-time dependencies on protoc. | 503 | | 504 | This directive applies to the current directory and subdirectories. As a | 505 | special case, when Gazelle enters a directory named ``vendor``, if the proto | 506 | mode isn't set explicitly in a parent directory or on the command line, | 507 | Gazelle will run in ``disable`` mode. Additionally, if the file | 508 | ``@io_bazel_rules_go//proto:go_proto_library.bzl`` is loaded, Gazelle | 509 | will run in ``legacy`` mode. | 510 +------------------------------------------+-----------------------------------+ 511 | :direc:`# gazelle:proto_group option` | :value:`""` | 512 +------------------------------------------+-----------------------------------+ 513 | *This directive is only effective in* ``package`` *mode (see above).* | 514 | | 515 | Specifies an option that Gazelle can use to group .proto files into rules. | 516 | For example, when set to ``go_package``, .proto files with the same | 517 | ``option go_package`` will be grouped together. | 518 | | 519 | When this directive is set to the empty string, Gazelle will group packages | 520 | by their proto package statement. | 521 | | 522 | Rule names are generated based on the last run of identifier characters | 523 | in the package name. For example, if the package is ``"foo/bar/baz"``, the | 524 | ``proto_library`` rule will be named ``baz_proto``. | 525 +------------------------------------------+-----------------------------------+ 526 527 Keep comments 528 ~~~~~~~~~~~~~ 529 530 In addition to directives, Gazelle supports ``# keep`` comments that protect 531 parts of build files from being modified. ``# keep`` may be written before 532 a rule, before an attribute, or after a string within a list. 533 534 Example 535 ^^^^^^^ 536 537 Suppose you have a library that includes a generated .go file. Gazelle won't 538 know what imports to resolve, so you may need to add dependencies manually with 539 ``# keep`` comments. 540 541 .. code:: bzl 542 543 load("@io_bazel_rules_go//go:def.bzl", "go_library") 544 load("@com_github_example_gen//:gen.bzl", "gen_go_file") 545 546 gen_go_file( 547 name = "magic", 548 srcs = ["magic.go.in"], 549 outs = ["magic.go"], 550 ) 551 552 go_library( 553 name = "go_default_library", 554 srcs = ["magic.go"], 555 visibility = ["//visibility:public"], 556 deps = [ 557 "@com_github_example_gen//:go_default_library", # keep 558 ], 559 ) 560 561 Fix command transformations 562 --------------------------- 563 564 Gazelle will generate and update build files when invoked with either 565 ``gazelle update`` or ``gazelle fix`` (``update`` is the default). Both commands 566 perform several transformations to fix deprecated usage of the Go rules. 567 ``update`` performs a safe set of tranformations, while ``fix`` performs some 568 additional transformations that may delete or rename rules. 569 570 The following transformations are performed: 571 572 **Migrate library to embed (fix and update):** Gazelle replaces ``library`` 573 attributes with ``embed`` attributes. 574 575 **Migrate gRPC compilers (fix and update):** Gazelle converts 576 ``go_grpc_library`` rules to ``go_proto_library`` rules with 577 ``compilers = ["@io_bazel_rules_go//proto:go_grpc"]``. 578 579 **Flatten srcs (fix and update):** Gazelle converts ``srcs`` attributes that 580 use OS and architecture-specific ``select`` expressions to flat lists. 581 rules_go filters these sources anyway. 582 583 **Squash cgo libraries (fix only)**: Gazelle will remove `cgo_library` rules 584 named ``cgo_default_library`` and merge their attributes with a ``go_library`` 585 rule in the same package named ``go_default_library``. If no such ``go_library`` 586 rule exists, a new one will be created. Other ``cgo_library`` rules will not be 587 removed. 588 589 **Squash external tests (fix only)**: Gazelle will squash ``go_test`` rules 590 named ``go_default_xtest`` into ``go_default_test``. Earlier versions of 591 rules_go required internal and external tests to be built separately, but 592 this is no longer needed. 593 594 **Remove legacy protos (fix only)**: Gazelle will remove usage of 595 ``go_proto_library`` rules loaded from 596 ``@io_bazel_rules_go//proto:go_proto_library.bzl`` and ``filegroup`` rules named 597 ``go_default_library_protos``. Newly generated proto rules will take their 598 place. Since ``filegroup`` isn't needed anymore and ``go_proto_library`` has 599 different attributes and was always written by hand, Gazelle will not attempt to 600 merge anything from these rules with the newly generated rules. 601 602 This transformation is only applied in the default proto mode. Since Gazelle 603 will run in legacy proto mode if ``go_proto_library.bzl`` is loaded, this 604 transformation is not usually applied. You can set the proto mode explicitly 605 using the directive ``# gazelle:proto default``. 606 607 **Update loads of gazelle rule (fix and update)**: Gazelle will remove loads 608 of ``gazelle`` from ``@io_bazel_rules_go//go:def.bzl``. It will automatically 609 add a load from ``@bazel_gazelle//:def.bzl`` if ``gazelle`` is not loaded 610 from another location.