Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(docs): move WORKSPACE docs out of primary README #4209

Merged
merged 4 commits into from
Jan 7, 2025
Merged

chore(docs): move WORKSPACE docs out of primary README #4209

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
116d9ea
chore(docs): move WORKSPACE docs out of primary README
alexeagle Jan 1, 2025
e1d5bfb
chore: update release instructions
alexeagle Jan 1, 2025
091872a
fixup! chore(docs): move WORKSPACE docs out of primary README
alexeagle Jan 1, 2025
96ae7ee
fixup! chore(docs): move WORKSPACE docs out of primary README
alexeagle Jan 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
304 changes: 6 additions & 298 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -202,7 +201,6 @@ Contents

* `Overview`_
* `Setup`_
* `protobuf and gRPC`_
* `FAQ`_

Documentation
Expand Down Expand Up @@ -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
---
Expand Down
Loading
Loading