Merge branch 'master' into msan_support

Author: smertnik3sh

README.rst

@@ -9,21 +9,20 @@ Go rules for Bazel_
 .. _Build modes: go/modes.rst
 .. _Bzlmod: https://bazel.build/external/overview#bzlmod
 .. _Go with Bzlmod: docs/go/core/bzlmod.md
+.. _Go with WORKSPACE: docs/go/core/workspace.md
 .. _Core rules: docs/go/core/rules.md
 .. _Coverage: https://bazel.google.cn/docs/coverage
 .. _Dependencies: go/dependencies.rst
 .. _Deprecation schedule: https://github.com/bazelbuild/rules_go/wiki/Deprecation-schedule
 .. _Gopher Slack: https://invite.slack.golangbridge.org/
 .. _gopls integration: https://github.com/bazelbuild/rules_go/wiki/Editor-setup
 .. _Overriding dependencies: go/dependencies.rst#overriding-dependencies
-.. _Proto dependencies: go/dependencies.rst#proto-dependencies
 .. _Proto rules: proto/core.rst
 .. _Protocol buffers: proto/core.rst
 .. _Toolchains: go/toolchains.rst
 .. _Using rules_go on Windows: windows.rst
 .. _bazel-go-discuss: https://groups.google.com/forum/#!forum/bazel-go-discuss
 .. _configuration transition: https://docs.bazel.build/versions/master/skylark/lib/transition.html
-.. _gRPC dependencies: go/dependencies.rst#grpc-dependencies
 .. _gazelle update-repos: https://github.com/bazelbuild/bazel-gazelle#update-repos
 .. _gazelle: https://github.com/bazelbuild/bazel-gazelle
 .. _github.com/bazelbuild/bazel-gazelle: https://github.com/bazelbuild/bazel-gazelle
@@ -202,7 +201,6 @@ Contents
 
 * `Overview`_
 * `Setup`_
-* `protobuf and gRPC`_
 * `FAQ`_
 
 Documentation
@@ -306,302 +304,12 @@ Several additional tools need to be installed and configured.
 Initial project setup
 ~~~~~~~~~~~~~~~~~~~~~
 
-If you are using Bazel's new external dependency management system `Bzlmod`_,
-refer to the dedicated `Go with Bzlmod`_ guide instead.
+There are two ways to setup:
 
-Create a file at the top of your repository named ``WORKSPACE``, and add the
-snippet below (or add to your existing ``WORKSPACE``). This tells Bazel to
-fetch rules_go and its dependencies. Bazel will download a recent supported
-Go toolchain and register it for use.
-
-.. code:: bzl
-
-    load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
-
-    http_archive(
-        name = "io_bazel_rules_go",
-        integrity = "sha256-M6zErg9wUC20uJPJ/B3Xqb+ZjCPn/yxFF3QdQEmpdvg=",
-        urls = [
-            "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.48.0/rules_go-v0.48.0.zip",
-            "https://github.com/bazelbuild/rules_go/releases/download/v0.48.0/rules_go-v0.48.0.zip",
-        ],
-    )
-
-    load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")
-
-    go_rules_dependencies()
-
-    go_register_toolchains(version = "1.23.1")
-
-You can use rules_go at ``master`` by using `git_repository`_ instead of
-`http_archive`_ and pointing to a recent commit.
-
-Add a file named ``BUILD.bazel`` in the root directory of your project.
-You'll need a build file in each directory with Go code, but you'll also need
-one in the root directory, even if your project doesn't have Go code there.
-For a "Hello, world" binary, the file should look like this:
-
-.. code:: bzl
-
-    load("@io_bazel_rules_go//go:def.bzl", "go_binary")
-
-    go_binary(
-        name = "hello",
-        srcs = ["hello.go"],
-    )
-
-You can build this target with ``bazel build //:hello``.
-
-Generating build files
-~~~~~~~~~~~~~~~~~~~~~~
-
-If your project can be built with ``go build``, you can generate and update your
-build files automatically using gazelle_.
-
-Add the ``bazel_gazelle`` repository and its dependencies to your
-``WORKSPACE``. It should look like this:
-
-  .. code:: bzl
-
-    load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
-
-    http_archive(
-        name = "io_bazel_rules_go",
-        integrity = "sha256-M6zErg9wUC20uJPJ/B3Xqb+ZjCPn/yxFF3QdQEmpdvg=",
-        urls = [
-            "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.48.0/rules_go-v0.48.0.zip",
-            "https://github.com/bazelbuild/rules_go/releases/download/v0.48.0/rules_go-v0.48.0.zip",
-        ],
-    )
-
-    http_archive(
-        name = "bazel_gazelle",
-        integrity = "sha256-12v3pg/YsFBEQJDfooN6Tq+YKeEWVhjuNdzspcvfWNU=",
-        urls = [
-            "https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.37.0/bazel-gazelle-v0.37.0.tar.gz",
-            "https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.37.0/bazel-gazelle-v0.37.0.tar.gz",
-        ],
-    )
-
-    load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")
-    load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies")
-
-    go_rules_dependencies()
-
-    go_register_toolchains(version = "1.23.1")
-
-    gazelle_dependencies()
-
-Add the code below to the ``BUILD.bazel`` file in your project's root directory.
-Replace the string after ``prefix`` with an import path prefix that matches your
-project. It should be the same as your module path, if you have a ``go.mod``
-file.
-
-.. code:: bzl
-
-    load("@bazel_gazelle//:def.bzl", "gazelle")
-
-    # gazelle:prefix github.com/example/project
-    gazelle(name = "gazelle")
-
-This declares a ``gazelle`` binary rule, which you can run using the command
-below:
-
-.. code:: bash
-
-    bazel run //:gazelle
-
-This will generate a ``BUILD.bazel`` file with `go_library`_, `go_binary`_, and
-`go_test`_ targets for each package in your project. You can run the same
-command in the future to update existing build files with new source files,
-dependencies, and options.
-
-Writing build files by hand
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If your project doesn't follow ``go build`` conventions or you prefer not to use
-gazelle_, you can write build files by hand.
-
-In each directory that contains Go code, create a file named ``BUILD.bazel``
-Add a ``load`` statement at the top of the file for the rules you use.
-
-.. code:: bzl
-
-    load("@io_bazel_rules_go//go:def.bzl", "go_binary", "go_library", "go_test")
-
-For each library, add a `go_library`_ rule like the one below.  Source files are
-listed in the ``srcs`` attribute. Imported packages outside the standard library
-are listed in the ``deps`` attribute using `Bazel labels`_ that refer to
-corresponding `go_library`_ rules. The library's import path must be specified
-with the ``importpath`` attribute.
-
-.. code:: bzl
-
-    go_library(
-        name = "foo_library",
-        srcs = [
-            "a.go",
-            "b.go",
-        ],
-        importpath = "github.com/example/project/foo",
-        deps = [
-            "//tools",
-            "@org_golang_x_utils//stuff",
-        ],
-        visibility = ["//visibility:public"],
-    )
-
-For tests, add a `go_test`_ rule like the one below. The library being tested
-should be listed in an ``embed`` attribute.
-
-.. code:: bzl
-
-    go_test(
-        name = "foo_test",
-        srcs = [
-            "a_test.go",
-            "b_test.go",
-        ],
-        embed = [":foo_lib"],
-        deps = [
-            "//testtools",
-            "@org_golang_x_utils//morestuff",
-        ],
-    )
-
-For binaries, add a `go_binary`_ rule like the one below.
-
-.. code:: bzl
-
-    go_binary(
-        name = "foo",
-        srcs = ["main.go"],
-    )
-
-Adding external repositories
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-For each Go repository, add a `go_repository`_ rule to ``WORKSPACE`` like the
-one below.  This rule comes from the Gazelle repository, so you will need to
-load it. `gazelle update-repos`_ can generate or update these rules
-automatically from a go.mod or Gopkg.lock file.
-
-.. code:: bzl
-
-    load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
-
-    # Download the Go rules.
-    http_archive(
-        name = "io_bazel_rules_go",
-        integrity = "sha256-M6zErg9wUC20uJPJ/B3Xqb+ZjCPn/yxFF3QdQEmpdvg=",
-        urls = [
-            "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.48.0/rules_go-v0.48.0.zip",
-            "https://github.com/bazelbuild/rules_go/releases/download/v0.48.0/rules_go-v0.48.0.zip",
-        ],
-    )
-
-    # Download Gazelle.
-    http_archive(
-        name = "bazel_gazelle",
-        integrity = "sha256-12v3pg/YsFBEQJDfooN6Tq+YKeEWVhjuNdzspcvfWNU=",
-        urls = [
-            "https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.37.0/bazel-gazelle-v0.37.0.tar.gz",
-            "https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.37.0/bazel-gazelle-v0.37.0.tar.gz",
-        ],
-    )
-
-    # Load macros and repository rules.
-    load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")
-    load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies", "go_repository")
-
-    # Declare Go direct dependencies.
-    go_repository(
-        name = "org_golang_x_net",
-        importpath = "golang.org/x/net",
-        sum = "h1:7EYJ93RZ9vYSZAIb2x3lnuvqO5zneoD6IvWjuhfxjTs=",
-        version = "v0.23.0",
-    )
-
-    # Declare indirect dependencies and register toolchains.
-    go_rules_dependencies()
-
-    go_register_toolchains(version = "1.23.1")
-
-    gazelle_dependencies()
-
-
-protobuf and gRPC
------------------
-
-To generate code from protocol buffers, you'll need to add a dependency on
-``com_google_protobuf`` to your ``WORKSPACE``.
-
-.. code:: bzl
-
-    load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
-
-    http_archive(
-        name = "com_google_protobuf",
-        sha256 = "535fbf566d372ccf3a097c374b26896fa044bf4232aef9cab37bd1cc1ba4e850",
-        strip_prefix = "protobuf-3.15.0",
-        urls = [
-            "https://mirror.bazel.build/github.com/protocolbuffers/protobuf/archive/v3.15.0.tar.gz",
-            "https://github.com/protocolbuffers/protobuf/archive/v3.15.0.tar.gz",
-        ],
-    )
-
-    load("@com_google_protobuf//:protobuf_deps.bzl", "protobuf_deps")
-
-    protobuf_deps()
-
-You'll need a C/C++ toolchain registered for the execution platform (the
-platform where Bazel runs actions) to build protoc.
-
-The `proto_library`_ rule is provided by the ``rules_proto`` repository.
-``protoc-gen-go``, the Go proto compiler plugin, is provided by the
-``com_github_golang_protobuf`` repository. Both are declared by
-`go_rules_dependencies`_. You won't need to declare an explicit dependency
-unless you specifically want to use a different version. See `Overriding
-dependencies`_ for instructions on using a different version.
-
-gRPC dependencies are not declared by default (there are too many). You can
-declare them in WORKSPACE using `go_repository`_. You may want to use
-`gazelle update-repos`_ to import them from ``go.mod``.
-
-See `Proto dependencies`_, `gRPC dependencies`_ for more information. See also
-`Avoiding conflicts`_.
-
-Once all dependencies have been registered, you can declare `proto_library`_
-and `go_proto_library`_ rules to generate and compile Go code from .proto
-files.
-
-.. code:: bzl
-
-    load("@rules_proto//proto:defs.bzl", "proto_library")
-    load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library")
-
-    proto_library(
-        name = "foo_proto",
-        srcs = ["foo.proto"],
-        deps = ["//bar:bar_proto"],
-        visibility = ["//visibility:public"],
-    )
-
-    go_proto_library(
-        name = "foo_go_proto",
-        importpath = "github.com/example/protos/foo_proto",
-        protos = [":foo_proto"],
-        visibility = ["//visibility:public"],
-    )
-
-A ``go_proto_library`` target may be imported and depended on like a normal
-``go_library``.
-
-Note that recent versions of rules_go support both APIv1
-(``github.com/golang/protobuf``) and APIv2 (``google.golang.org/protobuf``).
-By default, code is generated with
-``github.com/golang/protobuf/cmd/protoc-gen-gen`` for compatibility with both
-interfaces. Client code may import use either runtime library or both.
+* With Bazel's external dependency management system `Bzlmod`_,
+refer to the dedicated `Go with Bzlmod`_ guide.
+* With the older ``WORKSPACE`` dependency file, refer to the
+`Go with WORKSPACE`_ setup docs.
 
 FAQ
 ---