github.com/wolfd/bazel-gazelle@v0.14.0/repository.rst (about) 1 Repository rules 2 ================ 3 4 .. _http_archive.strip_prefix: https://docs.bazel.build/versions/master/be/workspace.html#http_archive.strip_prefix 5 .. _native git_repository rule: https://docs.bazel.build/versions/master/be/workspace.html#git_repository 6 .. _native http_archive rule: https://docs.bazel.build/versions/master/be/workspace.html#http_archive 7 .. _manifest.bzl: third_party/manifest.bzl 8 .. _Directives: /README.rst#directives 9 10 .. role:: param(kbd) 11 .. role:: type(emphasis) 12 .. role:: value(code) 13 .. |mandatory| replace:: **mandatory value** 14 15 Repository rules are Bazel rules that can be used in WORKSPACE files to import 16 projects in external repositories. Repository rules may download projects 17 and transform them by applying patches or generating build files. 18 19 The Gazelle repository provides three rules: 20 21 * `go_repository`_ downloads a Go project over HTTP or using a version control 22 tool like git. It understands Go import path redirection. If build files are 23 not already present, it can generate them with Gazelle. 24 * `git_repository`_ downloads a project with git. Unlike the native 25 ``git_repository``, this rule allows you to specify an "overlay": a set of 26 files to be copied into the downloaded project. This may be used to add 27 pre-generated build files to a project that doesn't have them. 28 * `http_archive`_ downloads a project via HTTP. It also lets you specify 29 overlay files. 30 31 Repository rules can be loaded and used in WORKSPACE like this: 32 33 .. code:: bzl 34 35 load("@bazel_gazelle//:deps.bzl", "go_repository") 36 37 go_repository( 38 name = "com_github_pkg_errors", 39 commit = "816c9085562cd7ee03e7f8188a1cfd942858cded", 40 importpath = "github.com/pkg/errors", 41 ) 42 43 Gazelle can add and update some of these rules automatically using the 44 ``update-repos`` command. For example, the rule above can be added with: 45 46 .. code:: 47 48 $ gazelle update-repos github.com/pkg/errors 49 50 go_repository 51 ------------- 52 53 ``go_repository`` downloads a Go project and generates build files with Gazelle 54 if they are not already present. This is the simplest way to depend on 55 external Go projects. 56 57 **Example** 58 59 .. code:: bzl 60 61 load("@bazel_gazelle//:deps.bzl", "go_repository") 62 63 # Download automatically via git 64 go_repository( 65 name = "com_github_pkg_errors", 66 commit = "816c9085562cd7ee03e7f8188a1cfd942858cded", 67 importpath = "github.com/pkg/errors", 68 ) 69 70 # Download from git fork 71 go_repository( 72 name = "com_github_pkg_errors", 73 commit = "816c9085562cd7ee03e7f8188a1cfd942858cded", 74 importpath = "github.com/pkg/errors", 75 remote = "https://example.com/fork/github.com/pkg/errors", 76 vcs = "git", 77 ) 78 79 # Download via HTTP 80 go_repository( 81 name = "com_github_pkg_errors", 82 importpath = "github.com/pkg/errors", 83 urls = ["https://codeload.github.com/pkg/errors/zip/816c9085562cd7ee03e7f8188a1cfd942858cded"], 84 strip_prefix = ["errors-816c9085562cd7ee03e7f8188a1cfd942858cded"], 85 type = "zip", 86 ) 87 88 **Attributes** 89 90 +--------------------------------+----------------------+-------------------------------------------------+ 91 | **Name** | **Type** | **Default value** | 92 +--------------------------------+----------------------+-------------------------------------------------+ 93 | :param:`name` | :type:`string` | |mandatory| | 94 +--------------------------------+----------------------+-------------------------------------------------+ 95 | A unique name for this rule. This should usually be the Java-package-style | 96 | name of the URL, with underscores as separators, for example, | 97 | ``com_github_example_project``. | 98 +--------------------------------+----------------------+-------------------------------------------------+ 99 | :param:`importpath` | :type:`string` | |mandatory| | 100 +--------------------------------+----------------------+-------------------------------------------------+ 101 | The Go import path that matches the root directory of this repository. If | 102 | neither ``urls`` nor ``remote`` are specified, ``go_repository`` will download | 103 | the repository from this location. This supports import path redirection. | 104 | If build files are generated, libraries will have ``importpath`` prefixed | 105 | with this string. | 106 +--------------------------------+----------------------+-------------------------------------------------+ 107 | :param:`commit` | :type:`string` | :value:`""` | 108 +--------------------------------+----------------------+-------------------------------------------------+ 109 | If the repository is downloaded using a version control tool, this is the | 110 | commit or revision to check out. With git, this would be a sha1 commit id. | 111 | ``commit`` and ``tag`` may not both be set. | 112 +--------------------------------+----------------------+-------------------------------------------------+ 113 | :param:`tag` | :type:`string` | :value:`""` | 114 +--------------------------------+----------------------+-------------------------------------------------+ 115 | If the repository is downloaded using a version control tool, this is the | 116 | named revision to check out. ``commit`` and ``tag`` may not both be set. | 117 +--------------------------------+----------------------+-------------------------------------------------+ 118 | :param:`vcs` | :type:`string` | :value:`""` | 119 +--------------------------------+----------------------+-------------------------------------------------+ 120 | One of ``"git"``, ``"hg"``, ``"svn"``, ``"bzr"``. | 121 | | 122 | The version control system to use. This is usually determined automatically, | 123 | but it may be necessary to set this when ``remote`` is set and the VCS cannot | 124 | be inferred. You must have the corresponding tool installed on your host. | 125 +--------------------------------+----------------------+-------------------------------------------------+ 126 | :param:`remote` | :type:`string` | :value:`""` | 127 +--------------------------------+----------------------+-------------------------------------------------+ 128 | The VCS location where the repository should be downloaded from. This is | 129 | usually inferred from ``importpath``, but you can set ``remote`` to download | 130 | from a private repository or a fork. | 131 +--------------------------------+----------------------+-------------------------------------------------+ 132 | :param:`urls` | :type:`string list` | :value:`[]` | 133 +--------------------------------+----------------------+-------------------------------------------------+ 134 | A list of HTTP(S) URLs where an archive containing the project can be | 135 | downloaded. Bazel will attempt to download from the first URL; the others | 136 | are mirrors. | 137 +--------------------------------+----------------------+-------------------------------------------------+ 138 | :param:`strip_prefix` | :type:`string` | :value:`""` | 139 +--------------------------------+----------------------+-------------------------------------------------+ 140 | If the repository is downloaded via HTTP (``urls`` is set), this is a | 141 | directory prefix to strip. See `http_archive.strip_prefix`_. | 142 +--------------------------------+----------------------+-------------------------------------------------+ 143 | :param:`type` | :type:`string` | :value:`""` | 144 +--------------------------------+----------------------+-------------------------------------------------+ 145 | One of ``"zip"``, ``"tar.gz"``, ``"tgz"``, ``"tar.bz2"``, ``"tar.xz"``. | 146 | | 147 | If the repository is downloaded via HTTP (``urls`` is set), this is the | 148 | file format of the repository archive. This is normally inferred from the | 149 | downloaded file name. | 150 +--------------------------------+----------------------+-------------------------------------------------+ 151 | :param:`sha256` | :type:`string` | :value:`""` | 152 +--------------------------------+----------------------+-------------------------------------------------+ 153 | If the repository is downloaded via HTTP (``urls`` is set), this is the | 154 | SHA-256 sum of the downloaded archive. When set, Bazel will verify the archive | 155 | against this sum before extracting it. | 156 | | 157 | **CAUTION:** Do not use this with services that prepare source archives on | 158 | demand, such as codeload.github.com. Any minor change in the server software | 159 | can cause differences in file order, alignment, and compression that break | 160 | SHA-256 sums. | 161 +--------------------------------+----------------------+-------------------------------------------------+ 162 | :param:`build_file_generation` | :type:`string` | :value:`"auto"` | 163 +--------------------------------+----------------------+-------------------------------------------------+ 164 | One of ``"auto"``, ``"on"``, ``"off"``. | 165 | | 166 | Whether Gazelle should generate build files in the repository. In ``"auto"`` | 167 | mode, Gazelle will run if there is no build file in the repository root | 168 | directory. | 169 +--------------------------------+----------------------+-------------------------------------------------+ 170 | :param:`build_file_name` | :type:`string` | :value:`BUILD.bazel,BUILD` | 171 +--------------------------------+----------------------+-------------------------------------------------+ 172 | Comma-separated list of names Gazelle will consider to be build files. | 173 | If a repository contains files named ``build`` that aren't related to Bazel, | 174 | it may help to set this to ``"BUILD.bazel"``, especially on case-insensitive | 175 | file systems. | 176 +--------------------------------+----------------------+-------------------------------------------------+ 177 | :param:`build_external` | :type:`string` | :value:`""` | 178 +--------------------------------+----------------------+-------------------------------------------------+ 179 | One of ``"external"``, ``"vendored"``. | 180 | | 181 | This sets Gazelle's ``-external`` command line flag. | 182 +--------------------------------+----------------------+-------------------------------------------------+ 183 | :param:`build_tags` | :type:`string list` | :value:`[]` | 184 +--------------------------------+----------------------+-------------------------------------------------+ 185 | This sets Gazelle's ``-build_tags`` command line flag. | 186 +--------------------------------+----------------------+-------------------------------------------------+ 187 | :param:`build_file_proto_mode` | :type:`string` | :value:`""` | 188 +--------------------------------+----------------------+-------------------------------------------------+ 189 | One of ``"default"``, ``"legacy"``, ``"disable"``, ``"disable_global"`` or | 190 | ``"package"``. | 191 | | 192 | This sets Gazelle's ``-proto`` command line flag. See Directives_ for more | 193 | information on each mode. | 194 +--------------------------------+----------------------+-------------------------------------------------+ 195 | :param:`build_extra_args` | :type:`string list` | :value:`[]` | 196 +--------------------------------+----------------------+-------------------------------------------------+ 197 | A list of additional command line arguments to pass to Gazelle when | 198 | generating build files. | 199 +--------------------------------+----------------------+-------------------------------------------------+ 200 201 git_repository 202 -------------- 203 204 ``git_repository`` downloads a project with git. It has the same features as the 205 `native git_repository rule`_, but it also allows you to copy a set of files 206 into the repository after download. This is particularly useful for placing 207 pre-generated build files. 208 209 **Example** 210 211 .. code:: bzl 212 213 load("@bazel_gazelle//:deps.bzl", "git_repository") 214 215 git_repository( 216 name = "com_github_pkg_errors", 217 remote = "https://github.com/pkg/errors", 218 commit = "816c9085562cd7ee03e7f8188a1cfd942858cded", 219 overlay = { 220 "@my_repo//third_party:com_github_pkg_errors/BUILD.bazel.in" : "BUILD.bazel", 221 }, 222 ) 223 224 **Attributes** 225 226 +--------------------------------+----------------------+-------------------------------------------------+ 227 | **Name** | **Type** | **Default value** | 228 +--------------------------------+----------------------+-------------------------------------------------+ 229 | :param:`name` | :type:`string` | |mandatory| | 230 +--------------------------------+----------------------+-------------------------------------------------+ 231 | A unique name for this rule. This should usually be the Java-package-style | 232 | name of the URL, with underscores as separators, for example, | 233 | ``com_github_example_project``. | 234 +--------------------------------+----------------------+-------------------------------------------------+ 235 | :param:`remote` | :type:`string` | |mandatory| | 236 +--------------------------------+----------------------+-------------------------------------------------+ 237 | The remote repository to download. | 238 +--------------------------------+----------------------+-------------------------------------------------+ 239 | :param:`commit` | :type:`string` | :value:`""` | 240 +--------------------------------+----------------------+-------------------------------------------------+ 241 | The git commit to check out. Either ``commit`` or ``tag`` may be specified. | 242 +--------------------------------+----------------------+-------------------------------------------------+ 243 | :param:`tag` | :type:`tag` | :value:`""` | 244 +--------------------------------+----------------------+-------------------------------------------------+ 245 | The git tag to check out. Either ``commit`` or ``tag`` may be specified. | 246 +--------------------------------+----------------------+-------------------------------------------------+ 247 | :param:`overlay` | :type:`dict` | :value:`{}` | 248 +--------------------------------+----------------------+-------------------------------------------------+ 249 | A set of files to copy into the downloaded repository. The keys in this | 250 | dictionary are Bazel labels that point to the files to copy. These must be | 251 | fully qualified labels (i.e., ``@repo//pkg:name``) because relative labels | 252 | are interpreted in the checked out repository, not the repository containing | 253 | the WORKSPACE file. The values in this dictionary are root-relative paths | 254 | where the overlay files should be written. | 255 | | 256 | It's convenient to store the overlay dictionaries for all repositories in | 257 | a separate .bzl file. See Gazelle's `manifest.bzl`_ for an example. | 258 +--------------------------------+----------------------+-------------------------------------------------+ 259 260 http_archive 261 ------------ 262 263 ``http_archive`` downloads a project over HTTP(S). It has the same features as 264 the `native http_archive rule`_, but it also allows you to copy a set of files 265 into the repository after download. This is particularly useful for placing 266 pre-generated build files. 267 268 **Example** 269 270 .. code:: bzl 271 272 load("@bazel_gazelle//:deps.bzl", "http_archive") 273 274 http_archive( 275 name = "com_github_pkg_errors", 276 urls = ["https://codeload.github.com/pkg/errors/zip/816c9085562cd7ee03e7f8188a1cfd942858cded"], 277 strip_prefix = "errors-816c9085562cd7ee03e7f8188a1cfd942858cded", 278 type = "zip", 279 overlay = { 280 "@my_repo//third_party:com_github_pkg_errors/BUILD.bazel.in" : "BUILD.bazel", 281 }, 282 ) 283 284 **Attributes** 285 286 +--------------------------------+----------------------+-------------------------------------------------+ 287 | **Name** | **Type** | **Default value** | 288 +--------------------------------+----------------------+-------------------------------------------------+ 289 | :param:`name` | :type:`string` | |mandatory| | 290 +--------------------------------+----------------------+-------------------------------------------------+ 291 | A unique name for this rule. This should usually be the Java-package-style | 292 | name of the URL, with underscores as separators, for example, | 293 | ``com_github_example_project``. | 294 +--------------------------------+----------------------+-------------------------------------------------+ 295 | :param:`urls` | :type:`string list` | |mandatory| | 296 +--------------------------------+----------------------+-------------------------------------------------+ 297 | A list of HTTP(S) URLs where the project can be downloaded. Bazel will | 298 | attempt to download the first URL; the others are mirrors. | 299 +--------------------------------+----------------------+-------------------------------------------------+ 300 | :param:`sha256` | :type:`string` | :value:`""` | 301 +--------------------------------+----------------------+-------------------------------------------------+ 302 | The SHA-256 sum of the downloaded archive. When set, Bazel will verify the | 303 | archive against this sum before extracting it. | 304 | | 305 | **CAUTION:** Do not use this with services that prepare source archives on | 306 | demand, such as codeload.github.com. Any minor change in the server software | 307 | can cause differences in file order, alignment, and compression that break | 308 | SHA-256 sums. | 309 +--------------------------------+----------------------+-------------------------------------------------+ 310 | :param:`strip_prefix` | :type:`string` | :value:`""` | 311 +--------------------------------+----------------------+-------------------------------------------------+ 312 | A directory prefix to strip. See `http_archive.strip_prefix`_. | 313 +--------------------------------+----------------------+-------------------------------------------------+ 314 | :param:`type` | :type:`string` | :value:`""` | 315 +--------------------------------+----------------------+-------------------------------------------------+ 316 | One of ``"zip"``, ``"tar.gz"``, ``"tgz"``, ``"tar.bz2"``, ``"tar.xz"``. | 317 | | 318 | The file format of the repository archive. This is normally inferred from | 319 | the downloaded file name. | 320 +--------------------------------+----------------------+-------------------------------------------------+ 321 | :param:`overlay` | :type:`dict` | :value:`{}` | 322 +--------------------------------+----------------------+-------------------------------------------------+ 323 | A set of files to copy into the downloaded repository. The keys in this | 324 | dictionary are Bazel labels that point to the files to copy. These must be | 325 | fully qualified labels (i.e., ``@repo//pkg:name``) because relative labels | 326 | are interpreted in the checked out repository, not the repository containing | 327 | the WORKSPACE file. The values in this dictionary are root-relative paths | 328 | where the overlay files should be written. | 329 | | 330 | It's convenient to store the overlay dictionaries for all repositories in | 331 | a separate .bzl file. See Gazelle's `manifest.bzl`_ for an example. | 332 +--------------------------------+----------------------+-------------------------------------------------+