Skip to content

Latest commit

 

History

History
332 lines (294 loc) · 24.4 KB

repository.rst

File metadata and controls

332 lines (294 loc) · 24.4 KB
Raw

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 downloads a Go project over HTTP or using a version control tool like git. 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.

Repository rules can be loaded and used in WORKSPACE like this:

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:

$ 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.

Example

load("@bazel_gazelle//:deps.bzl", "go_repository")

# 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
name string mandatory value
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.
importpath string mandatory value
The Go import path that matches the root directory of this repository. If neither urls nor remote are specified, go_repository will download the repository from this location. This supports import path redirection. If build files are generated, libraries will have importpath prefixed with this string.
commit string ""
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 string ""
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 string ""

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.
remote string ""
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.
urls string list []
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 string ""
If the repository is downloaded via HTTP (urls is set), this is a directory prefix to strip. See http_archive.strip_prefix.
type string ""

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 string ""

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.
build_file_generation string "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.
build_file_name string 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.
build_external string ""

One of "external", "vendored".

This sets Gazelle's -external command line flag.
build_tags string list []
This sets Gazelle's -build_tags command line flag.
build_file_proto_mode string ""

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.
build_extra_args string list []
A list of additional command line arguments to pass to Gazelle when generating build files.

git_repository

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

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
name string mandatory value
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.
remote string mandatory value
The remote repository to download.
commit string ""
The git commit to check out. Either commit or tag may be specified.
tag tag ""
The git tag to check out. Either commit or tag may be specified.
overlay dict {}

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

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

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
name string mandatory value
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.
urls string list mandatory value
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 string ""

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 string ""
A directory prefix to strip. See http_archive.strip_prefix.
type string ""

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 dict {}

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.