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