Skip to content

Commit

Permalink
chore(docs): move WORKSPACE docs out of primary README (#4209)
Browse files Browse the repository at this point in the history 
Current Bazel nightly versions (pre-releases of Bazel 9) will soon stop
supporting this, so it shouldn't be the first docs we show new users.

Note, I've done the minimal touching of the content, converting
ReStructured Text to Markdown.

Related to
bazel-contrib/bazel-gazelle#1715 (comment)
from a year ago.
  • Loading branch information
@alexeagle
alexeagle authored Jan 7, 2025
1 parent 292d14d commit 623f600
Show file tree
Hide file tree
Showing 3 changed files with 305 additions and 299 deletions.
304 changes: 6 additions & 298 deletions README.rst
View file
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

0 comments on commit 623f600

Please sign in to comment.