1Go workspace rules 2================== 3 4.. Links to other sites and pages 5.. _gazelle: tools/gazelle/README.rst 6.. _github.com/bazelbuild/bazel-skylib: https://github.com/bazelbuild/bazel-skylib 7.. _github.com/gogo/protobuf: https://github.com/gogo/protobuf 8.. _github.com/golang/protobuf: https://github.com/golang/protobuf/ 9.. _github.com/google/protobuf: https://github.com/google/protobuf/ 10.. _github.com/googleapis/googleapis: https://github.com/googleapis/googleapis 11.. _github.com/mwitkow/go-proto-validators: https://github.com/mwitkow/go-proto-validators 12.. _golang.org/x/net: https://github.com/golang/net/ 13.. _golang.org/x/sys: https://github.com/golang/sys/ 14.. _golang.org/x/text: https://github.com/golang/text/ 15.. _golang.org/x/tools: https://github.com/golang/tools/ 16.. _google.golang.org/genproto: https://github.com/google/go-genproto 17.. _google.golang.org/grpc: https://github.com/grpc/grpc-go 18.. _http_archive: https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/repo/http.bzl 19.. _nested workspaces: https://bazel.build/designs/2016/09/19/recursive-ws-parsing.html 20.. _nogo: nogo.rst#nogo 21.. _normal go logic: https://golang.org/cmd/go/#hdr-Remote_import_paths 22.. _repositories.bzl: https://github.com/bazelbuild/rules_go/blob/master/go/private/repositories.bzl 23.. _rules_proto: https://github.com/bazelbuild/rules_proto 24.. _third_party: https://github.com/bazelbuild/rules_go/tree/master/third_party 25.. _toolchains: toolchains.rst 26 27.. Go rules 28.. _go_library: /docs/go/core/rules.md#go_library 29.. _go_proto_library: https://github.com/bazelbuild/rules_go/blob/master/proto/core.rst#go-proto-library 30.. _go_register_toolchains: toolchains.rst#go_register_toolchains 31.. _go_repository: https://github.com/bazelbuild/bazel-gazelle/blob/master/repository.md#go_repository 32.. _go_toolchain: toolchains.rst#go_toolchain 33 34.. Other rules 35.. _git_repository: https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/repo/git.bzl 36.. _proto_library: https://github.com/bazelbuild/rules_proto 37 38.. Issues 39.. _#1986: https://github.com/bazelbuild/rules_go/issues/1986 40 41.. role:: param(kbd) 42.. role:: type(emphasis) 43.. role:: value(code) 44.. |mandatory| replace:: **mandatory value** 45 46This document describes workspace rules, functions, and dependencies intended 47to be used in the ``WORKSPACE`` file.a 48 49See also the `toolchains`_ for information on `go_register_toolchains`_ and 50other rules used to download and register toolchains. 51 52Contents 53-------- 54 55* `go_rules_dependencies`_ 56* `Proto dependencies`_ 57* `gRPC dependencies`_ 58* `Overriding dependencies`_ 59 60 61go_rules_dependencies 62--------------------- 63 64``go_rules_dependencies`` is a function that registers external dependencies 65needed by the Go rules. Projects that use rules_go should *always* call it from 66WORKSPACE. It may be called before or after other workspace rules. 67 68See `Overriding dependencies`_ for instructions on using a different version 69of one of the repositories below. 70 71``go_rules_dependencies`` declares the repositories in the table below. 72It also declares some internal repositories not described here. 73 74+-------------------------------------------------+-------------------------------------------+ 75| **Name** | **Path** | 76+-------------------------------------------------+-------------------------------------------+ 77| :value:`bazel_skylib` | `github.com/bazelbuild/bazel-skylib`_ | 78+-------------------------------------------------+-------------------------------------------+ 79| A library of useful Starlark functions, used in the implementation | 80| of rules_go. | 81+-------------------------------------------------+-------------------------------------------+ 82| :value:`org_golang_x_tools` | `golang.org/x/tools`_ | 83+-------------------------------------------------+-------------------------------------------+ 84| The Go tools module. Provides the analysis framework that nogo_ is based on. | 85| Also provides other package loading and testing infrastructure. | 86+-------------------------------------------------+-------------------------------------------+ 87| :value:`com_github_golang_protobuf` | `github.com/golang/protobuf`_ | 88+-------------------------------------------------+-------------------------------------------+ 89| The Go protobuf plugin and runtime. When overriding this, make sure to use | 90| ``@io_bazel_rules_go//third_party:com_github_golang_protobuf-extras.patch``. | 91| This is needed to support both pre-generated and dynamically generated | 92| proto libraries. | 93+-------------------------------------------------+-------------------------------------------+ 94| :value:`com_github_mwitkow_go_proto_validators` | `github.com/mwitkow/go-proto-validators`_ | 95+-------------------------------------------------+-------------------------------------------+ 96| Legacy definition for proto plugin. Ideally ``go_rules_dependencies`` should | 97| not provide this. | 98+-------------------------------------------------+-------------------------------------------+ 99| :value:`com_github_gogo_protobuf` | `github.com/gogo/protobuf`_ | 100+-------------------------------------------------+-------------------------------------------+ 101| Legacy definition for proto plugins. Ideally ``go_rules_dependencies`` should | 102| not provide this. | 103+-------------------------------------------------+-------------------------------------------+ 104| :value:`org_golang_google_genproto` | `google.golang.org/genproto`_ | 105+-------------------------------------------------+-------------------------------------------+ 106| Pre-generated proto libraries for gRPC and Google APIs. Ideally, | 107| ``go_rules_dependencies`` should provide this, but it doesn't change often, | 108| and many things break without it. | 109+-------------------------------------------------+-------------------------------------------+ 110| :value:`go_googleapis` | `github.com/googleapis/googleapis`_ | 111+-------------------------------------------------+-------------------------------------------+ 112| Like :value:`org_golang_google_genproto` but provides ``go_proto_library`` | 113| targets instead of ``go_library``. Ideally we should use | 114| ``com_google_googleapis``, but Gazelle still resolves imports to this repo. | 115| See `#1986`_. | 116+-------------------------------------------------+-------------------------------------------+ 117 118Proto dependencies 119------------------ 120 121In order to build `proto_library`_ and `go_proto_library`_ rules, you must 122add a dependency on ``com_google_protobuf`` in order to build the ``protoc`` 123compiler. Version 3.14.0 is the minimum supported version, but higher minor 124versions shoudl work. You'll need a C/C++ toolchain for the execution platform 125to build ``protoc``. 126 127.. code:: bzl 128 129 load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") 130 131 http_archive( 132 name = "com_google_protobuf", 133 sha256 = "d0f5f605d0d656007ce6c8b5a82df3037e1d8fe8b121ed42e536f569dec16113", 134 strip_prefix = "protobuf-3.14.0", 135 urls = [ 136 "https://mirror.bazel.build/github.com/protocolbuffers/protobuf/archive/v3.14.0.tar.gz", 137 "https://github.com/protocolbuffers/protobuf/archive/v3.14.0.tar.gz", 138 ], 139 ) 140 141 load("@com_google_protobuf//:protobuf_deps.bzl", "protobuf_deps") 142 143 protobuf_deps() 144 145The `proto_library`_ rule is provided by the `rules_proto`_ 146repository. ``protoc-gen-go``, the Go proto compiler plugin, is provided by the 147repository ``com_github_golang_protobuf``. Both are declared by 148`go_rules_dependencies`_ by default. You won't need to declare an 149explicit dependency unless you specifically want to use a different version. See 150`Overriding dependencies`_ for instructions on using a different version. 151 152gRPC dependencies 153----------------- 154 155In order to build ``go_proto_library`` rules with the gRPC plugin, 156several additional dependencies are needed. At minimum, you'll need to 157declare ``org_golang_google_grpc``, ``org_golang_x_net``, and 158``org_golang_x_text``. 159 160If you're using Gazelle, and you already import ``google.golang.org/grpc`` 161from a .go file somewhere in your repository, and you're also using Go modules 162to manage dependencies, you can generate these rules with 163``bazel run //:gazelle -- update-repos -from_file=go.mod``. 164 165Make sure you set ``build_file_proto_mode = "disable"`` on the 166`go_repository`_ rule for ``org_golang_google_grpc``. 167 168For example: 169 170.. code:: bzl 171 172 load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies", "go_repository") 173 174 gazelle_dependencies() 175 176 go_repository( 177 name = "org_golang_google_grpc", 178 build_file_proto_mode = "disable", 179 importpath = "google.golang.org/grpc", 180 sum = "h1:J0UbZOIrCAl+fpTOf8YLs4dJo8L/owV4LYVtAXQoPkw=", 181 version = "v1.22.0", 182 ) 183 184 go_repository( 185 name = "org_golang_x_net", 186 importpath = "golang.org/x/net", 187 sum = "h1:oWX7TPOiFAMXLq8o0ikBYfCJVlRHBcsciT5bXOrH628=", 188 version = "v0.0.0-20190311183353-d8887717615a", 189 ) 190 191 go_repository( 192 name = "org_golang_x_text", 193 importpath = "golang.org/x/text", 194 sum = "h1:g61tztE5qeGQ89tm6NTjjM9VPIm088od1l6aSorWRWg=", 195 version = "v0.3.0", 196 ) 197 198Overriding dependencies 199----------------------- 200 201You can override a dependency declared in ``go_rules_dependencies`` by 202declaring a repository rule in WORKSPACE with the same name *before* the call 203to ``go_rules_dependencies``. 204 205For example, this is how you would override ``com_github_golang_protobuf``: 206 207.. code:: bzl 208 209 load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") 210 load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository") 211 212 http_archive( 213 name = "io_bazel_rules_go", 214 sha256 = "7b9bbe3ea1fccb46dcfa6c3f3e29ba7ec740d8733370e21cdc8937467b4a4349", 215 urls = [ 216 "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.22.4/rules_go-v0.22.4.tar.gz", 217 "https://github.com/bazelbuild/rules_go/releases/download/v0.22.4/rules_go-v0.22.4.tar.gz", 218 ], 219 ) 220 221 http_archive( 222 name = "bazel_gazelle", 223 sha256 = "d8c45ee70ec39a57e7a05e5027c32b1576cc7f16d9dd37135b0eddde45cf1b10", 224 urls = [ 225 "https://storage.googleapis.com/bazel-mirror/github.com/bazelbuild/bazel-gazelle/releases/download/v0.20.0/bazel-gazelle-v0.20.0.tar.gz", 226 "https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.20.0/bazel-gazelle-v0.20.0.tar.gz", 227 ], 228 ) 229 230 http_archive( 231 name = "com_google_protobuf", 232 sha256 = "d0f5f605d0d656007ce6c8b5a82df3037e1d8fe8b121ed42e536f569dec16113", 233 strip_prefix = "protobuf-3.14.0", 234 urls = [ 235 "https://mirror.bazel.build/github.com/protocolbuffers/protobuf/archive/v3.14.0.tar.gz", 236 "https://github.com/protocolbuffers/protobuf/archive/v3.14.0.tar.gz", 237 ], 238 ) 239 240 load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies") 241 load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies", "go_repository") 242 load("@com_google_protobuf//:protobuf_deps.bzl", "protobuf_deps") 243 244 go_repository( 245 name = "com_github_golang_protobuf", 246 build_file_proto_mode = "disable_global", 247 importpath = "github.com/golang/protobuf", 248 patch_args = ["-p1"], 249 patches = ["@io_bazel_rules_go//third_party:com_github_golang_protobuf-extras.patch"], 250 sum = "h1:F768QJ1E9tib+q5Sc8MkdJi1RxLTbRcTf8LJV56aRls=", 251 version = "v1.3.5", 252 ) 253 254 go_rules_dependencies() 255 256 go_register_toolchains() 257 258 gazelle_dependencies() 259 260 protobuf_deps() 261 262Some of the dependencies declared by ``go_rules_dependencies`` require 263additional patches and or adjustments compared to what `go_repository`_ 264generates by default (as ``com_github_golang_protobuf`` does in the example 265above). Patches may be found in the `third_party`_ directory. 266See notes in `repositories.bzl`_. If you're generated build files with 267`go_repository`_, you do not need the ``*-gazelle.patch`` files. 268