Skip to content

Latest commit

 

History

History
252 lines (207 loc) · 15 KB

workspace.rst

File metadata and controls

252 lines (207 loc) · 15 KB
Raw

Go workspace rules

Workspace rules are either repository rules, or macros that are intended to be used from the WORKSPACE file.

See also the toolchains rules, which contains the go_register_toolchains workspace rule.

There is also the deprecated new_go_repository and go_repositories which you should no longer use (we will be deleting them soon).

Contents

go_rules_dependencies

Registers external dependencies needed by rules_go, including the Go toolchain and standard library. All the other workspace rules and build rules assume that this rule is placed in the WORKSPACE.

When nested workspaces arrive this will be redundant, but for now you should always call this macro from your WORKSPACE.

The macro takes no arguments and returns no results. You put

go_rules_dependencies()

in the bottom of your WORKSPACE file and forget about it.

The list of dependencies it adds is quite long, there are a few listed below that you are more likely to want to know about and override, but it is by no means a complete list.

It won't override repositories that were declared earlier, so you can replace any of these with a different version by declaring it before calling this macro, which is why we recommend you should put the call at the bottom of your WORKSPACE. For example:

go_repository(
    name = "org_golang_x_net",
    commit = "0744d001aa8470aaa53df28d32e5ceeb8af9bd70",
    importpath = "golang.org/x/net",
)

go_rules_dependencies()

would cause the go rules to use the specified version of x/net.

go_repository

Fetches a remote repository of a Go project, and generates BUILD.bazel files if they are not already present. In vcs mode, it recognizes importpath redirection.

The importpath must always be specified, it is used as the root import path for libraries in the repository.

The repository should be fetched either using a VCS (commit or tag) or a source archive (urls).

In the future we expect this to be replaced by normal http_archive or git_repository rules, once gazelle fully supports flat build files.

Name Type Default value
name string mandatory value
A unique name for this external dependency.
importpath string mandatory value
The root import path for libraries in the repository.
commit string ""

The commit hash to checkout in the repository.

Exactly one of urls, commit or tag must be specified.
tag string ""

The tag to checkout in the repository.

Exactly one of urls, commit or tag must be specified.
vcs string ""

The version control system to use for fetching the repository. Useful for disabling importpath redirection if necessary.

May be "git", "hg", "svn", or "bzr".

Only valid if remote is set.
remote string ""

The URI of the target remote repository, if this cannot be determined from the value of importpath.

Only valid if one of commit or tag is set.
urls string None

URLs for one or more source code archives.

Exactly one of urls, commit or tag must be specified.

See http_archive for more details.
strip_prefix string ""

The internal path prefix to strip when the archive is extracted.

Only valid if urls is set.

See http_archive for more details.
type string ""

The type of the archive, only needed if it cannot be inferred from the file extension.

Only valid if urls is set.

See http_archive for more details.
sha256 string ""

The expected SHA-256 hash of the file downloaded.

Only valid if urls is set.

See http_archive for more details.
build_file_name string "BUILD.bazel,BUILD"
The name to use for the generated build files. Defaults to "BUILD.bazel".
build_file_generation string "auto"

Used to force build file generation.

  • "off" : do not generate build files.
  • "on" : always run gazelle, even if build files are already present.
  • "auto" : run gazelle only if there is no root build file.
build_tags string_list ""
The set of tags to pass to gazelle when generating build files.
build_file_proto_mode string default

How Gazelle should generate proto rules.

  • "default" : generate proto_library and go_proto_library rules, ignore .pb.go files.
  • "disable" : ignore .proto files. Treat .pb.go files as normal sources.
  • "legacy" : generate filegroup rules for .proto files.

Example

The rule below fetches a repository with Git. Import path redirection is used to automatically determine the true location of the repository.

load("@io_bazel_rules_go//go:def.bzl", "go_repository")

go_repository(
    name = "org_golang_x_tools",
    importpath = "golang.org/x/tools",
    commit = "663269851cdddc898f963782f74ea574bcd5c814",
)

The rule below fetches a repository archive with HTTP. GitHub provides HTTP archives for all repositories. It's generally faster to fetch these than to checkout a repository with Git, but the strip_prefix part can break if the repository is renamed.

load("@io_bazel_rules_go//go:def.bzl", "go_repository")

go_repository(
    name = "org_golang_x_tools",
    importpath = "golang.org/x/tools",
    urls = ["https://codeload.github.com/golang/tools/zip/663269851cdddc898f963782f74ea574bcd5c814"],
    strip_prefix = "tools-663269851cdddc898f963782f74ea574bcd5c814",
    type = "zip",
)

The following fetches the same package, but using git without import redirection. This is also the same method you would use for private git repositories.

load("@io_bazel_rules_go//go:def.bzl", "go_repository")

go_repository(
    name = "org_golang_x_tools",
    importpath = "golang.org/x/tools",
    remote = "[email protected]:golang/tools.git",
    vcs = "git",
    commit = "663269851cdddc898f963782f74ea574bcd5c814",
)