1<!-- Generated with Stardoc: http://skydoc.bazel.build -->
2
3Repository rules
4================
5
6Repository rules are Bazel rules that can be used in WORKSPACE files to import
7projects in external repositories. Repository rules may download projects
8and transform them by applying patches or generating build files.
9
10The Gazelle repository provides three rules:
11
12* [`go_repository`](#go_repository) downloads a Go project using either `go mod download`, a
13 version control tool like `git`, or a direct HTTP download. It understands
14 Go import path redirection. If build files are not already present, it can
15 generate them with Gazelle.
16* [`git_repository`](#git_repository) downloads a project with git. Unlike the native
17 `git_repository`, this rule allows you to specify an "overlay": a set of
18 files to be copied into the downloaded project. This may be used to add
19 pre-generated build files to a project that doesn't have them.
20* [`http_archive`](#http_archive) downloads a project via HTTP. It also lets you specify
21 overlay files.
22
23**NOTE:** `git_repository` and `http_archive` are deprecated in favor of the
24rules of the same name in [@bazel_tools//tools/build_defs/repo:git.bzl] and
25[@bazel_tools//tools/build_defs/repo:http.bzl].
26
27Repository rules can be loaded and used in WORKSPACE like this:
28
29```starlark
30load("@bazel_gazelle//:deps.bzl", "go_repository")
31
32go_repository(
33 name = "com_github_pkg_errors",
34 commit = "816c9085562cd7ee03e7f8188a1cfd942858cded",
35 importpath = "github.com/pkg/errors",
36)
37```
38
39Gazelle can add and update some of these rules automatically using the
40`update-repos` command. For example, the rule above can be added with:
41
42```shell
43$ gazelle update-repos github.com/pkg/errors
44```
45
46[http_archive.strip_prefix]: https://docs.bazel.build/versions/master/be/workspace.html#http_archive.strip_prefix
47[native git_repository rule]: https://docs.bazel.build/versions/master/be/workspace.html#git_repository
48[native http_archive rule]: https://docs.bazel.build/versions/master/be/workspace.html#http_archive
49[manifest.bzl]: third_party/manifest.bzl
50[Directives]: /README.rst#directives
51[@bazel_tools//tools/build_defs/repo:git.bzl]: https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/repo/git.bzl
52[@bazel_tools//tools/build_defs/repo:http.bzl]: https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/repo/http.bzl
53
54<a id="git_repository"></a>
55
56## git_repository
57
58<pre>
59git_repository(<a href="#git_repository-name">name</a>, <a href="#git_repository-commit">commit</a>, <a href="#git_repository-overlay">overlay</a>, <a href="#git_repository-remote">remote</a>, <a href="#git_repository-repo_mapping">repo_mapping</a>, <a href="#git_repository-tag">tag</a>)
60</pre>
61
62**NOTE:** `git_repository` is deprecated in favor of the rule of the same name
63in [@bazel_tools//tools/build_defs/repo:git.bzl].
64
65`git_repository` downloads a project with git. It has the same features as the
66[native git_repository rule], but it also allows you to copy a set of files
67into the repository after download. This is particularly useful for placing
68pre-generated build files.
69
70**Example**
71
72```starlark
73load("@bazel_gazelle//:deps.bzl", "git_repository")
74
75git_repository(
76 name = "com_github_pkg_errors",
77 remote = "https://github.com/pkg/errors",
78 commit = "816c9085562cd7ee03e7f8188a1cfd942858cded",
79 overlay = {
80 "@my_repo//third_party:com_github_pkg_errors/BUILD.bazel.in" : "BUILD.bazel",
81 },
82)
83```
84
85**ATTRIBUTES**
86
87
88| Name | Description | Type | Mandatory | Default |
89| :------------- | :------------- | :------------- | :------------- | :------------- |
90| <a id="git_repository-name"></a>name | A unique name for this repository. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
91| <a id="git_repository-commit"></a>commit | The git commit to check out. Either `commit` or `tag` may be specified. | String | optional | `""` |
92| <a id="git_repository-overlay"></a>overlay | A set of files to copy into the downloaded repository. The keys in this dictionary are Bazel labels that point to the files to copy. These must be fully qualified labels (i.e., `@repo//pkg:name`) because relative labels are interpreted in the checked out repository, not the repository containing the WORKSPACE file. The values in this dictionary are root-relative paths where the overlay files should be written.<br><br>It's convenient to store the overlay dictionaries for all repositories in a separate .bzl file. See Gazelle's `manifest.bzl`_ for an example. | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional | `{}` |
93| <a id="git_repository-remote"></a>remote | The remote repository to download. | String | required | |
94| <a id="git_repository-repo_mapping"></a>repo_mapping | In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<br><br>For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`).<br><br>This attribute is _not_ supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function). | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | |
95| <a id="git_repository-tag"></a>tag | The git tag to check out. Either `commit` or `tag` may be specified. | String | optional | `""` |
96
97
98<a id="go_repository"></a>
99
100## go_repository
101
102<pre>
103go_repository(<a href="#go_repository-name">name</a>, <a href="#go_repository-auth_patterns">auth_patterns</a>, <a href="#go_repository-build_config">build_config</a>, <a href="#go_repository-build_directives">build_directives</a>, <a href="#go_repository-build_external">build_external</a>, <a href="#go_repository-build_extra_args">build_extra_args</a>,
104 <a href="#go_repository-build_file_generation">build_file_generation</a>, <a href="#go_repository-build_file_name">build_file_name</a>, <a href="#go_repository-build_file_proto_mode">build_file_proto_mode</a>, <a href="#go_repository-build_naming_convention">build_naming_convention</a>,
105 <a href="#go_repository-build_tags">build_tags</a>, <a href="#go_repository-canonical_id">canonical_id</a>, <a href="#go_repository-commit">commit</a>, <a href="#go_repository-debug_mode">debug_mode</a>, <a href="#go_repository-importpath">importpath</a>, <a href="#go_repository-patch_args">patch_args</a>, <a href="#go_repository-patch_cmds">patch_cmds</a>,
106 <a href="#go_repository-patch_tool">patch_tool</a>, <a href="#go_repository-patches">patches</a>, <a href="#go_repository-remote">remote</a>, <a href="#go_repository-replace">replace</a>, <a href="#go_repository-repo_mapping">repo_mapping</a>, <a href="#go_repository-sha256">sha256</a>, <a href="#go_repository-strip_prefix">strip_prefix</a>, <a href="#go_repository-sum">sum</a>, <a href="#go_repository-tag">tag</a>,
107 <a href="#go_repository-type">type</a>, <a href="#go_repository-urls">urls</a>, <a href="#go_repository-vcs">vcs</a>, <a href="#go_repository-version">version</a>)
108</pre>
109
110`go_repository` downloads a Go project and generates build files with Gazelle
111if they are not already present. This is the simplest way to depend on
112external Go projects.
113
114When `go_repository` is in module mode, it saves downloaded modules in a shared,
115internal cache within Bazel's cache. It may be cleared with `bazel clean --expunge`.
116By setting the environment variable `GO_REPOSITORY_USE_HOST_CACHE=1`, you can
117force `go_repository` to use the module cache on the host system in the location
118returned by `go env GOPATH`. Alternatively, by setting the environment variable
119`GO_REPOSITORY_USE_HOST_MODCACHE=1`, you can force `go_repository` to use only
120the module cache on the host system in the location returned by `go env GOMODCACHE`.
121
122**Example**
123
124```starlark
125load("@bazel_gazelle//:deps.bzl", "go_repository")
126
127# Download using "go mod download"
128go_repository(
129 name = "com_github_pkg_errors",
130 importpath = "github.com/pkg/errors",
131 sum = "h1:iURUrRGxPUNPdy5/HRSm+Yj6okJ6UtLINN0Q9M4+h3I=",
132 version = "v0.8.1",
133)
134
135# Download automatically via git
136go_repository(
137 name = "com_github_pkg_errors",
138 commit = "816c9085562cd7ee03e7f8188a1cfd942858cded",
139 importpath = "github.com/pkg/errors",
140)
141
142# Download from git fork
143go_repository(
144 name = "com_github_pkg_errors",
145 commit = "816c9085562cd7ee03e7f8188a1cfd942858cded",
146 importpath = "github.com/pkg/errors",
147 remote = "https://example.com/fork/github.com/pkg/errors",
148 vcs = "git",
149)
150
151# Download via HTTP
152go_repository(
153 name = "com_github_pkg_errors",
154 importpath = "github.com/pkg/errors",
155 urls = ["https://codeload.github.com/pkg/errors/zip/816c9085562cd7ee03e7f8188a1cfd942858cded"],
156 strip_prefix = "errors-816c9085562cd7ee03e7f8188a1cfd942858cded",
157 type = "zip",
158)
159
160# Download major version suffixed via git
161go_repository(
162 name = "com_github_thediveo_enumflag_v2",
163 commit = "0217df583bf3d37b92798602e5061b36556bcd38",
164 importpath = "github.com/thediveo/enumflag/v2",
165 remote = "https://github.com/thediveo/enumflag",
166 vcs = "git",
167)
168```
169
170**ATTRIBUTES**
171
172
173| Name | Description | Type | Mandatory | Default |
174| :------------- | :------------- | :------------- | :------------- | :------------- |
175| <a id="go_repository-name"></a>name | A unique name for this repository. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
176| <a id="go_repository-auth_patterns"></a>auth_patterns | An optional dict mapping host names to custom authorization patterns.<br><br>If a URL's host name is present in this dict the value will be used as a pattern when generating the authorization header for the http request. This enables the use of custom authorization schemes used in a lot of common cloud storage providers.<br><br>The pattern currently supports 2 tokens: <code><login></code> and <code><password></code>, which are replaced with their equivalent value in the netrc file for the same host name. After formatting, the result is set as the value for the <code>Authorization</code> field of the HTTP request.<br><br>Example attribute and netrc for a http download to an oauth2 enabled API using a bearer token:<br><br><pre> auth_patterns = { "storage.cloudprovider.com": "Bearer <password>" } </pre><br><br>netrc:<br><br><pre> machine storage.cloudprovider.com password RANDOM-TOKEN </pre><br><br>The final HTTP request would have the following header:<br><br><pre> Authorization: Bearer RANDOM-TOKEN </pre> | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | `{}` |
177| <a id="go_repository-build_config"></a>build_config | A file that Gazelle should read to learn about external repositories before generating build files. This is useful for dependency resolution. For example, a `go_repository` rule in this file establishes a mapping between a repository name like `golang.org/x/tools` and a workspace name like `org_golang_x_tools`. Workspace directives like `# gazelle:repository_macro` are recognized.<br><br>`go_repository` rules will be re-evaluated when parts of WORKSPACE related to Gazelle's configuration are changed, including Gazelle directives and `go_repository` `name` and `importpath` attributes. Their content should still be fetched from a local cache, but build files will be regenerated. If this is not desirable, `build_config` may be set to a less frequently updated file or `None` to disable this functionality. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `"@bazel_gazelle_go_repository_config//:WORKSPACE"` |
178| <a id="go_repository-build_directives"></a>build_directives | A list of directives to be written to the root level build file before Calling Gazelle to generate build files. Each string in the list will be prefixed with `#` automatically. A common use case is to pass a list of Gazelle directives. | List of strings | optional | `[]` |
179| <a id="go_repository-build_external"></a>build_external | One of `"external"`, `"static"` or `"vendored"`.<br><br>This sets Gazelle's `-external` command line flag. In `"static"` mode, Gazelle will not call out to the network to resolve imports.<br><br>**NOTE:** This cannot be used to ignore the `vendor` directory in a repository. The `-external` flag only controls how Gazelle resolves imports which are not present in the repository. Use `build_extra_args = ["-exclude=vendor"]` instead. | String | optional | `"static"` |
180| <a id="go_repository-build_extra_args"></a>build_extra_args | A list of additional command line arguments to pass to Gazelle when generating build files. | List of strings | optional | `[]` |
181| <a id="go_repository-build_file_generation"></a>build_file_generation | One of `"auto"`, `"on"`, `"off"`.<br><br>Whether Gazelle should generate build files in the repository. In `"auto"` mode, Gazelle will run if there is no build file in the repository root directory. | String | optional | `"auto"` |
182| <a id="go_repository-build_file_name"></a>build_file_name | Comma-separated list of names Gazelle will consider to be build files. If a repository contains files named `build` that aren't related to Bazel, it may help to set this to `"BUILD.bazel"`, especially on case-insensitive file systems. | String | optional | `"BUILD.bazel,BUILD"` |
183| <a id="go_repository-build_file_proto_mode"></a>build_file_proto_mode | One of `"default"`, `"legacy"`, `"disable"`, `"disable_global"` or `"package"`.<br><br>This sets Gazelle's `-proto` command line flag. See [Directives] for more information on each mode. | String | optional | `""` |
184| <a id="go_repository-build_naming_convention"></a>build_naming_convention | Sets the library naming convention to use when resolving dependencies against this external repository. If unset, the convention from the external workspace is used. Legal values are `go_default_library`, `import`, and `import_alias`.<br><br>See the `gazelle:go_naming_convention` directive in [Directives] for more information. | String | optional | `"import_alias"` |
185| <a id="go_repository-build_tags"></a>build_tags | This sets Gazelle's `-build_tags` command line flag. | List of strings | optional | `[]` |
186| <a id="go_repository-canonical_id"></a>canonical_id | If the repository is downloaded via HTTP (`urls` is set) and this is set, restrict cache hits to those cases where the repository was added to the cache with the same canonical id. | String | optional | `""` |
187| <a id="go_repository-commit"></a>commit | If the repository is downloaded using a version control tool, this is the commit or revision to check out. With git, this would be a sha1 commit id. `commit` and `tag` may not both be set. | String | optional | `""` |
188| <a id="go_repository-debug_mode"></a>debug_mode | Enables logging of fetch_repo and Gazelle output during succcesful runs. Gazelle can be noisy so this defaults to `False`. However, setting to `True` can be useful for debugging build failures and unexpected behavior for the given rule. | Boolean | optional | `False` |
189| <a id="go_repository-importpath"></a>importpath | The Go import path that matches the root directory of this repository.<br><br>In module mode (when `version` is set), this must be the module path. If neither `urls` nor `remote` is specified, `go_repository` will automatically find the true path of the module, applying import path redirection.<br><br>If build files are generated for this repository, libraries will have their `importpath` attributes prefixed with this `importpath` string. | String | required | |
190| <a id="go_repository-patch_args"></a>patch_args | Arguments passed to the patch tool when applying patches. | List of strings | optional | `["-p0"]` |
191| <a id="go_repository-patch_cmds"></a>patch_cmds | Commands to run in the repository after patches are applied. | List of strings | optional | `[]` |
192| <a id="go_repository-patch_tool"></a>patch_tool | The patch tool used to apply `patches`. If this is specified, Bazel will use the specifed patch tool instead of the Bazel-native patch implementation. | String | optional | `""` |
193| <a id="go_repository-patches"></a>patches | A list of patches to apply to the repository after gazelle runs. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` |
194| <a id="go_repository-remote"></a>remote | The VCS location where the repository should be downloaded from. This is usually inferred from `importpath`, but you can set `remote` to download from a private repository or a fork. | String | optional | `""` |
195| <a id="go_repository-replace"></a>replace | A replacement for the module named by `importpath`. The module named by `replace` will be downloaded at `version` and verified with `sum`.<br><br>NOTE: There is no `go_repository` equivalent to file path `replace` directives. Use `local_repository` instead. | String | optional | `""` |
196| <a id="go_repository-repo_mapping"></a>repo_mapping | In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<br><br>For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`).<br><br>This attribute is _not_ supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function). | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | |
197| <a id="go_repository-sha256"></a>sha256 | If the repository is downloaded via HTTP (`urls` is set), this is the SHA-256 sum of the downloaded archive. When set, Bazel will verify the archive against this sum before extracting it.<br><br>**CAUTION:** Do not use this with services that prepare source archives on demand, such as codeload.github.com. Any minor change in the server software can cause differences in file order, alignment, and compression that break SHA-256 sums. | String | optional | `""` |
198| <a id="go_repository-strip_prefix"></a>strip_prefix | If the repository is downloaded via HTTP (`urls` is set), this is a directory prefix to strip. See [`http_archive.strip_prefix`]. | String | optional | `""` |
199| <a id="go_repository-sum"></a>sum | A hash of the module contents. In module mode, `go_repository` will verify the downloaded module matches this sum. May only be set when `version` is also set.<br><br>A value for `sum` may be found in the `go.sum` file or by running `go mod download -json <module>@<version>`. | String | optional | `""` |
200| <a id="go_repository-tag"></a>tag | If the repository is downloaded using a version control tool, this is the named revision to check out. `commit` and `tag` may not both be set. | String | optional | `""` |
201| <a id="go_repository-type"></a>type | One of `"zip"`, `"tar.gz"`, `"tgz"`, `"tar.bz2"`, `"tar.xz"`.<br><br>If the repository is downloaded via HTTP (`urls` is set), this is the file format of the repository archive. This is normally inferred from the downloaded file name. | String | optional | `""` |
202| <a id="go_repository-urls"></a>urls | A list of HTTP(S) URLs where an archive containing the project can be downloaded. Bazel will attempt to download from the first URL; the others are mirrors. | List of strings | optional | `[]` |
203| <a id="go_repository-vcs"></a>vcs | One of `"git"`, `"hg"`, `"svn"`, `"bzr"`.<br><br>The version control system to use. This is usually determined automatically, but it may be necessary to set this when `remote` is set and the VCS cannot be inferred. You must have the corresponding tool installed on your host. | String | optional | `""` |
204| <a id="go_repository-version"></a>version | If specified, `go_repository` will download the module at this version using `go mod download`. `sum` must also be set. `commit`, `tag`, and `urls` may not be set. | String | optional | `""` |
205
206
207<a id="http_archive"></a>
208
209## http_archive
210
211<pre>
212http_archive(<a href="#http_archive-name">name</a>, <a href="#http_archive-overlay">overlay</a>, <a href="#http_archive-repo_mapping">repo_mapping</a>, <a href="#http_archive-sha256">sha256</a>, <a href="#http_archive-strip_prefix">strip_prefix</a>, <a href="#http_archive-type">type</a>, <a href="#http_archive-urls">urls</a>)
213</pre>
214
215**NOTE:** `http_archive` is deprecated in favor of the rule of the same name
216in [@bazel_tools//tools/build_defs/repo:http.bzl].
217
218`http_archive` downloads a project over HTTP(S). It has the same features as
219the [native http_archive rule], but it also allows you to copy a set of files
220into the repository after download. This is particularly useful for placing
221pre-generated build files.
222
223**Example**
224
225```starlark
226load("@bazel_gazelle//:deps.bzl", "http_archive")
227
228http_archive(
229 name = "com_github_pkg_errors",
230 urls = ["https://codeload.github.com/pkg/errors/zip/816c9085562cd7ee03e7f8188a1cfd942858cded"],
231 strip_prefix = "errors-816c9085562cd7ee03e7f8188a1cfd942858cded",
232 type = "zip",
233 overlay = {
234 "@my_repo//third_party:com_github_pkg_errors/BUILD.bazel.in" : "BUILD.bazel",
235 },
236)
237```
238
239**ATTRIBUTES**
240
241
242| Name | Description | Type | Mandatory | Default |
243| :------------- | :------------- | :------------- | :------------- | :------------- |
244| <a id="http_archive-name"></a>name | A unique name for this repository. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
245| <a id="http_archive-overlay"></a>overlay | A set of files to copy into the downloaded repository. The keys in this dictionary are Bazel labels that point to the files to copy. These must be fully qualified labels (i.e., `@repo//pkg:name`) because relative labels are interpreted in the checked out repository, not the repository containing the WORKSPACE file. The values in this dictionary are root-relative paths where the overlay files should be written.<br><br>It's convenient to store the overlay dictionaries for all repositories in a separate .bzl file. See Gazelle's `manifest.bzl`_ for an example. | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional | `{}` |
246| <a id="http_archive-repo_mapping"></a>repo_mapping | In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<br><br>For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`).<br><br>This attribute is _not_ supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function). | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | |
247| <a id="http_archive-sha256"></a>sha256 | The SHA-256 sum of the downloaded archive. When set, Bazel will verify the archive against this sum before extracting it.<br><br>**CAUTION:** Do not use this with services that prepare source archives on demand, such as codeload.github.com. Any minor change in the server software can cause differences in file order, alignment, and compression that break SHA-256 sums. | String | optional | `""` |
248| <a id="http_archive-strip_prefix"></a>strip_prefix | A directory prefix to strip. See [http_archive.strip_prefix]. | String | optional | `""` |
249| <a id="http_archive-type"></a>type | One of `"zip"`, `"tar.gz"`, `"tgz"`, `"tar.bz2"`, `"tar.xz"`.<br><br>The file format of the repository archive. This is normally inferred from the downloaded file name. | String | optional | `""` |
250| <a id="http_archive-urls"></a>urls | A list of HTTP(S) URLs where the project can be downloaded. Bazel will attempt to download the first URL; the others are mirrors. | List of strings | optional | `[]` |
251
252
View as plain text