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