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. Thi name of the URL, with underscore com_github_example_project. s should usually be the s as separators, for ex

Java-package-style

ample,
importpath string mandatory value
The Go import path that matches neither urls nor remote the repository from this locatio If build files are generated, li with this string. the root directory of t are specified, go_rep n. This supports import braries will haveimp his repository. If ositorywill download path redirection. ortpath prefixed
commit string ""
If the repository is downloaded commit or revision to check out. commit and tag may not b
using a version control

With git, this would b

oth be set.

tool, this is the

e a sha1 commit id.
tag string ""
If the repository is downloaded named revision to check out. ``c using a version control ommitandtag`` may tool, this is the not both be set.
vcs string ""

One of "git", "hg", ``"s

The version control system to us but it may be necessary to set t be inferred. You must have the c

 vn","bzr". e. This is usually dete his whenremote`` is orresponding tool insta rmined automatically, set and the VCS cannot lled on your host.
remote string ""
The VCS location where the repos usually inferred from ``importpa from a private repository or a f itory should be downloa th`, but you can set ork. ded from. This is remote` to download
urls string list []
A list of HTTP(S) URLs where an downloaded. Bazel will attempt t are mirrors. archive containing the o download from the fir project can be st URL; the others
strip_prefix string ""
If the repository is downloaded directory prefix to strip. See ` via HTTP (urls is s http_archive.strip_pref et), this is a ix`_.
type string ""

One of "zip", "tar.gz",

If the repository is downloaded file format of the repository ar downloaded file name.

 "tgz", "tar.bz2"` via HTTP (urls`` is s chive. This is normally

, "tar.xz"`.

et), this is the

inferred from the
sha256 string ""

If the repository is downloaded SHA-256 sum of the downloaded ar against this sum before extracti

CAUTION: Do not use this wit demand, such as codeload.github. can cause differences in file or SHA-256 sums.

via HTTP (urls is s chive. When set, Bazel ng it.

h services that prepare com. Any minor change i der, alignment, and com

et), this is the will verify the archive

source archives on

n the server software pression that break
build_file_generation string "auto"

One of "auto", "on", ``"

Whether Gazelle should generate mode, Gazelle will run if there directory.

off"``.

build files in the repo is no build file in the
sitory. In "auto"

repository root
build_file_name string BUILD.bazel,BUILD
Comma-separated list of names Ga If a repository contains files n it may help to set this to ``"BU file systems. zelle will consider to amed build that are ILD.bazel"``, especiall be build files. n't related to Bazel, y on case-insensitive
build_external string ""
One of "external", "vendor This sets Gazelle's-external`

ed"``.

` command line flag.
build_tags string list []
This sets Gazelle's ``-build_tag s`` command line flag.
build_file_proto_mode string ""
One of "default", "legacy""package". This sets Gazelle's-proto`` c information on each mode.

,"disable","d

ommand line flag. See D

isable_global"`` or

irectives for more
build_extra_args string list []
A list of additional command lin generating build files. e arguments to pass to Gazelle when

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. Thi name of the URL, with underscore com_github_example_project. s should usually be the s as separators, for ex

Java-package-style

ample,
remote string mandatory value
The remote repository to downloa d.
commit string ""
The git commit to check out. Eit her 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 dictionary are Bazel labels that fully qualified labels (i.e., `` are interpreted in the checked o the WORKSPACE file. The values i where the overlay files should b

It's convenient to store the ove a separate .bzl file. See Gazell
downloaded repository.

point to the files to

@repo//pkg:name``) beca ut repository, not the n this dictionary are r e written.

rlay dictionaries for a e's manifest.bzl for

The keys in this copy. These must be use relative labels repository containing oot-relative paths

ll repositories in

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. Thi name of the URL, with underscore com_github_example_project. s should usually be the s as separators, for ex

Java-package-style

ample,
urls string list mandatory value
A list of HTTP(S) URLs where the attempt to download the first UR

project can be downloa

L; the others are mirro		 ded. Bazel will rs.
sha256 string ""

The SHA-256 sum of the downloade archive against this sum before

CAUTION: Do not use this wit demand, such as codeload.github. can cause differences in file or SHA-256 sums.

d archive. When set, Ba extracting it.

h services that prepare com. Any minor change i der, alignment, and com

zel will verify the

source archives on

n the server software pression that break
strip_prefix string ""
A directory prefix to strip. See `http_archive.strip_pr efix`_.
type string ""

One of "zip", "tar.gz",

The file format of the repositor the downloaded file name.

"tgz", `"tar.bz2"

y archive. This is norm

, "tar.xz"`.

ally inferred from
overlay dict {}

A set of files to copy into the dictionary are Bazel labels that fully qualified labels (i.e., `` are interpreted in the checked o the WORKSPACE file. The values i where the overlay files should b

It's convenient to store the ove a separate .bzl file. See Gazell
downloaded repository.

point to the files to

@repo//pkg:name``) beca ut repository, not the n this dictionary are r e written.

rlay dictionaries for a e's manifest.bzl for

The keys in this copy. These must be use relative labels repository containing oot-relative paths

ll repositories in

an example.