github.com/bazelbuild/bazel-gazelle@v0.36.1-0.20240520142334-61b277ba6fed/README.rst (about) 1 Gazelle build file generator 2 ============================ 3 4 .. All external links are here 5 .. _a gazelle extension: https://github.com/bazel-contrib/rules_jvm/tree/main/java/gazelle 6 .. _Kotlin Support: https://github.com/aspect-build/aspect-cli/blob/main/gazelle/kotlin/ 7 .. _JavaScript and TypeScript Support: https://github.com/aspect-build/aspect-cli/blob/main/gazelle/js/ 8 .. _Architecture of Gazelle: Design.rst 9 .. _Repository rules: repository.md 10 .. _go_repository: repository.md#go_repository 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 .. _gazelle rule: #bazel-rule 15 .. _doublestar.Match: https://github.com/bmatcuk/doublestar#match 16 .. _Extending Gazelle: extend.md 17 .. _extended: `Extending Gazelle`_ 18 .. _gazelle_binary: extend.md#gazelle_binary 19 .. _import_prefix: https://docs.bazel.build/versions/master/be/protocol-buffer.html#proto_library.import_prefix 20 .. _strip_import_prefix: https://docs.bazel.build/versions/master/be/protocol-buffer.html#proto_library.strip_import_prefix 21 .. _buildozer: https://github.com/bazelbuild/buildtools/tree/master/buildozer 22 .. _Go Release Policy: https://golang.org/doc/devel/release.html#policy 23 .. _bazel-go-discuss: https://groups.google.com/forum/#!forum/bazel-go-discuss 24 .. _#bazel on Go Slack: https://gophers.slack.com/archives/C1SCQE54N 25 .. _#go on Bazel Slack: https://bazelbuild.slack.com/archives/CDBP88Z0D 26 .. _#514: https://github.com/bazelbuild/rules_python/pull/514 27 .. _#1030: https://github.com/bazelbuild/bazel-gazelle/issues/1030 28 .. _rules_jvm: https://github.com/bazel-contrib/rules_jvm 29 .. _rules_python: https://github.com/bazelbuild/rules_python 30 .. _rules_r: https://github.com/grailbio/rules_r 31 .. _rules_haskell: https://github.com/tweag/rules_haskell 32 .. _rules_nodejs_gazelle: https://github.com/benchsci/rules_nodejs_gazelle 33 .. _bazel-skylib: https://github.com/bazelbuild/bazel-skylib 34 .. _bazel_skylib/gazelle/bzl: https://github.com/bazelbuild/bazel-skylib/tree/master/gazelle/bzl 35 .. _gazelle_cabal: https://github.com/tweag/gazelle_cabal 36 .. _gazelle_haskell_modules: https://github.com/tweag/gazelle_haskell_modules 37 .. _stackb/rules_proto: https://github.com/stackb/rules_proto 38 .. _Open a PR: https://github.com/bazelbuild/bazel-gazelle/edit/master/README.rst 39 .. _Bazel Slack: https://slack.bazel.build 40 .. _rules_swift_package_manager: https://github.com/cgrindel/rules_swift_package_manager 41 .. _gazelle_rust: https://github.com/Calsign/gazelle_rust 42 .. _rules_rust: https://github.com/bazelbuild/rules_rust 43 44 .. role:: cmd(code) 45 .. role:: flag(code) 46 .. role:: direc(code) 47 .. role:: kbd 48 .. role:: param(kbd) 49 .. role:: type(emphasis) 50 .. role:: value(code) 51 .. |mandatory| replace:: **mandatory value** 52 .. End of directives 53 54 Gazelle is a build file generator for Bazel projects. It can create new 55 BUILD.bazel files for a project that follows language conventions, and it can 56 update existing build files to include new sources, dependencies, and 57 options. Gazelle natively supports Go and protobuf, and it may be extended_ 58 to support new languages and custom rule sets. 59 60 Gazelle may be run by Bazel using the `gazelle rule`_, or it may be installed 61 and run as a command line tool. Gazelle can also generate build files for 62 external repositories as part of the `go_repository`_ rule. 63 64 *Gazelle is under active development. Its interface and the rules it generates 65 may change. Gazelle is not an official Google product.* 66 67 Mailing list: `bazel-go-discuss`_ 68 69 Slack: `#go on Bazel Slack`_, `#bazel on Go Slack`_ 70 71 *rules_go and Gazelle are getting community maintainers! If you are a regular 72 user of either project and are interested in helping out with development, 73 code reviews, and issue triage, please drop by our Slack channels (linked above) 74 and say hello!* 75 76 .. contents:: **Contents** 77 :depth: 2 78 79 **See also:** 80 81 * `Architecture of Gazelle`_ 82 * `Repository rules`_ 83 84 * `go_repository`_ 85 86 * `Extending Gazelle`_ 87 * `Avoiding conflicts with proto rules`_ 88 89 Supported languages 90 ------------------- 91 92 Gazelle can generate Bazel BUILD files for many languages: 93 94 * Go 95 96 Go supported is included here in bazel-gazelle, see below. 97 98 * Haskell 99 100 Tweag's `rules_haskell`_ has two extensions: `gazelle_cabal`_, for generating rules from Cabal files 101 and `gazelle_haskell_modules`_ for even more fine-grained build definitions. 102 103 * Java 104 105 bazel-contrib's `rules_jvm`_ extensions include `a gazelle extension`_ for 106 generating ``java_library``, ``java_binary``, ``java_test``, and ``java_test_suite`` rules. 107 108 * JavaScript / TypeScript 109 110 Aspect provides `JavaScript and TypeScript Support`_ in aspect-cli (also usable separately). 111 112 BenchSci's `rules_nodejs_gazelle`_ supports generating `ts_project`, `js_library`, `jest_test`, 113 and `web_asset` rules, and is able to support module bundlers like Webpack and Next.js 114 115 116 * Kotlin 117 118 Aspect Build provides some `Kotlin Support`_ in the repo of their aspect-cli (also usable separately). 119 Still under development, please check the README for currently available features. 120 121 * Protocol Buffers 122 123 Support for the `proto_library` rule, as well as `go_proto_library` is in this repository, see below. 124 Other language-specific proto rules are not supported here. 125 `stackb/rules_proto`_ is a good resource for these rules. 126 127 * Python 128 129 `rules_python`_ has an extension for generating ``py_library``, ``py_binary``, and ``py_test`` rules. 130 131 * R 132 133 `rules_r`_ has an extension for generating rules for R package builds and tests. 134 135 * Rust 136 137 `gazelle_rust`_ is an extension for generating `rules_rust`_ targets. 138 139 * Starlark 140 141 `bazel-skylib`_ has an extension for generating ``bzl_library`` rules. See `bazel_skylib/gazelle/bzl`_. 142 143 * Swift 144 145 `rules_swift_package_manager`_ has an extension for generating ``swift_library``, ``swift_binary``, and 146 ``swift_test`` rules. It also includes facilities for resolving, downloading and building external Swift 147 packages for a Bazel workspace. 148 149 If you know of an extension which could be linked here, please `open a PR`_! 150 151 More languages can be added by `Extending Gazelle`_. 152 Chat with us in the ``#gazelle`` channel on `Bazel Slack`_ if you'd like to discuss your design. 153 154 If you've written your own extension, please consider open-sourcing it for 155 use by the rest of the community. 156 Note that such extensions belong in a language-specific repository, not in bazel-gazelle. 157 See discussion in `#1030`_. 158 159 Setup 160 ----- 161 162 Running Gazelle with Bazel 163 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 164 165 To use Gazelle in a new project, add the ``bazel_gazelle`` repository and its 166 dependencies to your WORKSPACE file and call ``gazelle_dependencies``. It 167 should look like this: 168 169 .. code:: bzl 170 171 load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") 172 173 http_archive( 174 name = "io_bazel_rules_go", 175 sha256 = "80a98277ad1311dacd837f9b16db62887702e9f1d1c4c9f796d0121a46c8e184", 176 urls = [ 177 "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.46.0/rules_go-v0.46.0.zip", 178 "https://github.com/bazelbuild/rules_go/releases/download/v0.46.0/rules_go-v0.46.0.zip", 179 ], 180 ) 181 182 http_archive( 183 name = "bazel_gazelle", 184 integrity = "sha256-MpOL2hbmcABjA1R5Bj2dJMYO2o15/Uc5Vj9Q0zHLMgk=", 185 urls = [ 186 "https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.35.0/bazel-gazelle-v0.35.0.tar.gz", 187 "https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.35.0/bazel-gazelle-v0.35.0.tar.gz", 188 ], 189 ) 190 191 192 load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies") 193 load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies", "go_repository") 194 195 ############################################################ 196 # Define your own dependencies here using go_repository. 197 # Else, dependencies declared by rules_go/gazelle will be used. 198 # The first declaration of an external repository "wins". 199 ############################################################ 200 201 go_rules_dependencies() 202 203 go_register_toolchains(version = "1.20.5") 204 205 gazelle_dependencies() 206 207 ``gazelle_dependencies`` supports optional argument ``go_env`` (dict-mapping) 208 to set project specific go environment variables. If you are using a 209 `WORKSPACE.bazel` file, you will need to specify that using: 210 211 .. code:: bzl 212 213 gazelle_dependencies(go_repository_default_config = "//:WORKSPACE.bazel") 214 215 Add the code below to the BUILD or BUILD.bazel file in the root directory 216 of your repository. 217 218 **Important:** For Go projects, replace the string after ``prefix`` with 219 the portion of your import path that corresponds to your repository. 220 221 .. code:: bzl 222 223 load("@bazel_gazelle//:def.bzl", "gazelle") 224 225 # gazelle:prefix github.com/example/project 226 gazelle(name = "gazelle") 227 228 After adding this code, you can run Gazelle with Bazel. 229 230 .. code:: 231 232 $ bazel run //:gazelle 233 234 This will generate new BUILD.bazel files for your project. You can run the same 235 command in the future to update existing BUILD.bazel files to include new source 236 files or options. 237 238 You can write other ``gazelle`` rules to run alternate commands like ``update-repos``. 239 240 .. code:: bzl 241 242 gazelle( 243 name = "gazelle-update-repos", 244 args = [ 245 "-from_file=go.mod", 246 "-to_macro=deps.bzl%go_dependencies", 247 "-prune", 248 ], 249 command = "update-repos", 250 ) 251 252 You can also pass additional arguments to Gazelle after a ``--`` argument. 253 254 .. code:: 255 256 $ bazel run //:gazelle -- update-repos -from_file=go.mod -to_macro=deps.bzl%go_dependencies 257 258 After running ``update-repos``, you might want to run ``bazel run //:gazelle`` again, as the 259 ``update-repos`` command can affect the output of a normal run of Gazelle. 260 261 Running Gazelle with Go 262 ~~~~~~~~~~~~~~~~~~~~~~~ 263 264 If you have a Go toolchain installed, you can install Gazelle with the 265 command below: 266 267 .. code:: 268 269 go install github.com/bazelbuild/bazel-gazelle/cmd/gazelle@latest 270 271 Make sure to re-run this command to upgrade Gazelle whenever you upgrade 272 rules_go in your repository. 273 274 To generate BUILD.bazel files in a new project, run the command below, replacing 275 the prefix with the portion of your import path that corresponds to your 276 repository. 277 278 .. code:: 279 280 gazelle -go_prefix github.com/example/project 281 282 Most of Gazelle's command-line arguments can be expressed as special comments 283 in build files. See Directives_ below. You may want to copy this line into 284 your root build files to avoid having to type ``-go_prefix`` every time. 285 286 .. code:: bzl 287 288 # gazelle:prefix github.com/example/project 289 290 Compatibility with Go 291 --------------------- 292 293 Gazelle is compatible with supported releases of Go, per the 294 `Go Release Policy`_. The Go Team officially supports the current and previous 295 minor releases. Older releases are not supported and don't receive bug fixes 296 or security updates. 297 298 Gazelle may use language and library features from the oldest supported release. 299 300 Compatibility with rules_go 301 --------------------------- 302 303 Gazelle generates build files that use features in newer versions of 304 ``rules_go``. Newer versions of Gazelle *may* generate build files that work 305 with older versions of ``rules_go``, but check the table below to ensure 306 you're using a compatible version. 307 308 +---------------------+------------------------------+------------------------------+ 309 | **Gazelle version** | **Minimum rules_go version** | **Maximum rules_go version** | 310 +=====================+==============================+==============================+ 311 | 0.8 | 0.8 | n/a | 312 +---------------------+------------------------------+------------------------------+ 313 | 0.9 | 0.9 | n/a | 314 +---------------------+------------------------------+------------------------------+ 315 | 0.10 | 0.9 | 0.11 | 316 +---------------------+------------------------------+------------------------------+ 317 | 0.11 | 0.11 | 0.24 | 318 +---------------------+------------------------------+------------------------------+ 319 | 0.12 | 0.11 | 0.24 | 320 +---------------------+------------------------------+------------------------------+ 321 | 0.13 | 0.13 | 0.24 | 322 +---------------------+------------------------------+------------------------------+ 323 | 0.14 | 0.13 | 0.24 | 324 +---------------------+------------------------------+------------------------------+ 325 | 0.15 | 0.13 | 0.24 | 326 +---------------------+------------------------------+------------------------------+ 327 | 0.16 | 0.13 | 0.24 | 328 +---------------------+------------------------------+------------------------------+ 329 | 0.17 | 0.13 | 0.24 | 330 +---------------------+------------------------------+------------------------------+ 331 | 0.18 | 0.19 | 0.24 | 332 +---------------------+------------------------------+------------------------------+ 333 | 0.19 | 0.19 | 0.24 | 334 +---------------------+------------------------------+------------------------------+ 335 | 0.20 | 0.20 | 0.24 | 336 +---------------------+------------------------------+------------------------------+ 337 | 0.21 | 0.20 | 0.24 | 338 +---------------------+------------------------------+------------------------------+ 339 | 0.22 | 0.20 | 0.24 | 340 +---------------------+------------------------------+------------------------------+ 341 | 0.23 | 0.26 | 0.28 | 342 +---------------------+------------------------------+------------------------------+ 343 | 0.24 | 0.29 | 0.40 | 344 +---------------------+------------------------------+------------------------------+ 345 | 0.25 | 0.29 | 0.40 | 346 +---------------------+------------------------------+------------------------------+ 347 | 0.26 | 0.29 | 0.40 | 348 +---------------------+------------------------------+------------------------------+ 349 | 0.27 | 0.29 | 0.40 | 350 +---------------------+------------------------------+------------------------------+ 351 | 0.28 | 0.35 | 0.40 | 352 +---------------------+------------------------------+------------------------------+ 353 | 0.29 | 0.35 | 0.40 | 354 +---------------------+------------------------------+------------------------------+ 355 | 0.30 | 0.35 | 0.40 | 356 +---------------------+------------------------------+------------------------------+ 357 | 0.31 | 0.35 | 0.40 | 358 +---------------------+------------------------------+------------------------------+ 359 | 0.32 | **0.41** | n/a | 360 +---------------------+------------------------------+------------------------------+ 361 | 0.33 | 0.41 | n/a | 362 +---------------------+------------------------------+------------------------------+ 363 | 0.34 | 0.41 | n/a | 364 +---------------------+------------------------------+------------------------------+ 365 | 0.35 | 0.41 | n/a | 366 +---------------------+------------------------------+------------------------------+ 367 368 Usage 369 ----- 370 371 Command line 372 ~~~~~~~~~~~~ 373 374 .. code:: 375 376 gazelle <command> [flags...] [package-dirs...] 377 378 The first argument to Gazelle may be one of the commands below. If no command 379 is specified, ``update`` is assumed. The remaining arguments are specific 380 to each command and are documented below. 381 382 update_ 383 Scans sources files, then generates and updates build files. 384 385 fix_ 386 Same as the ``update`` command, but it also fixes deprecated usage of rules. 387 388 update-repos_ 389 Adds and updates repository rules in the WORKSPACE file. 390 391 Bazel rule 392 ~~~~~~~~~~ 393 394 Gazelle may be run via a rule. See `Running Gazelle with Bazel`_ for setup 395 instructions. This rule builds Gazelle and generates a wrapper script that 396 executes Gazelle with baked-in set of arguments. You can run this script 397 with ``bazel run``, or you can copy it into your workspace and run it directly. 398 399 The following attributes are available on the ``gazelle`` rule. 400 401 +----------------------+---------------------+--------------------------------------+ 402 | **Name** | **Type** | **Default value** | 403 +======================+=====================+======================================+ 404 | :param:`gazelle` | :type:`label` | :value:`@bazel_gazelle//cmd/gazelle` | 405 +----------------------+---------------------+--------------------------------------+ 406 | The `gazelle_binary`_ rule that builds Gazelle. You can substitute a modified | 407 | version of Gazelle with this. See `Extending Gazelle`_. | 408 +----------------------+---------------------+--------------------------------------+ 409 | :param:`external` | :type:`string` | :value:`external` | 410 +----------------------+---------------------+--------------------------------------+ 411 | The method for resolving unknown imports to Bazel dependencies. May be | 412 | :value:`external`, :value:`static` or :value:`vendored`. | 413 | See `Dependency resolution`_. | 414 +----------------------+---------------------+--------------------------------------+ 415 | :param:`build_tags` | :type:`string_list` | :value:`[]` | 416 +----------------------+---------------------+--------------------------------------+ 417 | The list of Go build tags that Gazelle should consider to always be true. | 418 +----------------------+---------------------+--------------------------------------+ 419 | :param:`prefix` | :type:`string` | :value:`""` | 420 +----------------------+---------------------+--------------------------------------+ 421 | The import path that corresponds to the repository root directory. | 422 | | 423 | Note: It's usually better to write a directive like | 424 | ``# gazelle:prefix example.com/repo`` in your build file instead of setting | 425 | this attribute. | 426 +----------------------+---------------------+--------------------------------------+ 427 | :param:`extra_args` | :type:`string_list` | :value:`[]` | 428 +----------------------+---------------------+--------------------------------------+ 429 | A list of extra command line arguments passed to Gazelle. Note that | 430 | ``extra_args`` are suppressed by extra command line args (e.g. | 431 | ``bazel run //:gazelle -- subdir``). | 432 | See https://github.com/bazelbuild/bazel-gazelle/issues/536 for explanation. | 433 +----------------------+---------------------+--------------------------------------+ 434 | :param:`command` | :type:`string` | :value:`update` | 435 +----------------------+---------------------+--------------------------------------+ 436 | The Gazelle command to use. May be :value:`fix`, :value:`update` or | 437 | :value:`update-repos`. | 438 +----------------------+---------------------+--------------------------------------+ 439 440 ``fix`` and ``update`` 441 ~~~~~~~~~~~~~~~~~~~~~~ 442 443 The ``update`` command is the most common way of running Gazelle. Gazelle 444 scans sources in directories throughout the repository, then creates and updates 445 build files. 446 447 The ``fix`` command does everything ``update`` does, but it also fixes 448 deprecated usage of rules, analogous to ``go fix``. For example, ``cgo_library`` 449 will be consolidated with ``go_library``. This command may delete or rename 450 rules, so it's not on by default. See `Fix command transformations`_ 451 for details. 452 453 Both commands accept a list of directories to process as positional arguments. 454 If no directories are specified, Gazelle will process the current directory. 455 Subdirectories will be processed recursively. 456 457 The following flags are accepted: 458 459 +-------------------------------------------------------------------+----------------------------------------+ 460 | **Name** | **Default value** | 461 +===================================================================+========================================+ 462 | :flag:`-build_file_name file1,file2,...` | :value:`BUILD.bazel,BUILD` | 463 +-------------------------------------------------------------------+----------------------------------------+ 464 | Comma-separated list of file names. Gazelle recognizes these files as Bazel | 465 | build files. New files will use the first name in this list. Use this if | 466 | your project contains non-Bazel files named ``BUILD`` (or ``build`` on | 467 | case-insensitive file systems). | 468 +-------------------------------------------------------------------+----------------------------------------+ 469 | :flag:`-build_tags tag1,tag2` | | 470 +-------------------------------------------------------------------+----------------------------------------+ 471 | List of Go build tags Gazelle will consider to be true. Gazelle applies | 472 | constraints when generating Go rules. It assumes certain tags are true on | 473 | certain platforms (for example, ``amd64,linux``). It assumes all Go release | 474 | tags are true (for example, ``go1.8``). It considers other tags to be false | 475 | (for example, ``ignore``). This flag overrides that behavior. | 476 | | 477 | Bazel may still filter sources with these tags. Use | 478 | ``bazel build --define gotags=foo,bar`` to set tags at build time. | 479 +-------------------------------------------------------------------+----------------------------------------+ 480 | :flag:`-exclude pattern` | | 481 +-------------------------------------------------------------------+----------------------------------------+ 482 | Prevents Gazelle from processing a file or directory if the given | 483 | `doublestar.Match`_ pattern matches. If the pattern refers to a source file, | 484 | Gazelle won't include it in any rules. If the pattern refers to a directory, | 485 | Gazelle won't recurse into it. | 486 | | 487 | This option may be repeated. Patterns must be slash-separated, relative to the | 488 | repository root. This is equivalent to the ``# gazelle:exclude pattern`` | 489 | directive. | 490 +-------------------------------------------------------------------+----------------------------------------+ 491 | :flag:`-external external|static|vendored` | :value:`external` | 492 +-------------------------------------------------------------------+----------------------------------------+ 493 | Determines how Gazelle resolves import paths that cannot be resolve in the | 494 | current repository. May be :value:`external`, :value:`static` or :value:`vendored`. See | 495 | `Dependency resolution`_. | 496 +-------------------------------------------------------------------+----------------------------------------+ 497 | :flag:`-index true|false` | :value:`true` | 498 +-------------------------------------------------------------------+----------------------------------------+ 499 | Determines whether Gazelle should index the libraries in the current repository and whether it | 500 | should use the index to resolve dependencies. If this is switched off, Gazelle would rely on | 501 | ``# gazelle:prefix`` directive or ``-go_prefix`` flag to resolve dependencies. | 502 +-------------------------------------------------------------------+----------------------------------------+ 503 | :flag:`-go_grpc_compiler` | ``@io_bazel_rules_go//proto:go_grpc`` | 504 +-------------------------------------------------------------------+----------------------------------------+ 505 | The protocol buffers compiler to use for building go bindings for gRPC. May be repeated. | 506 | | 507 | See `Predefined plugins`_ for available options; commonly used options include | 508 | ``@io_bazel_rules_go//proto:gofast_grpc`` and ``@io_bazel_rules_go//proto:gogofaster_grpc``. | 509 +-------------------------------------------------------------------+----------------------------------------+ 510 | :flag:`-go_naming_convention` | | 511 +-------------------------------------------------------------------+----------------------------------------+ 512 | Controls the names of generated Go targets. Equivalent to the | 513 | ``# gazelle:go_naming_convention`` directive. See details in | 514 | `Directives`_ below. | 515 +-------------------------------------------------------------------+----------------------------------------+ 516 | :flag:`-go_naming_convention_external` | | 517 +-------------------------------------------------------------------+----------------------------------------+ 518 | Controls the default naming convention used when resolving libraries in | 519 | external repositories with unknown naming conventions. Equivalent to the | 520 | ``# gazelle:go_naming_convention_external`` directive. | 521 +-------------------------------------------------------------------+----------------------------------------+ 522 | :flag:`-go_prefix example.com/repo` | | 523 +-------------------------------------------------------------------+----------------------------------------+ 524 | A prefix of import paths for libraries in the repository that corresponds to | 525 | the repository root. Equivalent to setting the ``# gazelle:prefix`` directive | 526 | in the root BUILD.bazel file or the ``prefix`` attribute of the ``gazelle`` rule. If | 527 | neither of those are set, this option is mandatory. | 528 | | 529 | This prefix is used to determine whether an import path refers to a library | 530 | in the current repository or an external dependency. | 531 +-------------------------------------------------------------------+----------------------------------------+ 532 | :flag:`-go_proto_compiler` | ``@io_bazel_rules_go//proto:go_proto`` | 533 +-------------------------------------------------------------------+----------------------------------------+ 534 | The protocol buffers compiler to use for building go bindings. May be repeated. | 535 | | 536 | See `Predefined plugins`_ for available options; commonly used options include | 537 | ``@io_bazel_rules_go//proto:gofast_proto`` and ``@io_bazel_rules_go//proto:gogofaster_proto``. | 538 +-------------------------------------------------------------------+----------------------------------------+ 539 | :flag:`-known_import example.com` | | 540 +-------------------------------------------------------------------+----------------------------------------+ 541 | Skips import path resolution for a known domain. May be repeated. | 542 | | 543 | When Gazelle resolves an import path to an external dependency, it attempts | 544 | to discover the remote repository root over HTTP. Gazelle skips this | 545 | discovery step for a few well-known domains with predictable structure, like | 546 | golang.org and github.com. This flag specifies additional domains to skip, | 547 | which is useful in situations where the lookup would fail for some reason. | 548 +-------------------------------------------------------------------+----------------------------------------+ 549 | :flag:`-mode fix|print|diff` | :value:`fix` | 550 +-------------------------------------------------------------------+----------------------------------------+ 551 | Method for emitting merged build files. | 552 | | 553 | In ``fix`` mode, Gazelle writes generated and merged files to disk. In | 554 | ``print`` mode, it prints them to stdout. In ``diff`` mode, it prints a | 555 | unified diff. | 556 +-------------------------------------------------------------------+----------------------------------------+ 557 | :flag:`-proto default|file|package|legacy|disable|disable_global` | :value:`default` | 558 +-------------------------------------------------------------------+----------------------------------------+ 559 | Determines how Gazelle should generate rules for .proto files. See details | 560 | in `Directives`_ below. | 561 +-------------------------------------------------------------------+----------------------------------------+ 562 | :flag:`-proto_group group` | :value:`""` | 563 +-------------------------------------------------------------------+----------------------------------------+ 564 | Determines the proto option Gazelle uses to group .proto files into rules | 565 | when in ``package`` mode. See details in `Directives`_ below. | 566 +-------------------------------------------------------------------+----------------------------------------+ 567 | :flag:`-proto_import_prefix path` | | 568 +-------------------------------------------------------------------+----------------------------------------+ 569 | Sets the `import_prefix`_ attribute of generated ``proto_library`` rules. | 570 | This adds a prefix to the string used to import ``.proto`` files listed in | 571 | the ``srcs`` attribute of generated rules. Equivalent to the | 572 | ``# gazelle:proto_import_prefix`` directive. See details in `Directives`_ below. | 573 +-------------------------------------------------------------------+----------------------------------------+ 574 | :flag:`-repo_root dir` | | 575 +-------------------------------------------------------------------+----------------------------------------+ 576 | The root directory of the repository. Gazelle normally infers this to be the | 577 | directory containing the WORKSPACE file. | 578 | | 579 | Gazelle will not process packages outside this directory. | 580 +-------------------------------------------------------------------+----------------------------------------+ 581 | :flag:`-lang lang1,lang2,...` | :value:`""` | 582 +-------------------------------------------------------------------+----------------------------------------+ 583 | Selects languages for which to compose and index rules. | 584 | | 585 | By default, all languages that this Gazelle was built with are processed. | 586 +-------------------------------------------------------------------+----------------------------------------+ 587 | :flag:`-cpuprofile filename` | :value:`""` | 588 +-------------------------------------------------------------------+----------------------------------------+ 589 | If specified, gazelle uses [runtime/pprof](https://pkg.go.dev/runtime/pprof#StartCPUProfile) to collect | 590 | CPU profiling information from the command and save it to the given file. | 591 | | 592 | By default, this is disabled | 593 +-------------------------------------------------------------------+----------------------------------------+ 594 | :flag:`-memprofile filename` | :value:`""` | 595 +-------------------------------------------------------------------+----------------------------------------+ 596 | If specified, gazelle uses [runtime/pprof](https://pkg.go.dev/runtime/pprof#WriteHeapProfile) to collect | 597 | memory a profile information from the command and save it to a file. | 598 | | 599 | By default, this is disabled | 600 +-------------------------------------------------------------------+----------------------------------------+ 601 602 .. _Predefined plugins: https://github.com/bazelbuild/rules_go/blob/master/proto/core.rst#predefined-plugins 603 604 ``update-repos`` 605 ~~~~~~~~~~~~~~~~ 606 607 The ``update-repos`` command updates repository rules. It can write the rules 608 to either the WORKSPACE (by default) or a .bzl file macro function. It can be 609 used to add new repository rules or update existing rules to the specified 610 version. It can also import repository rules from a ``go.mod`` or a ``go.work`` 611 file. 612 613 WARNING: This command is mainly used for managing external Go dependencies in Bazel's WORKSPACE mode. 614 For managing external Go dependencies in Bazel's BzlMod mode, please check: https://github.com/bazelbuild/rules_go/blob/master/docs/go/core/bzlmod.md#external-dependencies 615 616 .. code:: bash 617 618 # Add or update a repository to latest version by import path 619 $ gazelle update-repos example.com/new/repo 620 621 # Add or update a repository to specified version/commit by import path 622 $ gazelle update-repos example.com/new/repo@v1.3.1 623 624 # Import repositories from go.mod 625 $ gazelle update-repos -from_file=go.mod 626 627 # Import repositories from go.work 628 $ gazelle update-repos -from_file=go.work 629 630 # Import repositories from go.mod and update macro 631 $ gazelle update-repos -from_file=go.mod -to_macro=repositories.bzl%go_repositories 632 633 # Import repositories from go.work and update macro 634 $ gazelle update-repos -from_file=go.work -to_macro=repositories.bzl%go_repositories 635 636 The following flags are accepted: 637 638 +----------------------------------------------------------------------------------------------------------+----------------------------------------------+ 639 | **Name** | **Default value** | 640 +==========================================================================================================+==============================================+ 641 | :flag:`-from_file lock-file` | | 642 +----------------------------------------------------------------------------------------------------------+----------------------------------------------+ 643 | Import repositories from a file as `go_repository`_ rules. These rules will be added to the bottom of the WORKSPACE file or merged with existing rules. | 644 | | 645 | The lock file format is inferred from the file name. ``go.mod`` and ``go.work`` are all supported. | 646 +----------------------------------------------------------------------------------------------------------+----------------------------------------------+ 647 | :flag:`-repo_root dir` | | 648 +----------------------------------------------------------------------------------------------------------+----------------------------------------------+ 649 | The root directory of the repository. Gazelle normally infers this to be the directory containing the WORKSPACE file. | 650 | | 651 | Gazelle will not process packages outside this directory. | 652 +----------------------------------------------------------------------------------------------------------+----------------------------------------------+ 653 | :flag:`-to_macro macroFile%defName` | | 654 +----------------------------------------------------------------------------------------------------------+----------------------------------------------+ 655 | Tells Gazelle to write new repository rules into a .bzl macro function rather than the WORKSPACE file. | 656 | | 657 | The ``repository_macro`` directive should be added to the WORKSPACE in order for future Gazelle calls to recognize the repos defined in the macro file. | 658 +----------------------------------------------------------------------------------------------------------+----------------------------------------------+ 659 | :flag:`-prune true|false` | :value:`false` | 660 +----------------------------------------------------------------------------------------------------------+----------------------------------------------+ 661 | When true, Gazelle will remove `go_repository`_ rules that no longer have equivalent repos in the ``go.mod`` file. | 662 | | 663 | This flag can only be used with ``-from_file``. | 664 +----------------------------------------------------------------------------------------------------------+----------------------------------------------+ 665 | :flag:`-build_directives arg1,arg2,...` | | 666 +----------------------------------------------------------------------------------------------------------+----------------------------------------------+ 667 | Sets the ``build_directives attribute`` for the generated `go_repository`_ rule(s). | 668 +----------------------------------------------------------------------------------------------------------+----------------------------------------------+ 669 | :flag:`-build_external external|vendored` | | 670 +----------------------------------------------------------------------------------------------------------+----------------------------------------------+ 671 | Sets the ``build_external`` attribute for the generated `go_repository`_ rule(s). | 672 +----------------------------------------------------------------------------------------------------------+----------------------------------------------+ 673 | :flag:`-build_extra_args arg1,arg2,...` | | 674 +----------------------------------------------------------------------------------------------------------+----------------------------------------------+ 675 | Sets the ``build_extra_args attribute`` for the generated `go_repository`_ rule(s). | 676 +----------------------------------------------------------------------------------------------------------+----------------------------------------------+ 677 | :flag:`-build_file_generation auto|on|off` | | 678 +----------------------------------------------------------------------------------------------------------+----------------------------------------------+ 679 | Sets the ``build_file_generation`` attribute for the generated `go_repository`_ rule(s). | 680 +----------------------------------------------------------------------------------------------------------+----------------------------------------------+ 681 | :flag:`-build_file_names file1,file2,...` | | 682 +----------------------------------------------------------------------------------------------------------+----------------------------------------------+ 683 | Sets the ``build_file_name`` attribute for the generated `go_repository`_ rule(s). | 684 +----------------------------------------------------------------------------------------------------------+----------------------------------------------+ 685 | :flag:`-build_file_proto_mode default|package|legacy|disable|disable_global` | | 686 +----------------------------------------------------------------------------------------------------------+----------------------------------------------+ 687 | Sets the ``build_file_proto_mode`` attribute for the generated `go_repository`_ rule(s). | 688 +----------------------------------------------------------------------------------------------------------+----------------------------------------------+ 689 | :flag:`-build_tags tag1,tag2,...` | | 690 +----------------------------------------------------------------------------------------------------------+----------------------------------------------+ 691 | Sets the ``build_tags`` attribute for the generated `go_repository`_ rule(s). | 692 +----------------------------------------------------------------------------------------------------------+----------------------------------------------+ 693 694 Directives 695 ~~~~~~~~~~ 696 697 Gazelle can be configured with *directives*, which are written as top-level 698 comments in build files. Most options that can be set on the command line 699 can also be set using directives. Some options can only be set with 700 directives. 701 702 Directive comments have the form ``# gazelle:key value``. For example: 703 704 .. code:: bzl 705 706 load("@io_bazel_rules_go//go:def.bzl", "go_library") 707 708 # gazelle:prefix github.com/example/project 709 # gazelle:build_file_name BUILD,BUILD.bazel 710 711 go_library( 712 name = "go_default_library", 713 srcs = ["example.go"], 714 importpath = "github.com/example/project", 715 visibility = ["//visibility:public"], 716 ) 717 718 Directives apply in the directory where they are set *and* in subdirectories. 719 This means, for example, if you set ``# gazelle:prefix`` in the build file 720 in your project's root directory, it affects your whole project. If you 721 set it in a subdirectory, it only affects rules in that subtree. 722 723 The following directives are recognized: 724 725 +---------------------------------------------------+----------------------------------------+ 726 | **Directive** | **Default value** | 727 +===================================================+========================================+ 728 | :direc:`# gazelle:build_file_name names` | :value:`BUILD.bazel,BUILD` | 729 +---------------------------------------------------+----------------------------------------+ 730 | Comma-separated list of file names. Gazelle recognizes these files as Bazel | 731 | build files. New files will use the first name in this list. Use this if | 732 | your project contains non-Bazel files named ``BUILD`` (or ``build`` on | 733 | case-insensitive file systems). | 734 +---------------------------------------------------+----------------------------------------+ 735 | :direc:`# gazelle:build_tags foo,bar` | none | 736 +---------------------------------------------------+----------------------------------------+ 737 | List of Go build tags Gazelle will consider to be true. Gazelle applies | 738 | constraints when generating Go rules. It assumes certain tags are true on | 739 | certain platforms (for example, ``amd64,linux``). It assumes all Go release | 740 | tags are true (for example, ``go1.8``). It considers other tags to be false | 741 | (for example, ``ignore``). This flag overrides that behavior. | 742 | | 743 | Bazel may still filter sources with these tags. Use | 744 | ``bazel build --define gotags=foo,bar`` to set tags at build time. | 745 +---------------------------------------------------+----------------------------------------+ 746 | :direc:`# gazelle:exclude pattern` | n/a | 747 +---------------------------------------------------+----------------------------------------+ 748 | Prevents Gazelle from processing a file or directory if the given | 749 | `doublestar.Match`_ pattern matches. If the pattern refers to a source file, | 750 | Gazelle won't include it in any rules. If the pattern refers to a directory, | 751 | Gazelle won't recurse into it. This directive may be repeated to exclude | 752 | multiple patterns, one per line. | 753 +---------------------------------------------------+----------------------------------------+ 754 | :direc:`# gazelle:follow pattern` | n/a | 755 +---------------------------------------------------+----------------------------------------+ 756 | Instructs Gazelle to follow a symbolic link to a directory within the repository if the | 757 | given `doublestar.Match`_ pattern matches. Normally, Gazelle does not follow symbolic | 758 | links unless they point outside of the repository root. | 759 | | 760 | Care must be taken to avoid visiting a directory more than once. | 761 | The ``# gazelle:exclude`` directive may be used to prevent Gazelle from | 762 | recursing into a directory. | 763 +---------------------------------------------------+----------------------------------------+ 764 | :direc:`# gazelle:go_generate_proto` | ``true`` | 765 +---------------------------------------------------+----------------------------------------+ 766 | Instructs Gazelle's Go extension whether to generate ``go_proto_library`` rules for | 767 | ``proto_library`` rules generated by the Proto extension. When this directive is ``true`` | 768 | Gazelle will generate ``go_proto_library`` and ``go_library`` according to | 769 | ``# gazelle:proto``. When this directive is ``false``, the Go extension will ignore any | 770 | ``proto_library`` rules. If there are any pre-generated Go files, they will be treated as | 771 | regular Go files. | 772 +---------------------------------------------------+----------------------------------------+ 773 | :direc:`# gazelle:go_test mode` | ``default`` | 774 +---------------------------------------------------+----------------------------------------+ 775 | Tells Gazelle how to generate rules for _test.go files. Valid values are: | 776 | | 777 | * ``default``: One ``go_test`` rule will be generated whose ``srcs`` includes | 778 | all ``_test.go`` files in the directory. | 779 | * ``file``: A distinct ``go_test`` rule will be generated for each ``_test.go`` file in the| 780 | package directory. | 781 +---------------------------------------------------+----------------------------------------+ 782 | :direc:`# gazelle:go_grpc_compilers` | ``@io_bazel_rules_go//proto:go_grpc`` | 783 +---------------------------------------------------+----------------------------------------+ 784 | The protocol buffers compiler(s) to use for building go bindings for gRPC. | 785 | Multiple compilers, separated by commas, may be specified. | 786 | Omit the directive value to reset ``go_grpc_compilers`` back to the default. | 787 | | 788 | See `Predefined plugins`_ for available options; commonly used options include | 789 | ``@io_bazel_rules_go//proto:gofast_grpc`` and | 790 | ``@io_bazel_rules_go//proto:gogofaster_grpc``. | 791 +---------------------------------------------------+----------------------------------------+ 792 | :direc:`# gazelle:go_naming_convention` | inferred automatically | 793 +---------------------------------------------------+----------------------------------------+ 794 | Controls the names of generated Go targets. | 795 | | 796 | Valid values are: | 797 | | 798 | * ``go_default_library``: Library targets are named ``go_default_library``, test targets | 799 | are named ``go_default_test``. | 800 | * ``import``: Library and test targets are named after the last segment of their import | 801 | path. | 802 | For example, ``example.repo/foo`` is named ``foo``, and the test target is ``foo_test``. | 803 | Major version suffixes like ``/v2`` are dropped. | 804 | For a main package with a binary ``foobin``, the names are instead ``foobin_lib`` and | 805 | ``foobin_test``. | 806 | * ``import_alias``: Same as ``import``, but an ``alias`` target is generated named | 807 | ``go_default_library`` to ensure backwards compatibility. | 808 | | 809 | If no naming convention is set, Gazelle attempts to infer the convention in | 810 | use by reading the root build file and build files in immediate | 811 | subdirectories. If no Go targets are found, Gazelle defaults to ``import``. | 812 +---------------------------------------------------+----------------------------------------+ 813 | :direc:`# gazelle:go_naming_convention_external` | n/a | 814 +---------------------------------------------------+----------------------------------------+ 815 | Controls the default naming convention used when resolving libraries in | 816 | external repositories with unknown naming conventions. Accepts the same values | 817 | as ``go_naming_convention``. | 818 +---------------------------------------------------+----------------------------------------+ 819 | :direc:`# gazelle:go_proto_compilers` | ``@io_bazel_rules_go//proto:go_proto`` | 820 +---------------------------------------------------+----------------------------------------+ 821 | The protocol buffers compiler(s) to use for building go bindings. | 822 | Multiple compilers, separated by commas, may be specified. | 823 | Omit the directive value to reset ``go_proto_compilers`` back to the default. | 824 | | 825 | See `Predefined plugins`_ for available options; commonly used options include | 826 | ``@io_bazel_rules_go//proto:gofast_proto`` and | 827 | ``@io_bazel_rules_go//proto:gogofaster_proto``. | 828 +---------------------------------------------------+----------------------------------------+ 829 | :direc:`# gazelle:ignore` | n/a | 830 +---------------------------------------------------+----------------------------------------+ 831 | Prevents Gazelle from modifying the build file. Gazelle will still read | 832 | rules in the build file and may modify build files in subdirectories. | 833 +---------------------------------------------------+----------------------------------------+ 834 | :direc:`# gazelle:importmap_prefix path` | See below | 835 +---------------------------------------------------+----------------------------------------+ 836 | A prefix for ``importmap`` attributes in library rules. Gazelle will set | 837 | an ``importmap`` on a ``go_library`` or ``go_proto_library`` by | 838 | concatenating this with the relative path from the directory where the | 839 | prefix is set to the library. For example, if ``importmap_prefix`` is set | 840 | to ``"x/example.com/repo"`` in the build file ``//foo/bar:BUILD.bazel``, | 841 | then a library in ``foo/bar/baz`` will have the ``importmap`` of | 842 | ``"x/example.com/repo/baz"``. | 843 | | 844 | ``importmap`` is not set when it matches ``importpath``. | 845 | | 846 | As a special case, when Gazelle enters a directory named ``vendor``, it | 847 | sets ``importmap_prefix`` to a string based on the repository name and the | 848 | location of the vendor directory. If you wish to override this, you'll need | 849 | to set ``importmap_prefix`` explicitly in the vendor directory. | 850 +------------------------------------------------------------+-------------------------------+ 851 | :direc:`# gazelle:map_kind from_kind to_kind to_kind_load` | n/a | 852 +------------------------------------------------------------+-------------------------------+ 853 | Customizes the kind of rules generated by Gazelle. | 854 | | 855 | As a separate step after generating rules, any new rules of kind ``from_kind`` have their | 856 | kind replaced with ``to_kind``. This means that ``to_kind`` must accept the same | 857 | parameters and behave similarly. | 858 | | 859 | Most commonly, this would be used to replace the rules provided by ``rules_go`` with | 860 | custom macros. For example, | 861 | ``gazelle:map_kind go_binary go_deployable //tools/go:def.bzl`` would configure Gazelle to | 862 | produce rules of kind ``go_deployable`` as loaded from ``//tools/go:def.bzl`` instead of | 863 | ``go_binary``, for this directory or within. | 864 | | 865 | Existing rules of the old kind will be ignored. To switch your codebase from a builtin | 866 | kind to a mapped kind, use `buildozer`_. | 867 +---------------------------------------------------+----------------------------------------+ 868 | :direc:`# gazelle:prefix path` | n/a | 869 +---------------------------------------------------+----------------------------------------+ 870 | A prefix for ``importpath`` attributes on library rules. Gazelle will set | 871 | an ``importpath`` on a ``go_library`` or ``go_proto_library`` by | 872 | concatenating this with the relative path from the directory where the | 873 | prefix is set to the library. Most commonly, ``prefix`` is set to the | 874 | name of a repository in the root directory of a repository. For example, | 875 | in this repository, ``prefix`` is set in ``//:BUILD.bazel`` to | 876 | ``github.com/bazelbuild/bazel-gazelle``. The ``go_library`` in | 877 | ``//cmd/gazelle`` is assigned the ``importpath`` | 878 | ``"github.com/bazelbuild/bazel-gazelle/cmd/gazelle"``. | 879 | | 880 | As a special case, when Gazelle enters a directory named ``vendor``, it sets | 881 | ``prefix`` to the empty string. This automatically gives vendored libraries | 882 | an intuitive ``importpath``. | 883 +---------------------------------------------------+----------------------------------------+ 884 | :direc:`# gazelle:proto mode` | :value:`default` | 885 +---------------------------------------------------+----------------------------------------+ 886 | Tells Gazelle how to generate rules for .proto files. Valid values are: | 887 | | 888 | * ``default``: ``proto_library``, ``go_proto_library``, and ``go_library`` | 889 | rules are generated using ``@io_bazel_rules_go//proto:def.bzl``. Only one | 890 | of each rule may be generated per directory. This is the default mode. | 891 | * ``file``: a ``proto_library`` rule is generated for every .proto file. | 892 | * ``package``: multiple ``proto_library`` and ``go_proto_library`` rules | 893 | may be generated in the same directory. .proto files are grouped into | 894 | rules based on their package name or another option (see ``proto_group``). | 895 | * ``legacy``: ``filegroup`` rules are generated for use by | 896 | ``@io_bazel_rules_go//proto:go_proto_library.bzl``. ``go_proto_library`` | 897 | rules must be written by hand. Gazelle will run in this mode automatically | 898 | if ``go_proto_library.bzl`` is loaded to avoid disrupting existing | 899 | projects, but this can be overridden with a directive. | 900 | * ``disable``: .proto files are ignored. Gazelle will run in this mode | 901 | automatically if ``go_proto_library`` is loaded from any other source, | 902 | but this can be overridden with a directive. | 903 | * ``disable_global``: like ``disable`` mode, but also prevents Gazelle from | 904 | using any special cases in dependency resolution for Well Known Types and | 905 | Google APIs. Useful for avoiding build-time dependencies on protoc. | 906 | | 907 | This directive applies to the current directory and subdirectories. As a | 908 | special case, when Gazelle enters a directory named ``vendor``, if the proto | 909 | mode isn't set explicitly in a parent directory or on the command line, | 910 | Gazelle will run in ``disable`` mode. Additionally, if the file | 911 | ``@io_bazel_rules_go//proto:go_proto_library.bzl`` is loaded, Gazelle | 912 | will run in ``legacy`` mode. | 913 +---------------------------------------------------+----------------------------------------+ 914 | :direc:`# gazelle:proto_group option` | :value:`""` | 915 +---------------------------------------------------+----------------------------------------+ 916 | *This directive is only effective in* ``package`` *mode (see above).* | 917 | | 918 | Specifies an option that Gazelle can use to group .proto files into rules. | 919 | For example, when set to ``go_package``, .proto files with the same | 920 | ``option go_package`` will be grouped together. | 921 | | 922 | When this directive is set to the empty string, Gazelle will group packages | 923 | by their proto package statement. | 924 | | 925 | Rule names are generated based on the last run of identifier characters | 926 | in the package name. For example, if the package is ``"foo/bar/baz"``, the | 927 | ``proto_library`` rule will be named ``baz_proto``. | 928 +---------------------------------------------------+----------------------------------------+ 929 | :direc:`# gazelle:proto_import_prefix path` | n/a | 930 +---------------------------------------------------+----------------------------------------+ 931 | Sets the `import_prefix`_ attribute of generated ``proto_library`` rules. | 932 | This adds a prefix to the string used to import ``.proto`` files listed in | 933 | the ``srcs`` attribute of generated rules. | 934 | | 935 | For example, if the target ``//a:b_proto`` has ``srcs = ["b.proto"]`` and | 936 | ``import_prefix = "github.com/x/y"``, then ``b.proto`` should be imported | 937 | with the string ``"github.com/x/y/a/b.proto"``. | 938 +---------------------------------------------------+----------------------------------------+ 939 | :direc:`# gazelle:proto_strip_import_prefix path` | n/a | 940 +---------------------------------------------------+----------------------------------------+ 941 | Sets the `strip_import_prefix`_ attribute of generated ``proto_library`` rules. | 942 | This is a prefix to strip from the strings used to import ``.proto`` files. | 943 | | 944 | If the prefix starts with a slash, it's intepreted relative to the repository | 945 | root. Otherwise, it's relative to the directory containing the build file. | 946 | The package-relative form is only useful when a single build file covers | 947 | ``.proto`` files in subdirectories. Gazelle doesn't generate build files like | 948 | this, so only paths with a leading slash should be used. Gazelle will print | 949 | a warning when the package-relative form is used. | 950 | | 951 | For example, if the target ``//proto/a:b_proto`` has ``srcs = ["b.proto"]`` | 952 | and ``strip_import_prefix = "/proto"``, then ``b.proto`` should be imported | 953 | with the string ``"a/b.proto"``. | 954 +---------------------------------------------------+----------------------------------------+ 955 | :direc:`# gazelle:resolve ...` | n/a | 956 +---------------------------------------------------+----------------------------------------+ 957 | Specifies an explicit mapping from an import string to a label for | 958 | `Dependency resolution`_. The format for a resolve directive is: | 959 | | 960 | ``# gazelle:resolve source-lang import-lang import-string label`` | 961 | | 962 | * ``source-lang`` is the language of the source code being imported. | 963 | * ``import-lang`` is the language importing the library. This is usually | 964 | the same as ``source-lang`` but may differ with generated code. For | 965 | example, when resolving dependencies for a ``go_proto_library``, | 966 | ``source-lang`` would be ``"proto"`` and ``import-lang`` would be ``"go"``. | 967 | ``import-lang`` may be omitted if it is the same as ``source-lang``. | 968 | * ``import-string`` is the string used in source code to import a library. | 969 | * ``label`` is the Bazel label that Gazelle should write in ``deps``. | 970 | | 971 | For example: | 972 | | 973 | .. code:: bzl | 974 | | 975 | # gazelle:resolve go example.com/foo //foo:go_default_library | 976 | # gazelle:resolve proto go foo/foo.proto //foo:foo_go_proto | 977 | | 978 +---------------------------------------------------+----------------------------------------+ 979 | :direc:`# gazelle:resolve_regexp ...` | n/a | 980 +---------------------------------------------------+----------------------------------------+ 981 | Specifies an explicit mapping from an import regex to a label for | 982 | `Dependency resolution`_. The format for a resolve directive is: | 983 | | 984 | ``# gazelle:resolve_regexp source-lang import-lang import-string-regex label`` | 985 | | 986 | * ``source-lang`` is the language of the source code being imported. | 987 | * ``import-lang`` is the language importing the library. This is usually | 988 | the same as ``source-lang`` but may differ with generated code. For | 989 | example, when resolving dependencies for a ``go_proto_library``, | 990 | ``source-lang`` would be ``"proto"`` and ``import-lang`` would be ``"go"``. | 991 | ``import-lang`` may be omitted if it is the same as ``source-lang``. | 992 | * ``import-string-regex`` is the regex applied to the import in the source code. | 993 | If it matches, that import will be resolved to the label specified below. | 994 | * ``label`` is the Bazel label that Gazelle should write in ``deps``. | 995 | | 996 | For example: | 997 | | 998 | .. code:: bzl | 999 | | 1000 | # gazelle:resolve_regexp go example.com/.* //foo:go_default_library | 1001 | # gazelle:resolve_regexp proto go foo/.*\.proto //foo:foo_go_proto | 1002 | | 1003 +---------------------------------------------------+----------------------------------------+ 1004 | :direc:`# gazelle:go_visibility label` | n/a | 1005 +---------------------------------------------------+----------------------------------------+ 1006 | By default, internal packages are only visible to its siblings. This directive adds a label| 1007 | internal packages should be visible to additionally. This directive can be used several | 1008 | times, adding a list of labels. | 1009 +---------------------------------------------------+----------------------------------------+ 1010 | :direc:`# gazelle:lang lang1,lang2,...` | n/a | 1011 +---------------------------------------------------+----------------------------------------+ 1012 | Sets the language selection flag for this and descendent packages, which causes gazelle to | 1013 | index and generate rules for only the languages named in this directive. | 1014 +---------------------------------------------------+----------------------------------------+ 1015 | :direc:`# gazelle:default_visibility visibility` | n/a | 1016 +---------------------------------------------------+----------------------------------------+ 1017 | Comma-separated list of visibility specifications. | 1018 | This directive adds the visibility specifications for this and descendant packages. | 1019 | | 1020 | For example: | 1021 | | 1022 | .. code:: bzl | 1023 | | 1024 | # gazelle:default_visibility //foo:__subpackages__,//src:__subpackages__ | 1025 +---------------------------------------------------+----------------------------------------+ 1026 1027 Gazelle also reads directives from the WORKSPACE file. They may be used to 1028 discover custom repository names and known prefixes. The ``fix`` and ``update`` 1029 commands use these directives for dependency resolution. ``update-repos`` uses 1030 them to learn about repository rules defined in alternate locations. 1031 1032 +--------------------------------------------------------------------+----------------------------------------+ 1033 | **WORKSPACE Directive** | **Default value** | 1034 +====================================================================+========================================+ 1035 | :direc:`# gazelle:repository_macro [+]macroFile%defName` | n/a | 1036 +--------------------------------------------------------------------+----------------------------------------+ 1037 | Tells Gazelle to look for repository rules in a macro in a .bzl file. The directive can be | 1038 | repeated multiple times. | 1039 | The macro can be generated by calling ``update-repos`` with the ``to_macro`` flag. | 1040 | | 1041 | The directive can be prepended with a "+", which will tell Gazelle to also look for repositories | 1042 | within any macros called by the specified macro. | 1043 +--------------------------------------------------------------------+----------------------------------------+ 1044 | :direc:`# gazelle:repository rule_kind attr1_name=attr1_value ...` | n/a | 1045 +--------------------------------------------------------------------+----------------------------------------+ 1046 | Specifies a repository rule that Gazelle should know about. The directive can be repeated multiple times, | 1047 | and can be declared from within a macro definition that Gazelle knows about. At the very least the | 1048 | directive must define a rule kind and a name attribute, but it can define extra attributes after that. | 1049 | | 1050 | This is useful for teaching Gazelle about repos declared in external macros. The directive can also be used | 1051 | to override an actual repository rule. For example, a ``git_repository`` rule for ``org_golang_x_tools`` | 1052 | could be overriden with the directive: | 1053 | | 1054 | .. code:: bzl | 1055 | | 1056 | # gazelle:repository go_repository name=org_golang_x_tools importpath=golang.org/x/tools | 1057 | | 1058 | Gazelle would then proceed as if ``org_golang_x_tools`` was declared as a ``go_repository`` rule. | 1059 +--------------------------------------------------------------------+----------------------------------------+ 1060 1061 Keep comments 1062 ~~~~~~~~~~~~~ 1063 1064 In addition to directives, Gazelle supports ``# keep`` comments that protect 1065 parts of build files from being modified. ``# keep`` may be written before 1066 a rule, before an attribute, or after a string within a list. 1067 1068 ``# keep`` comments might take one of 2 forms; the ``# keep`` literal or a 1069 description prefixed by ``# keep:``. 1070 1071 Example 1072 ^^^^^^^ 1073 1074 Suppose you have a library that includes a generated .go file. Gazelle won't 1075 know what imports to resolve, so you may need to add dependencies manually with 1076 ``# keep`` comments. 1077 1078 .. code:: bzl 1079 1080 load("@io_bazel_rules_go//go:def.bzl", "go_library") 1081 load("@com_github_example_gen//:gen.bzl", "gen_go_file") 1082 1083 gen_go_file( 1084 name = "magic", 1085 srcs = ["magic.go.in"], 1086 outs = ["magic.go"], 1087 ) 1088 1089 go_library( 1090 name = "go_default_library", 1091 srcs = ["magic.go"], 1092 visibility = ["//visibility:public"], 1093 deps = [ 1094 "@com_github_example_gen//:go_default_library", # keep 1095 "@com_github_example_gen//a/b/c:go_default_library", # keep: this is also important 1096 ], 1097 ) 1098 1099 Dependency resolution 1100 --------------------- 1101 1102 One of Gazelle's most important jobs is resolving library import strings 1103 (like ``import "golang.org/x/sys/unix"``) to Bazel labels (like 1104 ``@org_golang_x_sys//unix:go_default_library``). Gazelle follows the rules 1105 below to resolve dependencies: 1106 1107 1. If the import to be resolved is part of a standard library, no explicit 1108 dependency is written. For example, in Go, you don't need to declare 1109 that you depend on ``"fmt"``. 1110 2. If a ``# gazelle:resolve`` directive matches the import to be resolved, 1111 the label at the end of the directive will be used. 1112 3. If proto rule generation is enabled, special rules will be used when 1113 importing certain libraries. These rules may be disabled by adding 1114 ``# gazelle:proto disable_global`` to a build file (this will affect 1115 subdirectories, too) or by passing ``-proto disable_global`` on the 1116 command line. 1117 1118 a) Imports of Well Known Types are mapped to rules in 1119 ``@io_bazel_rules_go//proto/wkt``. 1120 b) Imports of Google APIs are mapped to ``@go_googleapis``. 1121 c) Imports of ``github.com/golang/protobuf/ptypes``, ``descriptor``, and 1122 ``jsonpb`` are mapped to special rules in ``@com_github_golang_protobuf``. 1123 See `Avoiding conflicts with proto rules`_. 1124 1125 4. If the import to be resolved is in the library index, the import will be resolved 1126 to that library. If ``-index=true``, Gazelle builds an index of library rules in 1127 the current repository before starting dependency resolution, and this is how 1128 most dependencies are resolved. 1129 1130 a) For Go, the match is based on the ``importpath`` attribute. 1131 b) For proto, the match is based on the ``srcs`` attribute. 1132 1133 5. If ``-index=false`` and a package is imported that has the current ``go_prefix`` 1134 as a prefix, Gazelle generates a label following a convention. For example, if 1135 the build file in ``//src`` set the prefix with 1136 ``# gazelle:prefix example.com/repo/foo``, and you import the library 1137 ``"example.com/repo/foo/bar``, the dependency will be 1138 ``"//src/foo/bar:go_default_library"``. 1139 6. Otherwise, Gazelle will use the current ``external`` mode to resolve 1140 the dependency. 1141 1142 a) In ``external`` mode (the default), Gazelle will transform the import 1143 string into an external repository label. For example, 1144 ``"golang.org/x/sys/unix"`` would be resolved to 1145 ``"@org_golang_x_sys//unix:go_default_library"``. Gazelle does not confirm 1146 whether the external repository is actually declared in WORKSPACE, 1147 but if there *is* a ``go_repository`` in WORKSPACE with a matching 1148 ``importpath``, Gazelle will use its name. Gazelle does not index 1149 rules in external repositories, so it's possible the resolved dependency 1150 does not exist. 1151 b) In ``static`` mode, Gazelle has the same behavior as ``external`` mode, 1152 except that it will not call out to the network for resolution when no 1153 matching import is found within WORKSPACE. Instead, it will skip the 1154 unknown import. This is the default mode for ``go_repository`` rules. 1155 c) In ``vendored`` mode, Gazelle will transform the import string into 1156 a label in the vendor directory. For example, ``"golang.org/x/sys/unix"`` 1157 would be resolved to 1158 ``"//vendor/golang.org/x/sys/unix:go_default_library"``. This mode is 1159 usually not necessary, since vendored libraries will be indexed and 1160 resolved using rule 4. 1161 1162 Fix command transformations 1163 --------------------------- 1164 1165 Gazelle will generate and update build files when invoked with either 1166 ``gazelle update`` or ``gazelle fix`` (``update`` is the default). Both commands 1167 perform several transformations to fix deprecated usage of the Go rules. 1168 ``update`` performs a safe set of tranformations, while ``fix`` performs some 1169 additional transformations that may delete or rename rules. 1170 1171 The following transformations are performed: 1172 1173 **Migrate library to embed (fix and update):** Gazelle replaces ``library`` 1174 attributes with ``embed`` attributes. 1175 1176 **Migrate gRPC compilers (fix and update):** Gazelle converts 1177 ``go_grpc_library`` rules to ``go_proto_library`` rules with 1178 ``compilers = ["@io_bazel_rules_go//proto:go_grpc"]``. 1179 1180 **Flatten srcs (fix and update):** Gazelle converts ``srcs`` attributes that 1181 use OS and architecture-specific ``select`` expressions to flat lists. 1182 rules_go filters these sources anyway. 1183 1184 **Squash cgo libraries (fix only)**: Gazelle will remove `cgo_library` rules 1185 named ``cgo_default_library`` and merge their attributes with a ``go_library`` 1186 rule in the same package named ``go_default_library``. If no such ``go_library`` 1187 rule exists, a new one will be created. Other ``cgo_library`` rules will not be 1188 removed. 1189 1190 **Squash external tests (fix only)**: Gazelle will squash ``go_test`` rules 1191 named ``go_default_xtest`` into ``go_default_test``. Earlier versions of 1192 rules_go required internal and external tests to be built separately, but 1193 this is no longer needed. 1194 1195 **Remove legacy protos (fix only)**: Gazelle will remove usage of 1196 ``go_proto_library`` rules loaded from 1197 ``@io_bazel_rules_go//proto:go_proto_library.bzl`` and ``filegroup`` rules named 1198 ``go_default_library_protos``. Newly generated proto rules will take their 1199 place. Since ``filegroup`` isn't needed anymore and ``go_proto_library`` has 1200 different attributes and was always written by hand, Gazelle will not attempt to 1201 merge anything from these rules with the newly generated rules. 1202 1203 This transformation is only applied in the default proto mode. Since Gazelle 1204 will run in legacy proto mode if ``go_proto_library.bzl`` is loaded, this 1205 transformation is not usually applied. You can set the proto mode explicitly 1206 using the directive ``# gazelle:proto default``. 1207 1208 **Update loads of gazelle rule (fix and update)**: Gazelle will remove loads 1209 of ``gazelle`` from ``@io_bazel_rules_go//go:def.bzl``. It will automatically 1210 add a load from ``@bazel_gazelle//:def.bzl`` if ``gazelle`` is not loaded 1211 from another location.