workspace.rst

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.

Contents

• go_rules_dependencies
• go_repository
• Overriding dependencies

---

go_rules_dependencies

go_rules_dependencies is a macro that registers external dependencies needed by the Go and proto rules in rules_go.

When Bazel supports nested workspaces in the future, this macro may be redundant, but for now, projects that use rules_go should always call it from WORKSPACE. It takes no arguments and returns no results.

The list of dependencies declared by go_rules_dependencies 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.

• com_google_protobuf : github.com/google/protobuf
• com_github_golang_protobuf : github.com/golang/protobuf
• org_golang_google_genproto : google.golang.org/genproto (go_library rules with pre-generated .pb.go files)
• go_googleapis : google.golang.org/genproto (go_proto_library rules that generate code at build time)
• org_golang_google_grpc : google.golang.org/grpc
• org_golang_x_net : golang.org/x/net
• org_golang_x_text : golang.org/x/text
• org_golang_x_tools : golang.org/x/tools
• org_golang_x_sys: golang.org/x/sys

go_rules_dependencies won't override repositories that were declared earlier, so you can replace any of these repositories with a different version by declaring a repository rule with the same name before calling go_rules_dependencies.

You can find the full implementation in repositories.bzl.

See Overriding dependencies for examples of how to use alternative versions of these repositories.

go_repository

This rule has moved. See go_repository in the Gazelle repository.

Overriding dependencies

You can override a dependency declared in go_rules_dependencies by declaring a repository rule in WORKSPACE with the same name before the call to go_rules_dependencies.

For example, this is how you would override org_golang_x_sys.

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
    name = "io_bazel_rules_go",
    sha256 = "6776d68ebb897625dead17ae510eac3d5f6342367327875210df44dbe2aeeb19",
    urls = ["https://github.com/bazelbuild/rules_go/releases/download/0.17.1/rules_go-0.17.1.tar.gz"],
)

http_archive(
    name = "bazel_gazelle",
    sha256 = "3c681998538231a2d24d0c07ed5a7658cb72bfb5fd4bf9911157c0e9ac6a2687",
    urls = ["https://github.com/bazelbuild/bazel-gazelle/releases/download/0.17.0/bazel-gazelle-0.17.0.tar.gz"],
)

load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")

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

go_repository(
    name = "org_golang_x_sys",
    commit = "57f5ac02873b2752783ca8c3c763a20f911e4d89",
    importpath = "golang.org/x/sys",
)

go_rules_dependencies()

go_register_toolchains()

gazelle_dependencies()

In order to avoid a dependency on Gazelle, the repositories in go_rules_dependencies are declared with Bazel's git_repository and http_archive rules instead of go_repository. These rules accept a list of patches, so we provide pre-generated patches that are equivalent to running Gazelle. These patches are checked into the third_party directory with the suffix -gazelle.patch.

When upgrading these rules, you can use go_repository instead of using these patches. This will run Gazelle automatically when the repository is checked out. Note that some repositories require additional patches after running Gazelle. You can provide the additional patches to go_repository.

go_repository(
    name = "com_github_golang_protobuf",
    build_file_proto_mode = "disable_global",
    commit = "7011d38ac0d201eeddff4a4085a657c3da322d75",
    importpath = "github.com/golang/protobuf",
    patch_args = ["-p1"],
    patches = ["@io_bazel_rules_go//third_party:com_github_golang_protobuf-extras.patch"],
)