diff --git a/.bazelci/presubmit.yml b/.bazelci/presubmit.yml index 0f39e8de5..5e5767ad7 100644 --- a/.bazelci/presubmit.yml +++ b/.bazelci/presubmit.yml @@ -26,5 +26,8 @@ platforms: # autogazelle is only supported on UNIX-like platforms. # It requires UNIX domain sockets. - "-//cmd/autogazelle/..." + # Stardoc produces different line-endings on windows, + # so the documentation it generates doesn't match the checked in files + - "-//docs:all" # Fails to execute, apparently due to command-line length limit. - "-//internal:bazel_test" diff --git a/BUILD.bazel b/BUILD.bazel index 1447b0373..37175004b 100644 --- a/BUILD.bazel +++ b/BUILD.bazel @@ -32,7 +32,7 @@ nogo( visibility = ["//visibility:public"], ) -exports_files(["WORKSPACE"]) +exports_files(["WORKSPACE", "repository.md"]) filegroup( name = "all_files", diff --git a/WORKSPACE b/WORKSPACE index eaf216108..5fcc89e68 100644 --- a/WORKSPACE +++ b/WORKSPACE @@ -76,3 +76,15 @@ gazelle_dependencies() # gazelle:repository go_repository name=org_golang_x_text importpath=golang.org/x/text # gazelle:repository go_repository name=org_golang_x_tools importpath=golang.org/x/tools # gazelle:repository go_repository name=org_golang_x_xerrors importpath=golang.org/x/xerrors + +# For API doc generation +# This is a dev dependency, users should not need to install it +# so we declare it in the WORKSPACE +http_archive( + name = "io_bazel_stardoc", + sha256 = "c9794dcc8026a30ff67cf7cf91ebe245ca294b20b071845d12c192afe243ad72", + urls = [ + "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.0/stardoc-0.5.0.tar.gz", + "https://github.com/bazelbuild/stardoc/releases/download/0.5.0/stardoc-0.5.0.tar.gz", + ], +) diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel new file mode 100644 index 000000000..3fb1594dd --- /dev/null +++ b/docs/BUILD.bazel @@ -0,0 +1,54 @@ +"""Documentation generation with stardoc + +This is in a separate package from both the stardoc source files and the +resulting documentation markdown files, to prevent users trying to load() +the stardoc repository, which is not a dependency users should install. +""" +load("@bazel_skylib//rules:write_file.bzl", "write_file") +load("@bazel_skylib//rules:diff_test.bzl", "diff_test") +load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc") + +_DOC_SRCS = { + "//internal:repository_docs": "repository.md", +} + +[ + stardoc( + name = out.replace(".md", "_docgen"), + out = out, + # Convention: foo.bzl has bzl_library named "foo" + input = input + ".bzl", + deps = [input], + ) + for [input, out] in _DOC_SRCS.items() +] + +[ + diff_test( + name = "check_" + out, + failure_message = "Please run bazel run //docs:update", + # source file (InputArtifact) + file1 = "//:" + out, + # result from stardoc rule above + file2 = out, + ) + for out in _DOC_SRCS.values() +] + +write_file( + name = "gen_update", + out = "update.sh", + content = [ + "#!/usr/bin/env bash", + "cd $BUILD_WORKSPACE_DIRECTORY", + ] + [ + "cp -fv bazel-bin/docs/{0} {0}".format(v) + for v in _DOC_SRCS.values() + ], +) + +sh_binary( + name = "update", + srcs = ["update.sh"], + data = _DOC_SRCS.values(), +) diff --git a/internal/BUILD.bazel b/internal/BUILD.bazel index df23e15d8..6fa6c557e 100644 --- a/internal/BUILD.bazel +++ b/internal/BUILD.bazel @@ -20,6 +20,7 @@ go_bazel_test( exports_files( [ "gazelle.bash.in", + "repository_docs.bzl", "list_repository_tools_srcs.go", "repository_rules_test_errors.patch", ], @@ -113,3 +114,13 @@ bzl_library( srcs = ["overlay_repository.bzl"], visibility = ["//:__subpackages__"], ) + +bzl_library( + name = "repository_docs", + srcs = ["repository_docs.bzl"], + deps = [ + ":go_repository", + ":overlay_repository", + ], + visibility = ["//:__subpackages__"], +) \ No newline at end of file diff --git a/internal/go_repository.bzl b/internal/go_repository.bzl index 07f803402..27b8b0b84 100644 --- a/internal/go_repository.bzl +++ b/internal/go_repository.bzl @@ -16,6 +16,58 @@ load("//internal:common.bzl", "env_execute", "executable_extension") load("@bazel_gazelle//internal:go_repository_cache.bzl", "read_cache_env") load("@bazel_tools//tools/build_defs/repo:utils.bzl", "read_netrc", "use_netrc") +_DOC = """ +`go_repository` downloads a Go project and generates build files with Gazelle +if they are not already present. This is the simplest way to depend on +external Go projects. + +When `go_repository` is in module mode, it saves downloaded modules in a shared, +internal cache within Bazel's cache. It may be cleared with `bazel clean --expunge`. +By setting the environment variable `GO_REPOSITORY_USE_HOST_CACHE=1`, you can +force `go_repository` to use the module cache on the host system in the location +returned by `go env GOPATH`. + +**Example** + +```starlark +load("@bazel_gazelle//:deps.bzl", "go_repository") + +# Download using "go mod download" +go_repository( + name = "com_github_pkg_errors", + importpath = "github.com/pkg/errors", + sum = "h1:iURUrRGxPUNPdy5/HRSm+Yj6okJ6UtLINN0Q9M4+h3I=", + version = "v0.8.1", +) + +# Download automatically via git +go_repository( + name = "com_github_pkg_errors", + commit = "816c9085562cd7ee03e7f8188a1cfd942858cded", + importpath = "github.com/pkg/errors", +) + +# Download from git fork +go_repository( + name = "com_github_pkg_errors", + commit = "816c9085562cd7ee03e7f8188a1cfd942858cded", + importpath = "github.com/pkg/errors", + remote = "https://example.com/fork/github.com/pkg/errors", + vcs = "git", +) + +# Download via HTTP +go_repository( + name = "com_github_pkg_errors", + importpath = "github.com/pkg/errors", + urls = ["https://codeload.github.com/pkg/errors/zip/816c9085562cd7ee03e7f8188a1cfd942858cded"], + strip_prefix = "errors-816c9085562cd7ee03e7f8188a1cfd942858cded", + type = "zip", +) +``` + +""" + # We can't disable timeouts on Bazel, but we can set them to large values. _GO_REPOSITORY_TIMEOUT = 86400 @@ -214,15 +266,39 @@ def _go_repository_impl(ctx): go_repository = repository_rule( implementation = _go_repository_impl, + doc = _DOC, attrs = { # Fundamental attributes of a go repository - "importpath": attr.string(mandatory = True), + "importpath": attr.string( + doc = """The Go import path that matches the root directory of this repository. + + 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. + + If build files are generated for this repository, libraries will have their + `importpath` attributes prefixed with this `importpath` string. """, + mandatory = True, + ), # Attributes for a repository that should be checked out from VCS - "commit": attr.string(), - "tag": attr.string(), + "commit": attr.string( + doc = """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.""", + ), + "tag": attr.string( + doc = """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.""", + ), "vcs": attr.string( default = "", + doc = """One of `"git"`, `"hg"`, `"svn"`, `"bzr"`. + + 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.""", values = [ "", "git", @@ -231,31 +307,96 @@ go_repository = repository_rule( "bzr", ], ), - "remote": attr.string(), + "remote": attr.string( + doc = """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.""", + ), # Attributes for a repository that should be downloaded via HTTP. - "urls": attr.string_list(), - "strip_prefix": attr.string(), - "type": attr.string(), - "sha256": attr.string(), - "canonical_id": attr.string(), + "urls": attr.string_list( + doc = """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.""", + ), + "strip_prefix": attr.string( + doc = """If the repository is downloaded via HTTP (`urls` is set), this is a + directory prefix to strip. See [`http_archive.strip_prefix`].""", + ), + "type": attr.string( + doc = """One of `"zip"`, `"tar.gz"`, `"tgz"`, `"tar.bz2"`, `"tar.xz"`. + + 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.""", + ), + "sha256": attr.string( + doc = """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. + + **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.""", + ), + "canonical_id": attr.string( + doc = """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.""", + ), # Attributes for a module that should be downloaded with the Go toolchain. - "version": attr.string(), - "sum": attr.string(), - "replace": attr.string(), + "version": attr.string( + doc = """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. """, + ), + "sum": attr.string( + doc = """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. + + A value for `sum` may be found in the `go.sum` file or by running + `go mod download -json @`.""", + ), + "replace": attr.string( + doc = """A replacement for the module named by `importpath`. The module named by + `replace` will be downloaded at `version` and verified with `sum`. + + NOTE: There is no `go_repository` equivalent to file path `replace` + directives. Use `local_repository` instead.""" + ), # Attributes for a repository that needs automatic build file generation "build_external": attr.string( + doc = """One of `"external"`, `"vendored"`. + + This sets Gazelle's `-external` command line flag. + + **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.""", values = [ "", "external", "vendored", ], ), - "build_file_name": attr.string(default = "BUILD.bazel,BUILD"), + "build_file_name": attr.string( + default = "BUILD.bazel,BUILD", + doc = """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.""", + ), "build_file_generation": attr.string( default = "auto", + doc = """One of `"auto"`, `"on"`, `"off"`. + + 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.""", values = [ "on", "auto", @@ -269,9 +410,20 @@ go_repository = repository_rule( "import_alias", ], default = "import_alias", + doc = """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`. + + See the `gazelle:go_naming_convention` directive in [Directives] for more information.""", + ), + "build_tags": attr.string_list( + doc = "This sets Gazelle's `-build_tags` command line flag.", ), - "build_tags": attr.string_list(), "build_file_proto_mode": attr.string( + doc = """One of `"default"`, `"legacy"`, `"disable"`, `"disable_global"` or `"package"`. + + This sets Gazelle's `-proto` command line flag. See Directives_ for more + information on each mode.""", values = [ "", "default", @@ -281,15 +433,49 @@ go_repository = repository_rule( "legacy", ], ), - "build_extra_args": attr.string_list(), - "build_config": attr.label(default = "@bazel_gazelle_go_repository_config//:WORKSPACE"), - "build_directives": attr.string_list(default = []), + "build_extra_args": attr.string_list( + doc = "A list of additional command line arguments to pass to Gazelle when generating build files.", + ), + "build_config": attr.label( + default = "@bazel_gazelle_go_repository_config//:WORKSPACE", + doc = """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. + + `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.""", + ), + "build_directives": attr.string_list( + default = [], + doc = """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.""", + ), # Patches to apply after running gazelle. - "patches": attr.label_list(), - "patch_tool": attr.string(default = "patch"), - "patch_args": attr.string_list(default = ["-p0"]), - "patch_cmds": attr.string_list(default = []), + "patches": attr.label_list( + doc = "A list of patches to apply to the repository after gazelle runs.", + ), + "patch_tool": attr.string( + default = "patch", + doc = "The patch tool used to apply `patches`.", + ), + "patch_args": attr.string_list( + default = ["-p0"], + doc = "Arguments passed to the patch tool when applying patches.", + ), + "patch_cmds": attr.string_list( + default = [], + doc = "Commands to run in the repository after patches are applied.", + ), }, ) """See repository.rst#go-repository for full documentation.""" diff --git a/internal/list_repository_tools_srcs.go b/internal/list_repository_tools_srcs.go index 656681e8e..ac124ec6d 100644 --- a/internal/list_repository_tools_srcs.go +++ b/internal/list_repository_tools_srcs.go @@ -61,7 +61,7 @@ func main() { return err } base := filepath.Base(path) - if base == "vendor" || base == "third_party" || base == "testdata" { + if base == "docs" || base == "vendor" || base == "third_party" || base == "testdata" { return filepath.SkipDir } if !info.IsDir() && diff --git a/internal/overlay_repository.bzl b/internal/overlay_repository.bzl index 3cf470a54..bc0e1f750 100644 --- a/internal/overlay_repository.bzl +++ b/internal/overlay_repository.bzl @@ -25,12 +25,67 @@ def _http_archive_impl(ctx): http_archive = repository_rule( implementation = _http_archive_impl, + doc = """ +**NOTE:** `http_archive` is deprecated in favor of the rule of the same name +in [@bazel_tools//tools/build_defs/repo:http.bzl]. + +`http_archive` downloads a project over HTTP(S). It has the same features as +the [native http_archive rule], but it also allows you to copy a set of files +into the repository after download. This is particularly useful for placing +pre-generated build files. + +**Example** + +```starlark +load("@bazel_gazelle//:deps.bzl", "http_archive") + +http_archive( + name = "com_github_pkg_errors", + urls = ["https://codeload.github.com/pkg/errors/zip/816c9085562cd7ee03e7f8188a1cfd942858cded"], + strip_prefix = "errors-816c9085562cd7ee03e7f8188a1cfd942858cded", + type = "zip", + overlay = { + "@my_repo//third_party:com_github_pkg_errors/BUILD.bazel.in" : "BUILD.bazel", + }, +) +``` +""", attrs = { - "urls": attr.string_list(), - "sha256": attr.string(), - "strip_prefix": attr.string(), - "type": attr.string(), - "overlay": attr.label_keyed_string_dict(allow_files = True), + "urls": attr.string_list( + doc = """A list of HTTP(S) URLs where the project can be downloaded. Bazel will + attempt to download the first URL; the others are mirrors.""", + ), + "sha256": attr.string( + doc = """The SHA-256 sum of the downloaded archive. When set, Bazel will verify the + archive against this sum before extracting it. + + **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.""", + ), + "strip_prefix": attr.string( + doc = "A directory prefix to strip. See [http_archive.strip_prefix].", + ), + "type": attr.string( + doc = """One of `"zip"`, `"tar.gz"`, `"tgz"`, `"tar.bz2"`, `"tar.xz"`. + + The file format of the repository archive. This is normally inferred from + the downloaded file name.""", + + ), + "overlay": attr.label_keyed_string_dict( + allow_files = True, + doc = """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. + + It's convenient to store the overlay dictionaries for all repositories in + a separate .bzl file. See Gazelle's `manifest.bzl`_ for an example.""" + ), }, ) # TODO(jayconrod): add strip_count to remove a number of unnamed @@ -56,11 +111,53 @@ def _git_repository_impl(ctx): git_repository = repository_rule( implementation = _git_repository_impl, + doc = """ +**NOTE:** `git_repository` is deprecated in favor of the rule of the same name +in [@bazel_tools//tools/build_defs/repo:git.bzl]. + +`git_repository` downloads a project with git. It has the same features as the +[native git_repository rule], but it also allows you to copy a set of files +into the repository after download. This is particularly useful for placing +pre-generated build files. + +**Example** + +```starlark +load("@bazel_gazelle//:deps.bzl", "git_repository") + +git_repository( + name = "com_github_pkg_errors", + remote = "https://github.com/pkg/errors", + commit = "816c9085562cd7ee03e7f8188a1cfd942858cded", + overlay = { + "@my_repo//third_party:com_github_pkg_errors/BUILD.bazel.in" : "BUILD.bazel", + }, +) +``` +""", attrs = { - "commit": attr.string(), - "remote": attr.string(mandatory = True), - "tag": attr.string(), - "overlay": attr.label_keyed_string_dict(allow_files = True), + "commit": attr.string( + doc = "The git commit to check out. Either `commit` or `tag` may be specified.", + ), + "remote": attr.string( + doc = "The remote repository to download.", + mandatory = True, + ), + "tag": attr.string( + doc = "The git tag to check out. Either `commit` or `tag` may be specified.", + ), + "overlay": attr.label_keyed_string_dict( + allow_files = True, + doc = """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. + +It's convenient to store the overlay dictionaries for all repositories in +a separate .bzl file. See Gazelle's `manifest.bzl`_ for an example.""", + ), }, ) diff --git a/internal/repository_docs.bzl b/internal/repository_docs.bzl new file mode 100644 index 000000000..4d4a18236 --- /dev/null +++ b/internal/repository_docs.bzl @@ -0,0 +1,64 @@ +# Module used by stardoc to generate API documentation. +# Not meant for use by bazel-gazelle users. +""" +Repository rules +================ + +Repository rules are Bazel rules that can be used in WORKSPACE files to import +projects in external repositories. Repository rules may download projects +and transform them by applying patches or generating build files. + +The Gazelle repository provides three rules: + +* [`go_repository`](#go_repository) downloads a Go project using either `go mod download`, a + version control tool like `git`, or a direct HTTP download. It understands + Go import path redirection. If build files are not already present, it can + generate them with Gazelle. +* [`git_repository`](#git_repository) downloads a project with git. Unlike the native + `git_repository`, this rule allows you to specify an "overlay": a set of + files to be copied into the downloaded project. This may be used to add + pre-generated build files to a project that doesn't have them. +* [`http_archive`](#http_archive) downloads a project via HTTP. It also lets you specify + overlay files. + +**NOTE:** `git_repository` and `http_archive` are deprecated in favor of the +rules of the same name in [@bazel_tools//tools/build_defs/repo:git.bzl] and +[@bazel_tools//tools/build_defs/repo:http.bzl]. + +Repository rules can be loaded and used in WORKSPACE like this: + +```starlark +load("@bazel_gazelle//:deps.bzl", "go_repository") + +go_repository( + name = "com_github_pkg_errors", + commit = "816c9085562cd7ee03e7f8188a1cfd942858cded", + importpath = "github.com/pkg/errors", +) +``` + +Gazelle can add and update some of these rules automatically using the +`update-repos` command. For example, the rule above can be added with: + +```shell +$ gazelle update-repos github.com/pkg/errors +``` + +[http_archive.strip_prefix]: https://docs.bazel.build/versions/master/be/workspace.html#http_archive.strip_prefix +[native git_repository rule]: https://docs.bazel.build/versions/master/be/workspace.html#git_repository +[native http_archive rule]: https://docs.bazel.build/versions/master/be/workspace.html#http_archive +[manifest.bzl]: third_party/manifest.bzl +[Directives]: /README.rst#directives +[@bazel_tools//tools/build_defs/repo:git.bzl]: https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/repo/git.bzl +[@bazel_tools//tools/build_defs/repo:http.bzl]: https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/repo/http.bzl +""" + +load("go_repository.bzl", _go_repository = "go_repository") +load("overlay_repository.bzl", + _http_archive = "http_archive", + _git_repository = "git_repository", +) + +go_repository = _go_repository +http_archive = _http_archive +git_repository = _git_repository diff --git a/repository.md b/repository.md new file mode 100644 index 000000000..bb8c952ff --- /dev/null +++ b/repository.md @@ -0,0 +1,248 @@ + + + +Repository rules +================ + +Repository rules are Bazel rules that can be used in WORKSPACE files to import +projects in external repositories. Repository rules may download projects +and transform them by applying patches or generating build files. + +The Gazelle repository provides three rules: + +* [`go_repository`](#go_repository) downloads a Go project using either `go mod download`, a + version control tool like `git`, or a direct HTTP download. It understands + Go import path redirection. If build files are not already present, it can + generate them with Gazelle. +* [`git_repository`](#git_repository) downloads a project with git. Unlike the native + `git_repository`, this rule allows you to specify an "overlay": a set of + files to be copied into the downloaded project. This may be used to add + pre-generated build files to a project that doesn't have them. +* [`http_archive`](#http_archive) downloads a project via HTTP. It also lets you specify + overlay files. + +**NOTE:** `git_repository` and `http_archive` are deprecated in favor of the +rules of the same name in [@bazel_tools//tools/build_defs/repo:git.bzl] and +[@bazel_tools//tools/build_defs/repo:http.bzl]. + +Repository rules can be loaded and used in WORKSPACE like this: + +```starlark +load("@bazel_gazelle//:deps.bzl", "go_repository") + +go_repository( + name = "com_github_pkg_errors", + commit = "816c9085562cd7ee03e7f8188a1cfd942858cded", + importpath = "github.com/pkg/errors", +) +``` + +Gazelle can add and update some of these rules automatically using the +`update-repos` command. For example, the rule above can be added with: + +```shell +$ gazelle update-repos github.com/pkg/errors +``` + +[http_archive.strip_prefix]: https://docs.bazel.build/versions/master/be/workspace.html#http_archive.strip_prefix +[native git_repository rule]: https://docs.bazel.build/versions/master/be/workspace.html#git_repository +[native http_archive rule]: https://docs.bazel.build/versions/master/be/workspace.html#http_archive +[manifest.bzl]: third_party/manifest.bzl +[Directives]: /README.rst#directives +[@bazel_tools//tools/build_defs/repo:git.bzl]: https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/repo/git.bzl +[@bazel_tools//tools/build_defs/repo:http.bzl]: https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/repo/http.bzl + + + + +## git_repository + +
+git_repository(name, commit, overlay, remote, repo_mapping, tag)
+
+ + +**NOTE:** `git_repository` is deprecated in favor of the rule of the same name +in [@bazel_tools//tools/build_defs/repo:git.bzl]. + +`git_repository` downloads a project with git. It has the same features as the +[native git_repository rule], but it also allows you to copy a set of files +into the repository after download. This is particularly useful for placing +pre-generated build files. + +**Example** + +```starlark +load("@bazel_gazelle//:deps.bzl", "git_repository") + +git_repository( + name = "com_github_pkg_errors", + remote = "https://github.com/pkg/errors", + commit = "816c9085562cd7ee03e7f8188a1cfd942858cded", + overlay = { + "@my_repo//third_party:com_github_pkg_errors/BUILD.bazel.in" : "BUILD.bazel", + }, +) +``` + + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this repository. | Name | required | | +| commit | The git commit to check out. Either commit or tag may be specified. | String | optional | "" | +| 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.

It's convenient to store the overlay dictionaries for all repositories in a separate .bzl file. See Gazelle's manifest.bzl_ for an example. | Dictionary: Label -> String | optional | {} | +| remote | The remote repository to download. | String | required | | +| repo_mapping | A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<p>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). | Dictionary: String -> String | required | | +| tag | The git tag to check out. Either commit or tag may be specified. | String | optional | "" | + + + + +## go_repository + +
+go_repository(name, build_config, build_directives, build_external, build_extra_args,
+              build_file_generation, build_file_name, build_file_proto_mode, build_naming_convention,
+              build_tags, canonical_id, commit, importpath, patch_args, patch_cmds, patch_tool,
+              patches, remote, replace, repo_mapping, sha256, strip_prefix, sum, tag, type, urls, vcs,
+              version)
+
+ + +`go_repository` downloads a Go project and generates build files with Gazelle +if they are not already present. This is the simplest way to depend on +external Go projects. + +When `go_repository` is in module mode, it saves downloaded modules in a shared, +internal cache within Bazel's cache. It may be cleared with `bazel clean --expunge`. +By setting the environment variable `GO_REPOSITORY_USE_HOST_CACHE=1`, you can +force `go_repository` to use the module cache on the host system in the location +returned by `go env GOPATH`. + +**Example** + +```starlark +load("@bazel_gazelle//:deps.bzl", "go_repository") + +# Download using "go mod download" +go_repository( + name = "com_github_pkg_errors", + importpath = "github.com/pkg/errors", + sum = "h1:iURUrRGxPUNPdy5/HRSm+Yj6okJ6UtLINN0Q9M4+h3I=", + version = "v0.8.1", +) + +# Download automatically via git +go_repository( + name = "com_github_pkg_errors", + commit = "816c9085562cd7ee03e7f8188a1cfd942858cded", + importpath = "github.com/pkg/errors", +) + +# Download from git fork +go_repository( + name = "com_github_pkg_errors", + commit = "816c9085562cd7ee03e7f8188a1cfd942858cded", + importpath = "github.com/pkg/errors", + remote = "https://example.com/fork/github.com/pkg/errors", + vcs = "git", +) + +# Download via HTTP +go_repository( + name = "com_github_pkg_errors", + importpath = "github.com/pkg/errors", + urls = ["https://codeload.github.com/pkg/errors/zip/816c9085562cd7ee03e7f8188a1cfd942858cded"], + strip_prefix = "errors-816c9085562cd7ee03e7f8188a1cfd942858cded", + type = "zip", +) +``` + + + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this repository. | Name | required | | +| 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.

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. | Label | optional | @bazel_gazelle_go_repository_config//:WORKSPACE | +| 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 | [] | +| build_external | One of "external", "vendored".

This sets Gazelle's -external command line flag.

**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 | "" | +| build_extra_args | A list of additional command line arguments to pass to Gazelle when generating build files. | List of strings | optional | [] | +| build_file_generation | One of "auto", "on", "off".

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" | +| 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" | +| build_file_proto_mode | One of "default", "legacy", "disable", "disable_global" or "package".

This sets Gazelle's -proto command line flag. See Directives_ for more information on each mode. | String | optional | "" | +| 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.

See the gazelle:go_naming_convention directive in [Directives] for more information. | String | optional | "import_alias" | +| build_tags | This sets Gazelle's -build_tags command line flag. | List of strings | optional | [] | +| 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 | "" | +| 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 | "" | +| importpath | The Go import path that matches the root directory of this repository.

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.

If build files are generated for this repository, libraries will have their importpath attributes prefixed with this importpath string. | String | required | | +| patch_args | Arguments passed to the patch tool when applying patches. | List of strings | optional | ["-p0"] | +| patch_cmds | Commands to run in the repository after patches are applied. | List of strings | optional | [] | +| patch_tool | The patch tool used to apply patches. | String | optional | "patch" | +| patches | A list of patches to apply to the repository after gazelle runs. | List of labels | optional | [] | +| 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 | "" | +| replace | A replacement for the module named by importpath. The module named by replace will be downloaded at version and verified with sum.

NOTE: There is no go_repository equivalent to file path replace directives. Use local_repository instead. | String | optional | "" | +| repo_mapping | A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<p>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). | Dictionary: String -> String | required | | +| 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.

**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 | "" | +| 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 | "" | +| 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.

A value for sum may be found in the go.sum file or by running go mod download -json <module>@<version>. | String | optional | "" | +| 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 | "" | +| type | One of "zip", "tar.gz", "tgz", "tar.bz2", "tar.xz".

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 | "" | +| 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 | [] | +| vcs | One of "git", "hg", "svn", "bzr".

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 | "" | +| 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 | "" | + + + + +## http_archive + +
+http_archive(name, overlay, repo_mapping, sha256, strip_prefix, type, urls)
+
+ + +**NOTE:** `http_archive` is deprecated in favor of the rule of the same name +in [@bazel_tools//tools/build_defs/repo:http.bzl]. + +`http_archive` downloads a project over HTTP(S). It has the same features as +the [native http_archive rule], but it also allows you to copy a set of files +into the repository after download. This is particularly useful for placing +pre-generated build files. + +**Example** + +```starlark +load("@bazel_gazelle//:deps.bzl", "http_archive") + +http_archive( + name = "com_github_pkg_errors", + urls = ["https://codeload.github.com/pkg/errors/zip/816c9085562cd7ee03e7f8188a1cfd942858cded"], + strip_prefix = "errors-816c9085562cd7ee03e7f8188a1cfd942858cded", + type = "zip", + overlay = { + "@my_repo//third_party:com_github_pkg_errors/BUILD.bazel.in" : "BUILD.bazel", + }, +) +``` + + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this repository. | Name | required | | +| 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.

It's convenient to store the overlay dictionaries for all repositories in a separate .bzl file. See Gazelle's manifest.bzl_ for an example. | Dictionary: Label -> String | optional | {} | +| repo_mapping | A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<p>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). | Dictionary: String -> String | required | | +| sha256 | The SHA-256 sum of the downloaded archive. When set, Bazel will verify the archive against this sum before extracting it.

**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 | "" | +| strip_prefix | A directory prefix to strip. See [http_archive.strip_prefix]. | String | optional | "" | +| type | One of "zip", "tar.gz", "tgz", "tar.bz2", "tar.xz".

The file format of the repository archive. This is normally inferred from the downloaded file name. | String | optional | "" | +| 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 | [] | + + diff --git a/repository.rst b/repository.rst index df7580c30..fd9c58608 100644 --- a/repository.rst +++ b/repository.rst @@ -1,442 +1,4 @@ Repository rules ================ -.. _http_archive.strip_prefix: https://docs.bazel.build/versions/master/be/workspace.html#http_archive.strip_prefix -.. _native git_repository rule: https://docs.bazel.build/versions/master/be/workspace.html#git_repository -.. _native http_archive rule: https://docs.bazel.build/versions/master/be/workspace.html#http_archive -.. _manifest.bzl: third_party/manifest.bzl -.. _Directives: /README.rst#directives -.. _`@bazel_tools//tools/build_defs/repo:git.bzl`: https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/repo/git.bzl -.. _`@bazel_tools//tools/build_defs/repo:http.bzl`: https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/repo/http.bzl - -.. role:: param(kbd) -.. role:: type(emphasis) -.. role:: value(code) -.. |mandatory| replace:: **mandatory value** - -Repository rules are Bazel rules that can be used in WORKSPACE files to import -projects in external repositories. Repository rules may download projects -and transform them by applying patches or generating build files. - -The Gazelle repository provides three rules: - -* `go_repository`_ downloads a Go project using either ``go mod download``, a - version control tool like ``git``, or a direct HTTP download. It understands - Go import path redirection. If build files are not already present, it can - generate them with Gazelle. -* `git_repository`_ downloads a project with git. Unlike the native - ``git_repository``, this rule allows you to specify an "overlay": a set of - files to be copied into the downloaded project. This may be used to add - pre-generated build files to a project that doesn't have them. -* `http_archive`_ downloads a project via HTTP. It also lets you specify - overlay files. - -**NOTE:** ``git_repository`` and ``http_archive`` are deprecated in favor of the -rules of the same name in `@bazel_tools//tools/build_defs/repo:git.bzl`_ and -`@bazel_tools//tools/build_defs/repo:http.bzl`_. - -Repository rules can be loaded and used in WORKSPACE like this: - -.. code:: bzl - - load("@bazel_gazelle//:deps.bzl", "go_repository") - - go_repository( - name = "com_github_pkg_errors", - commit = "816c9085562cd7ee03e7f8188a1cfd942858cded", - importpath = "github.com/pkg/errors", - ) - -Gazelle can add and update some of these rules automatically using the -``update-repos`` command. For example, the rule above can be added with: - -.. code:: - - $ gazelle update-repos github.com/pkg/errors - -go_repository -------------- - -``go_repository`` downloads a Go project and generates build files with Gazelle -if they are not already present. This is the simplest way to depend on -external Go projects. - -When ``go_repository`` is in module mode, it saves downloaded modules in a shared, -internal cache within Bazel's cache. It may be cleared with ``bazel clean --expunge``. -By setting the environment variable ``GO_REPOSITORY_USE_HOST_CACHE=1``, you can -force ``go_repository`` to use the module cache on the host system in the location -returned by ``go env GOPATH``. - -**Example** - -.. code:: bzl - - load("@bazel_gazelle//:deps.bzl", "go_repository") - - # Download using "go mod download" - go_repository( - name = "com_github_pkg_errors", - importpath = "github.com/pkg/errors", - sum = "h1:iURUrRGxPUNPdy5/HRSm+Yj6okJ6UtLINN0Q9M4+h3I=", - version = "v0.8.1", - ) - - # Download automatically via git - go_repository( - name = "com_github_pkg_errors", - commit = "816c9085562cd7ee03e7f8188a1cfd942858cded", - importpath = "github.com/pkg/errors", - ) - - # Download from git fork - go_repository( - name = "com_github_pkg_errors", - commit = "816c9085562cd7ee03e7f8188a1cfd942858cded", - importpath = "github.com/pkg/errors", - remote = "https://example.com/fork/github.com/pkg/errors", - vcs = "git", - ) - - # Download via HTTP - go_repository( - name = "com_github_pkg_errors", - importpath = "github.com/pkg/errors", - urls = ["https://codeload.github.com/pkg/errors/zip/816c9085562cd7ee03e7f8188a1cfd942858cded"], - strip_prefix = "errors-816c9085562cd7ee03e7f8188a1cfd942858cded", - type = "zip", - ) - -**Attributes** - -+------------------------------------+----------------------+---------------------------------------------------------------+ -| **Name** | **Type** | **Default value** | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`name` | :type:`string` | |mandatory| | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| A unique name for this rule. This should usually be the Java-package-style | -| name of the URL, with underscores as separators, for example, | -| ``com_github_example_project``. | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`importpath` | :type:`string` | |mandatory| | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| The Go import path that matches the root directory of this repository. 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. | -| | -| If build files are generated for this repository, libraries will have their | -| ``importpath`` attributes prefixed with this ``importpath`` string. | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`version` | :type:`string` | :value:`""` | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| 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. | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`sum` | :type:`string` | :value:`""` | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| 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. | -| | -| A value for ``sum`` may be found in the ``go.sum`` file or by running | -| ``go mod download -json @``. | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`build_naming_convention` | :type:`string` | :value:`""` | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| 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``. | -| | -| See the ``gazelle:go_naming_convention`` directive in Directives_ for more information. | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`replace` | :type:`string` | :value:`""` | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| A replacement for the module named by ``importpath``. The module named by | -| ``replace`` will be downloaded at ``version`` and verified with ``sum``. | -| | -| NOTE: There is no ``go_repository`` equivalent to file path ``replace`` | -| directives. Use ``local_repository`` instead. | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`commit` | :type:`string` | :value:`""` | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| 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. | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`tag` | :type:`string` | :value:`""` | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| 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. | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`vcs` | :type:`string` | :value:`""` | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| One of ``"git"``, ``"hg"``, ``"svn"``, ``"bzr"``. | -| | -| 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. | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`remote` | :type:`string` | :value:`""` | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| 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. | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`urls` | :type:`string list` | :value:`[]` | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| 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. | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`strip_prefix` | :type:`string` | :value:`""` | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| If the repository is downloaded via HTTP (``urls`` is set), this is a | -| directory prefix to strip. See `http_archive.strip_prefix`_. | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`type` | :type:`string` | :value:`""` | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| One of ``"zip"``, ``"tar.gz"``, ``"tgz"``, ``"tar.bz2"``, ``"tar.xz"``. | -| | -| 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. | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`sha256` | :type:`string` | :value:`""` | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| 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. | -| | -| **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. | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`canonical_id` | :type:`string` | :value:`""` | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| 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. | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`build_file_generation` | :type:`string` | :value:`"auto"` | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| One of ``"auto"``, ``"on"``, ``"off"``. | -| | -| 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. | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`build_config` | :type:`label` | :value:`@bazel_gazelle_go_repository_config//:WORKSPACE` | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| 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. | -| | -| ``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. | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`build_file_name` | :type:`string` | :value:`BUILD.bazel,BUILD` | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| 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. | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`build_external` | :type:`string` | :value:`""` | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| One of ``"external"``, ``"vendored"``. | -| | -| This sets Gazelle's ``-external`` command line flag. | -| | -| **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. | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`build_tags` | :type:`string list` | :value:`[]` | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| This sets Gazelle's ``-build_tags`` command line flag. | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`build_file_proto_mode` | :type:`string` | :value:`""` | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| One of ``"default"``, ``"legacy"``, ``"disable"``, ``"disable_global"`` or | -| ``"package"``. | -| | -| This sets Gazelle's ``-proto`` command line flag. See Directives_ for more | -| information on each mode. | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`build_extra_args` | :type:`string list` | :value:`[]` | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| A list of additional command line arguments to pass to Gazelle when | -| generating build files. | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`build_directives` | :type:`string list` | :value:`[]` | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| 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. | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`patches` | :type:`label list` | :value:`[]` | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| A list of patches to apply to the repository after gazelle runs. | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`patch_tool` | :type:`string` | :value:`"patch"` | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| The patch tool used to apply ``patches``. | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`patch_args` | :type:`string list` | :value:`["-p0"]` | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| Arguments passed to the patch tool when applying patches. | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| :param:`patch_cmds` | :type:`string list` | :value:`[]` | -+------------------------------------+----------------------+---------------------------------------------------------------+ -| Commands to run in the repository after patches are applied. | -+------------------------------------+----------------------+---------------------------------------------------------------+ - -git_repository --------------- - -**NOTE:** ``git_repository`` is deprecated in favor of the rule of the same name -in `@bazel_tools//tools/build_defs/repo:git.bzl`_. - -``git_repository`` downloads a project with git. It has the same features as the -`native git_repository rule`_, but it also allows you to copy a set of files -into the repository after download. This is particularly useful for placing -pre-generated build files. - -**Example** - -.. code:: bzl - - load("@bazel_gazelle//:deps.bzl", "git_repository") - - git_repository( - name = "com_github_pkg_errors", - remote = "https://github.com/pkg/errors", - commit = "816c9085562cd7ee03e7f8188a1cfd942858cded", - overlay = { - "@my_repo//third_party:com_github_pkg_errors/BUILD.bazel.in" : "BUILD.bazel", - }, - ) - -**Attributes** - -+--------------------------------+----------------------+-------------------------------------------------+ -| **Name** | **Type** | **Default value** | -+--------------------------------+----------------------+-------------------------------------------------+ -| :param:`name` | :type:`string` | |mandatory| | -+--------------------------------+----------------------+-------------------------------------------------+ -| A unique name for this rule. This should usually be the Java-package-style | -| name of the URL, with underscores as separators, for example, | -| ``com_github_example_project``. | -+--------------------------------+----------------------+-------------------------------------------------+ -| :param:`remote` | :type:`string` | |mandatory| | -+--------------------------------+----------------------+-------------------------------------------------+ -| The remote repository to download. | -+--------------------------------+----------------------+-------------------------------------------------+ -| :param:`commit` | :type:`string` | :value:`""` | -+--------------------------------+----------------------+-------------------------------------------------+ -| The git commit to check out. Either ``commit`` or ``tag`` may be specified. | -+--------------------------------+----------------------+-------------------------------------------------+ -| :param:`tag` | :type:`tag` | :value:`""` | -+--------------------------------+----------------------+-------------------------------------------------+ -| The git tag to check out. Either ``commit`` or ``tag`` may be specified. | -+--------------------------------+----------------------+-------------------------------------------------+ -| :param:`overlay` | :type:`dict` | :value:`{}` | -+--------------------------------+----------------------+-------------------------------------------------+ -| 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. | -| | -| It's convenient to store the overlay dictionaries for all repositories in | -| a separate .bzl file. See Gazelle's `manifest.bzl`_ for an example. | -+--------------------------------+----------------------+-------------------------------------------------+ - -http_archive ------------- - -**NOTE:** ``http_archive`` is deprecated in favor of the rule of the same name -in `@bazel_tools//tools/build_defs/repo:http.bzl`_. - -``http_archive`` downloads a project over HTTP(S). It has the same features as -the `native http_archive rule`_, but it also allows you to copy a set of files -into the repository after download. This is particularly useful for placing -pre-generated build files. - -**Example** - -.. code:: bzl - - load("@bazel_gazelle//:deps.bzl", "http_archive") - - http_archive( - name = "com_github_pkg_errors", - urls = ["https://codeload.github.com/pkg/errors/zip/816c9085562cd7ee03e7f8188a1cfd942858cded"], - strip_prefix = "errors-816c9085562cd7ee03e7f8188a1cfd942858cded", - type = "zip", - overlay = { - "@my_repo//third_party:com_github_pkg_errors/BUILD.bazel.in" : "BUILD.bazel", - }, - ) - -**Attributes** - -+--------------------------------+----------------------+-------------------------------------------------+ -| **Name** | **Type** | **Default value** | -+--------------------------------+----------------------+-------------------------------------------------+ -| :param:`name` | :type:`string` | |mandatory| | -+--------------------------------+----------------------+-------------------------------------------------+ -| A unique name for this rule. This should usually be the Java-package-style | -| name of the URL, with underscores as separators, for example, | -| ``com_github_example_project``. | -+--------------------------------+----------------------+-------------------------------------------------+ -| :param:`urls` | :type:`string list` | |mandatory| | -+--------------------------------+----------------------+-------------------------------------------------+ -| A list of HTTP(S) URLs where the project can be downloaded. Bazel will | -| attempt to download the first URL; the others are mirrors. | -+--------------------------------+----------------------+-------------------------------------------------+ -| :param:`sha256` | :type:`string` | :value:`""` | -+--------------------------------+----------------------+-------------------------------------------------+ -| The SHA-256 sum of the downloaded archive. When set, Bazel will verify the | -| archive against this sum before extracting it. | -| | -| **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. | -+--------------------------------+----------------------+-------------------------------------------------+ -| :param:`strip_prefix` | :type:`string` | :value:`""` | -+--------------------------------+----------------------+-------------------------------------------------+ -| A directory prefix to strip. See `http_archive.strip_prefix`_. | -+--------------------------------+----------------------+-------------------------------------------------+ -| :param:`type` | :type:`string` | :value:`""` | -+--------------------------------+----------------------+-------------------------------------------------+ -| One of ``"zip"``, ``"tar.gz"``, ``"tgz"``, ``"tar.bz2"``, ``"tar.xz"``. | -| | -| The file format of the repository archive. This is normally inferred from | -| the downloaded file name. | -+--------------------------------+----------------------+-------------------------------------------------+ -| :param:`overlay` | :type:`dict` | :value:`{}` | -+--------------------------------+----------------------+-------------------------------------------------+ -| 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. | -| | -| It's convenient to store the overlay dictionaries for all repositories in | -| a separate .bzl file. See Gazelle's `manifest.bzl`_ for an example. | -+--------------------------------+----------------------+-------------------------------------------------+ +`Moved to markdown <./repository.md>`_