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