github.com/0xKiwi/rules_go@v0.24.3/go/dependencies.rst (about) 1 Go 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: core.rst#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.rst#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 46 This document describes workspace rules, functions, and dependencies intended 47 to be used in the ``WORKSPACE`` file.a 48 49 See also the `toolchains`_ for information on `go_register_toolchains`_ and 50 other rules used to download and register toolchains. 51 52 Contents 53 -------- 54 55 * `go_rules_dependencies`_ 56 * `Proto dependencies`_ 57 * `gRPC dependencies`_ 58 * `Overriding dependencies`_ 59 60 61 go_rules_dependencies 62 --------------------- 63 64 ``go_rules_dependencies`` is a function that registers external dependencies 65 needed by the Go rules. Projects that use rules_go should *always* call it from 66 WORKSPACE. It may be called before or after other workspace rules. 67 68 See `Overriding dependencies`_ for instructions on using a different version 69 of one of the repositories below. 70 71 ``go_rules_dependencies`` declares the repositories in the table below. 72 It 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 118 Proto dependencies 119 ------------------ 120 121 In order to build `proto_library`_ and `go_proto_library`_ rules, you must 122 add a dependency on ``com_google_protobuf`` (perhaps on a newer version) 123 in order to build the ``protoc`` compiler. You'll need a C/C++ toolchain for 124 the execution platform, too. 125 126 .. code:: bzl 127 128 load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") 129 130 http_archive( 131 name = "com_google_protobuf", 132 sha256 = "9748c0d90e54ea09e5e75fb7fac16edce15d2028d4356f32211cfa3c0e956564", 133 strip_prefix = "protobuf-3.11.4", 134 urls = ["https://github.com/protocolbuffers/protobuf/archive/v3.11.4.zip"], 135 ) 136 137 load("@com_google_protobuf//:protobuf_deps.bzl", "protobuf_deps") 138 139 protobuf_deps() 140 141 The `proto_library`_ rule is provided by the `rules_proto`_ 142 repository. ``protoc-gen-go``, the Go proto compiler plugin, is provided by the 143 repository ``com_github_golang_protobuf``. Both are declared by 144 `go_rules_dependencies`_ by default. You won't need to declare an 145 explicit dependency unless you specifically want to use a different version. See 146 `Overriding dependencies`_ for instructions on using a different version. 147 148 gRPC dependencies 149 ----------------- 150 151 In order to build ``go_proto_library`` rules with the gRPC plugin, 152 several additional dependencies are needed. At minimum, you'll need to 153 declare ``org_golang_google_grpc``, ``org_golang_x_net``, and 154 ``org_golang_x_text``. 155 156 If you're using Gazelle, and you already import ``google.golang.org/grpc`` 157 from a .go file somewhere in your repository, and you're also using Go modules 158 to manage dependencies, you can generate these rules with 159 ``bazel run //:gazelle -- update-repos -from_file=go.mod``. 160 161 Make sure you set ``build_file_proto_mode = "disable"`` on the 162 `go_repository`_ rule for ``org_golang_google_grpc``. 163 164 For example: 165 166 .. code:: bzl 167 168 load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies", "go_repository") 169 170 gazelle_dependencies() 171 172 go_repository( 173 name = "org_golang_google_grpc", 174 build_file_proto_mode = "disable", 175 importpath = "google.golang.org/grpc", 176 sum = "h1:J0UbZOIrCAl+fpTOf8YLs4dJo8L/owV4LYVtAXQoPkw=", 177 version = "v1.22.0", 178 ) 179 180 go_repository( 181 name = "org_golang_x_net", 182 importpath = "golang.org/x/net", 183 sum = "h1:oWX7TPOiFAMXLq8o0ikBYfCJVlRHBcsciT5bXOrH628=", 184 version = "v0.0.0-20190311183353-d8887717615a", 185 ) 186 187 go_repository( 188 name = "org_golang_x_text", 189 importpath = "golang.org/x/text", 190 sum = "h1:g61tztE5qeGQ89tm6NTjjM9VPIm088od1l6aSorWRWg=", 191 version = "v0.3.0", 192 ) 193 194 Overriding dependencies 195 ----------------------- 196 197 You can override a dependency declared in ``go_rules_dependencies`` by 198 declaring a repository rule in WORKSPACE with the same name *before* the call 199 to ``go_rules_dependencies``. 200 201 For example, this is how you would override ``com_github_golang_protobuf``: 202 203 .. code:: bzl 204 205 load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") 206 load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository") 207 208 http_archive( 209 name = "io_bazel_rules_go", 210 sha256 = "7b9bbe3ea1fccb46dcfa6c3f3e29ba7ec740d8733370e21cdc8937467b4a4349", 211 urls = [ 212 "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.22.4/rules_go-v0.22.4.tar.gz", 213 "https://github.com/bazelbuild/rules_go/releases/download/v0.22.4/rules_go-v0.22.4.tar.gz", 214 ], 215 ) 216 217 http_archive( 218 name = "bazel_gazelle", 219 sha256 = "d8c45ee70ec39a57e7a05e5027c32b1576cc7f16d9dd37135b0eddde45cf1b10", 220 urls = [ 221 "https://storage.googleapis.com/bazel-mirror/github.com/bazelbuild/bazel-gazelle/releases/download/v0.20.0/bazel-gazelle-v0.20.0.tar.gz", 222 "https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.20.0/bazel-gazelle-v0.20.0.tar.gz", 223 ], 224 ) 225 226 http_archive( 227 name = "com_google_protobuf", 228 sha256 = "9748c0d90e54ea09e5e75fb7fac16edce15d2028d4356f32211cfa3c0e956564", 229 strip_prefix = "protobuf-3.11.4", 230 urls = ["https://github.com/protocolbuffers/protobuf/archive/v3.11.4.zip"], 231 ) 232 233 load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies") 234 load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies", "go_repository") 235 load("@com_google_protobuf//:protobuf_deps.bzl", "protobuf_deps") 236 237 go_repository( 238 name = "com_github_golang_protobuf", 239 build_file_proto_mode = "disable_global", 240 importpath = "github.com/golang/protobuf", 241 patch_args = ["-p1"], 242 patches = ["@io_bazel_rules_go//third_party:com_github_golang_protobuf-extras.patch"], 243 sum = "h1:F768QJ1E9tib+q5Sc8MkdJi1RxLTbRcTf8LJV56aRls=", 244 version = "v1.3.5", 245 ) 246 247 go_rules_dependencies() 248 249 go_register_toolchains() 250 251 gazelle_dependencies() 252 253 protobuf_deps() 254 255 Some of the dependencies declared by ``go_rules_dependencies`` require 256 additional patches and or adjustments compared to what `go_repository`_ 257 generates by default (as ``com_github_golang_protobuf`` does in the example 258 above). Patches may be found in the `third_party`_ directory. 259 See notes in `repositories.bzl`_. If you're generated build files with 260 `go_repository`_, you do not need the ``*-gazelle.patch`` files.