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