github.com/afking/bazel-gazelle@v0.0.0-20180301150245-c02bc0f529e8/README.rst (about) 1 Gazelle build file generator 2 ============================ 3 4 .. All external links are here 5 .. _go_repository: https://github.com/bazelbuild/rules_go/blob/master/go/workspace.rst#go-repository 6 .. _Gazelle in rules_go: https://github.com/bazelbuild/rules_go/tree/master/go/tools/gazelle 7 .. _fix: #fix-and-update 8 .. _update: #fix-and-update 9 10 .. role:: cmd(code) 11 .. role:: flag(code) 12 .. role:: param(kbd) 13 .. role:: type(emphasis) 14 .. role:: value(code) 15 .. |mandatory| replace:: **mandatory value** 16 .. End of directives 17 18 Gazelle is a build file generator for Go projects. It can create new 19 BUILD.bazel files for a project that follows "go build" conventions, and it 20 can update existing build files to include new files and options. Gazelle can 21 be invoked directly in a project workspace, or it can be run on an external 22 repository during the build as part of the go_repository_ rule. 23 24 *Gazelle is under active development. Its interface and the rules it generates 25 may change. Gazelle is not an official Google product.* 26 27 .. contents:: **Contents** 28 :depth: 2 29 30 Setup 31 ----- 32 33 Running Gazelle with Bazel 34 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 35 36 To use Gazelle in a new project, add the ``bazel_gazelle`` repository and its 37 dependencies to your WORKSPACE file before ``go_rules_dependencies`` is called. 38 It should look like this: 39 40 .. code:: bzl 41 42 http_archive( 43 name = "io_bazel_rules_go", 44 url = "https://github.com/bazelbuild/rules_go/releases/download/0.10.1/rules_go-0.10.1.tar.gz", 45 sha256 = "4b14d8dd31c6dbaf3ff871adcd03f28c3274e42abc855cb8fb4d01233c0154dc", 46 ) 47 http_archive( 48 name = "bazel_gazelle", 49 url = "https://github.com/bazelbuild/bazel-gazelle/releases/download/0.10.0/bazel-gazelle-0.10.0.tar.gz", 50 sha256 = "6228d9618ab9536892aa69082c063207c91e777e51bd3c5544c9c060cafe1bd8", 51 ) 52 load("@io_bazel_rules_go//go:def.bzl", "go_rules_dependencies", "go_register_toolchains") 53 go_rules_dependencies() 54 go_register_toolchains() 55 load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies") 56 gazelle_dependencies() 57 58 Add the code below to the BUILD or BUILD.bazel file in the root directory 59 of your repository. Replace the string in ``prefix`` with the portion of 60 your import path that corresponds to your repository. 61 62 .. code:: bzl 63 64 load("@bazel_gazelle//:def.bzl", "gazelle") 65 66 gazelle( 67 name = "gazelle", 68 prefix = "github.com/example/project", 69 ) 70 71 After adding this code, you can run Gazelle with Bazel. 72 73 .. code:: 74 75 bazel run //:gazelle 76 77 This will generate new BUILD.bazel files for your project. You can run the same 78 command in the future to update existing BUILD.bazel files to include new source 79 files or options. 80 81 Running Gazelle with Go 82 ~~~~~~~~~~~~~~~~~~~~~~~ 83 84 If you have a Go SDK installed, you can install Gazelle in your ``GOPATH`` with 85 the command below: 86 87 .. code:: 88 89 go get -u github.com/bazelbuild/bazel-gazelle/cmd/gazelle 90 91 Make sure to re-run this command to upgrade Gazelle whenever you upgrade 92 rules_go in your repository. 93 94 To generate BUILD.bazel files in a new project, run the command below, replacing 95 the prefix with the portion of your import path that corresponds to your 96 repository. 97 98 .. code:: 99 100 gazelle -go_prefix github.com/my/project 101 102 The prefix only needs to be specified the first time you run Gazelle. To update 103 existing BUILD.bazel files, you can just run ``gazelle`` without arguments. 104 105 Compatibility 106 ------------- 107 108 Gazelle generates build files that require a minimum version of ``rules_go`` 109 to build. Check the table below to ensure that you're using compatible versions. 110 111 +---------------------+------------------------------+------------------------------+ 112 | **Gazelle version** | **Minimum rules_go version** | **Maximum rules_go version** | 113 +=====================+==============================+==============================+ 114 | 0.8 | 0.8.0 | n/a | 115 +---------------------+------------------------------+------------------------------+ 116 | 0.9 | 0.9.0 | n/a | 117 +---------------------+------------------------------+------------------------------+ 118 | 0.10.0 | 0.9.0 | n/a | 119 +---------------------+------------------------------+------------------------------+ 120 121 Usage 122 ----- 123 124 Command line 125 ~~~~~~~~~~~~ 126 127 .. code:: 128 129 gazelle <command> [flags...] [package-dirs...] 130 131 The first argument to Gazelle may be one of the commands below. If no command 132 is specified, ``update`` is assumed. The remaining arguments are specific 133 to each command and are documented below. 134 135 update_ 136 Scans sources files, then generates and updates build files. 137 138 fix_ 139 Same as the ``update`` command, but it also fixes deprecated usage of rules. 140 141 update-repos_ 142 Updates repository rules in the WORKSPACE file. 143 144 Bazel rule 145 ~~~~~~~~~~ 146 147 Gazelle may be run via a rule. See `Running Gazelle with Bazel`_ for setup 148 instructions. This rule builds Gazelle and generates a wrapper script that 149 executes Gazelle with baked-in set of arguments. You can run this script 150 with ``bazel run``, or you can copy it into your workspace and run it directly. 151 152 The following attributes are available on the ``gazelle`` rule. 153 154 +----------------------+---------------------+--------------------------------------+ 155 | **Name** | **Type** | **Default value** | 156 +======================+=====================+======================================+ 157 | :param:`gazelle` | :type:`label` | :value:`@bazel_gazelle//cmd/gazelle` | 158 +----------------------+---------------------+--------------------------------------+ 159 | The ``go_binary`` rule that builds Gazelle. You can substitute a modified | 160 | version of Gazelle with this. | 161 +----------------------+---------------------+--------------------------------------+ 162 | :param:`external` | :type:`string` | :value:`external` | 163 +----------------------+---------------------+--------------------------------------+ 164 | The method for resolving unknown imports to Bazel dependencies. May be | 165 | :value:`external` or :value:`vendored`. | 166 +----------------------+---------------------+--------------------------------------+ 167 | :param:`build_tags` | :type:`string_list` | :value:`[]` | 168 +----------------------+---------------------+--------------------------------------+ 169 | The last of Go build tags that Gazelle should consider to always be true. | 170 +----------------------+---------------------+--------------------------------------+ 171 | :param:`prefix` | :type:`string` | |mandatory| | 172 +----------------------+---------------------+--------------------------------------+ 173 | The import path that corresponds to the repository root directory. | 174 | TODO(#26): this should be optional. | 175 +----------------------+---------------------+--------------------------------------+ 176 | :param:`extra_args` | :type:`string_list` | :value:`[]` | 177 +----------------------+---------------------+--------------------------------------+ 178 | A list of extra command line arguments passed to Gazelle. | 179 +----------------------+---------------------+--------------------------------------+ 180 | :param:`command` | :type:`string` | :value:`update` | 181 +----------------------+---------------------+--------------------------------------+ 182 | The Gazelle command to use. May be :value:`fix` or :value:`update`. To run | 183 | a different command, e.g., :value:`update-repos`, you'll need to copy the | 184 | invoke the generated wrapper script directly with explicit arguments. | 185 +----------------------+---------------------+--------------------------------------+ 186 187 ``fix`` and ``update`` 188 ~~~~~~~~~~~~~~~~~~~~~~ 189 190 The ``update`` command is the most common way of running Gazelle. Gazelle will 191 scan sources in directories throughout the repository, then create and update 192 build files. 193 194 The ``fix`` command does everything ``update`` does, but it also fixes 195 deprecated usage of rules, analogous to ``go fix``. For example, ``cgo_library`` 196 will be consolidated with ``go_library``. This command may delete or rename 197 rules, so it's not on by default. See `Fix command transformations`_ 198 for details. 199 200 Both commands accept a list of directories to process as positional arguments. 201 If no directories are specified, Gazelle will process the current directory. 202 Subdirectories will be processed recursively. 203 204 The following flags are accepted: 205 206 +------------------------------------------+-----------------------------------+ 207 | **Name** | **Default value** | 208 +==========================================+===================================+ 209 | :flag:`-build_file_name file1,file2,...` | :value:`BUILD.bazel,BUILD` | 210 +------------------------------------------+-----------------------------------+ 211 | Comma-separated list of file names. Gazelle recognizes these files as Bazel | 212 | build files. New files will use the first name in this list. Use this if | 213 | your project contains non-Bazel files named ``BUILD`` (or ``build`` on | 214 | case-insensitive file systems). | 215 +------------------------------------------+-----------------------------------+ 216 | :flag:`-build_tags tag1,tag2` | | 217 +------------------------------------------+-----------------------------------+ 218 | List of Go build tags Gazelle will consider to be true. Gazelle applies | 219 | constraints when generating Go rules. It assumes certain tags are true on | 220 | certain platforms (for example, ``amd64,linux``). It assumes all Go release | 221 | tags are true (for example, ``go1.8``). It considers other tags to be false | 222 | (for example, ``ignore``). This flag overrides that behavior. | 223 +------------------------------------------+-----------------------------------+ 224 | :flag:`-external external|vendored` | :value:`external` | 225 +------------------------------------------+-----------------------------------+ 226 | Determines how Gazelle resolves import paths. May be :value:`external` or | 227 | :value:`vendored`. Gazelle translates Go import paths to Bazel labels when | 228 | resolving library dependencies. Import paths that start with the | 229 | ``go_prefix`` are resolved to local labels, but other imports | 230 | are resolved based on this mode. In :value:`external` mode, paths are | 231 | resolved using an external dependency in the WORKSPACE file (Gazelle does | 232 | not create or maintain these dependencies yet). In :value:`vendored` mode, | 233 | paths are resolved to a library in the vendor directory. | 234 +------------------------------------------+-----------------------------------+ 235 | :flag:`-go_prefix example.com/repo` | | 236 +------------------------------------------+-----------------------------------+ 237 | A prefix of import paths for libraries in the repository that corresponds to | 238 | the repository root. Gazelle infers this from the ``go_prefix`` rule in the | 239 | root BUILD.bazel file, if it exists. If not, this option is mandatory. | 240 | | 241 | This prefix is used to determine whether an import path refers to a library | 242 | in the current repository or an external dependency. | 243 +------------------------------------------+-----------------------------------+ 244 | :flag:`-known_import example.com` | | 245 +------------------------------------------+-----------------------------------+ 246 | Skips import path resolution for a known domain. May be repeated. | 247 | | 248 | When Gazelle resolves an import path to an external dependency, it attempts | 249 | to discover the remote repository root over HTTP. Gazelle skips this | 250 | discovery step for a few well-known domains with predictable structure, like | 251 | golang.org and github.com. This flag specifies additional domains to skip, | 252 | which is useful in situations where the lookup would fail for some reason. | 253 +------------------------------------------+-----------------------------------+ 254 | :flag:`-mode fix|print|diff` | :value:`fix` | 255 +------------------------------------------+-----------------------------------+ 256 | Method for emitting merged build files. | 257 | | 258 | In ``fix`` mode, Gazelle writes generated and merged files to disk. In | 259 | ``print`` mode, it prints them to stdout. In ``diff`` mode, it prints a | 260 | unified diff. | 261 +------------------------------------------+-----------------------------------+ 262 | :flag:`-proto default|legacy|disable` | :value:`default` | 263 +------------------------------------------+-----------------------------------+ 264 | Determines how Gazelle should generate rules for .proto files. See details | 265 | in `Directives`_ below. | 266 +------------------------------------------+-----------------------------------+ 267 | :flag:`-repo_root dir` | | 268 +------------------------------------------+-----------------------------------+ 269 | The root directory of the repository. Gazelle normally infers this to be the | 270 | directory containing the WORKSPACE file. | 271 | | 272 | Gazelle will not process packages outside this directory. | 273 +------------------------------------------+-----------------------------------+ 274 275 ``update-repos`` 276 ~~~~~~~~~~~~~~~~ 277 278 The ``update-repos`` command updates repository rules in the WORKSPACE file. 279 Currently, this can only be used to import repositories from a vendoring tool's 280 lock file. More functionality will be added in the future. 281 282 The following flags are accepted: 283 284 +------------------------------+-----------------------------------------------+ 285 | **Name** | **Default value** | 286 +==============================+===============================================+ 287 | :flag:`-from_file lock-file` | | 288 +------------------------------+-----------------------------------------------+ 289 | Import repositories from a vendoring tool's lock file as `go_repository`_ | 290 | rules. These rules will be added to the bottom of WORKSPACE or merged with | 291 | existing rules. | 292 | | 293 | The lock file format is inferred from the file's base name. Currently, only | 294 | Gopkg.lock is supported. | 295 +------------------------------+-----------------------------------------------+ 296 | :flag:`-repo_root dir` | | 297 +------------------------------+-----------------------------------------------+ 298 | The root directory of the repository. Gazelle normally infers this to be the | 299 | directory containing the WORKSPACE file. | 300 | | 301 | Gazelle will not process packages outside this directory. | 302 +------------------------------+-----------------------------------------------+ 303 304 Bazel rule 305 ~~~~~~~~~~ 306 307 When Gazelle is run by Bazel, most of the flags above can be encoded in the 308 ``gazelle`` rule. For example: 309 310 .. code:: bzl 311 312 load("@bazel_gazelle//:def.bzl", "gazelle") 313 314 gazelle( 315 name = "gazelle", 316 command = "fix", 317 prefix = "github.com/example/project", 318 external = "vendored", 319 build_tags = [ 320 "integration", 321 "debug", 322 ], 323 extra_args = [ 324 "-build_file_name", 325 "BUILD,BUILD.bazel", 326 ], 327 ) 328 329 Directives 330 ~~~~~~~~~~ 331 332 Gazelle supports several directives, written as comments in build files. 333 334 * ``# gazelle:ignore``: may be written at the top level of any build file. 335 Gazelle will not update files with this comment. 336 * ``# gazelle:exclude path``: may be written at the top level of 337 any build file. If the path refers to a source file, Gazelle won't include 338 it in any rules. If the path refers to a directory, Gazelle won't recurse 339 into it. The path may refer to something in a subdirectory, for example, 340 a testdata directory somewhere in a vendor tree. This directive may be 341 repeated to exclude multiple paths, one per line. 342 * ``# gazelle:proto <mode>``: Tells Gazelle how to generate rules for .proto 343 files. Applies to the current directory and subdirectories. Valid values for 344 ``mode`` are: 345 346 * ``default``: ``proto_library``, ``go_proto_library``, ``go_grpc_library``, 347 and ``go_library`` rules are generated using 348 ``@io_bazel_rules_go//proto:def.bzl``. This is the default mode. 349 * ``legacy``: ``filegroup`` rules are generated for use by 350 ``@io_bazel_rules_go//proto:go_proto_library.bzl``. ``go_proto_library`` 351 rules must be written by hand. Gazelle will run in this mode automatically 352 if ``go_proto_library.bzl`` is loaded to avoid disrupting existing 353 projects, but this can be overridden with a directive. 354 * ``disable``: .proto files are ignored. Gazelle will run in this mode 355 automatically if ``go_proto_library`` is loaded from any other source, 356 but this can be overridden with a directive. 357 * ``# keep``: may be written before a rule to prevent the rule from being 358 updated or after a source file, dependency, or flag to prevent it from being 359 removed. 360 361 Example 362 ^^^^^^^ 363 364 Suppose you have a library that includes a generated .go file. Gazelle won't 365 know what imports to resolve, so you may need to add dependencies manually with 366 ``# keep`` comments. 367 368 .. code:: bzl 369 370 load("@io_bazel_rules_go//go:def.bzl", "go_library") 371 load("@com_github_example_gen//:gen.bzl", "gen_go_file") 372 373 gen_go_file( 374 name = "magic", 375 srcs = ["magic.go.in"], 376 outs = ["magic.go"], 377 ) 378 379 go_library( 380 name = "go_default_library", 381 srcs = ["magic.go"], 382 visibility = ["//visibility:public"], 383 deps = [ 384 "@com_github_example_gen//:go_default_library", # keep 385 ], 386 ) 387 388 Fix command transformations 389 --------------------------- 390 391 When Gazelle is invoked with the ``fix`` command, in addition to updating 392 source files and dependencies of existing rules, Gazelle will remove deprecated 393 usage of the Go rules, analogous to ``go fix``. The following transformations 394 are performed. 395 396 **Squash cgo libraries**: Gazelle will remove `cgo_library` rules named 397 ``cgo_default_library`` and merge their attributes with a ``go_library`` rule 398 in the same package named ``go_default_library``. If no such ``go_library`` 399 rule exists, a new one will be created. Other ``cgo_library`` rules will not 400 be removed. 401 402 .. code:: bzl 403 # BEFORE 404 go_library( 405 name = "go_default_library", 406 srcs = ["pure.go"], 407 library = ":cgo_default_library", 408 ) 409 410 cgo_library( 411 name = "cgo_default_library", 412 srcs = ["cgo.go"], 413 ) 414 415 # AFTER 416 go_library( 417 name = "go_default_library", 418 srcs = [ 419 "cgo.go", 420 "pure.go", 421 ], 422 cgo = True, 423 ) 424 425 **Remove legacy protos**: Gazelle will remove usage of ``go_proto_library`` 426 rules loaded from ``@io_bazel_rules_go//proto:go_proto_library.bzl`` and 427 ``filegroup`` rules named ``go_default_library_protos``. Newly generated 428 proto rules will take their place. Since ``filegroup`` isn't needed anymore 429 and ``go_proto_library`` has different attributes and was always written by 430 hand, Gazelle will not attempt to merge anything from these rules with the 431 newly generated rules. 432 433 This transformation is only applied in the default proto mode. Since Gazelle 434 will run in legacy proto mode if ``go_proto_library.bzl`` is loaded, this 435 transformation is not usually applied. You can set the proto mode explicitly 436 using the directive ``# gazelle:proto default``. 437 438 .. code:: bzl 439 # BEFORE 440 # gazelle:proto default 441 load("@io_bazel_rules_go//proto:go_proto_library.bzl", "go_proto_library") 442 443 go_proto_library( 444 name = "go_default_library", 445 srcs = [":go_default_library_protos"], 446 ) 447 448 filegroup( 449 name = "go_default_library_protos", 450 srcs = ["foo.proto"], 451 ) 452 453 # AFTER 454 # The above rules are deleted. New proto_library, go_proto_library, and 455 # go_library rules will be generated automatically.