Go rules for Bazel_

.. All external links are here
.. _Bazel: https://bazel.build/
.. |travis| image:: https://travis-ci.org/bazelbuild/rules_go.svg?branch=master
:target: https://travis-ci.org/bazelbuild/rules_go
.. |jenkins| image:: http://ci.bazel.io/buildStatus/icon?job=PR/rules_go
:target: http://ci.bazel.io/view/Bazel%20bootstrap%20and%20maintenance/job/PR/job/rules_go/
.. _gazelle: go/tools/gazelle/README.md
.. _vendoring: Vendoring.md
.. _protocol buffers: proto/core.rst
.. _go_repository: go/workspace.rst#go_repository
.. _go_library: go/core.rst#go_library
.. _go_binary: go/core.rst#go_binary
.. _go_test: go/core.rst#go_test
.. _Bazel labels: https://docs.bazel.build/versions/master/build-ref.html#labels
.. _#721: bazel-contrib#721
.. _#265: bazel-contrib#265

.. ;; And now we continue with the actual content

======== =========
Travis Jenkins
======== =========
|travis| |jenkins|
======== =========

Announcements

September 13, 2017
Release 0.5.5 <https://github.com/bazelbuild/rules_go/releases/tag/0.5.5>_ is now
available. This is a bug fix release on top of 0.5.4 that removes the sha256
from some of our dependencies, since it changed upstream.
August 28, 2017
Release 0.5.4 <https://github.com/bazelbuild/rules_go/releases/tag/0.5.4>_ is
now available! This will be the last stable tag before requiring Bazel 0.5.4 and toolchains
support.
August 9, 2017
Release 0.5.3 <https://github.com/bazelbuild/rules_go/releases/tag/0.5.3>_ is
now available!

.. contents::

Quick links

• Core api <go/core.rst>_
• Workspace rules <go/workspace.rst>_
• Toolchains <go/toolchains.rst>_
• Protobuf rules <proto/core.rst>_
• Extra rules <go/extras.rst>_
• Deprecated rules <go/deprecated.rst>_
• Build modes <go/modes.rst>_

Overview

The rules are in the alpha stage of development. They support:

• libraries <go_library_>_
• binaries <go_binary_>_
• tests <go_test_>_
• vendoring_
• cgo
• cross compilation
• auto generating BUILD files via gazelle_
• protocol buffers_

They currently do not support (in order of importance):

• bazel-style auto generating BUILD (where the library name is other than
  go_default_library)
• C/C++ interoperation except cgo (swig etc.)
• coverage
• test sharding

:Note: The latest version of these rules (0.5.5) require Bazel ≥ 0.5.2 to
work.

The master branch is only guaranteed to work with the latest version of Bazel.

Setup

• Create a file at the top of your repository named WORKSPACE, and add one
  of the following snippets, verbatim. This will let Bazel fetch necessary
  dependencies from this repository and a few others.
  If you're using the latest stable release you can use the following contents:

  .. code:: bzl

  http_archive(
  name = "io_bazel_rules_go",
  url = "https://github.com/bazelbuild/rules_go/releases/download/0.5.5/rules_go-0.5.5.tar.gz",
  sha256 = "ca58b0b856dc95473b93f2228ab117913b82a6617fc0deabd107346e3981522a",
  )
  load("@io_bazel_rules_go//go:def.bzl", "go_repositories")

  go_repositories()

  If you're using rules_go at or near the HEAD of master, you can use the
  following contents (optionally replacing the commit with something newer):

  .. code:: bzl

  git_repository(
  name = "io_bazel_rules_go",
  remote = "https://github.com/bazelbuild/rules_go.git",
  commit = "d8d73c918ed7b59a5584e0cab4f5274d2f91faab",
  )
  load("@io_bazel_rules_go//go:def.bzl", "go_rules_dependencies", "go_register_toolchains")

  go_rules_dependencies()
  go_register_toolchains()

  You can add more external dependencies to this file later (see go_repository_).

• Add a file named BUILD.bazel in the root directory of your
  project. In general, you need one of these files in every directory
  with Go code, but you need one in the root directory even if your project
  doesn't have any Go code there.

• If your project can be built with go build, you can
  generate your build files <Generating build files_>_ using Gazelle. If your
  project isn't compatible with go build or if you prefer not to use Gazelle,
  you can write build files by hand <Writing build files by hand_>_.

Generating build files

If your project can be built with ``go build``, you can generate and update your
build files automatically using gazelle_, a tool included in this repository.

* Add the code below to the ``BUILD.bazel`` file in your repository's
  root directory. Replace the ``prefix`` string with the prefix you chose for
  your project earlier.

  .. code:: bzl

    load("@io_bazel_rules_go//go:def.bzl", "gazelle")

    gazelle(
        name = "gazelle",
        prefix = "github.com/example/project",
    )

* If your project uses vendoring, add ``external = "vendored",`` below the
  ``prefix`` line.

* After adding the ``gazelle`` rule, run the command below:

  ::

    bazel run //:gazelle


  This will generate a ``BUILD.bazel`` file for each Go package in your
  repository.  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 srcs. Other packages you import are listed in
  deps using Bazel labels_
  that refer to other go_library_ rules. The library's import path should
  be specified with importpath.

  .. code:: bzl

  go_library(
  name = "go_default_library",
  srcs = [
  "foo.go",
  "bar.go",
  ],
  deps = [
  "//tools:go_default_library",
  "@org_golang_x_utils//stuff:go_default_library",
  ],
  importpath = "github.com/example/project/foo",
  visibility = ["//visibility:public"],
  )

• For each test, add a go_test_ rule like either of the ones below.
  You'll need separate go_test_ rules for internal and external tests.

  .. code:: bzl

  Internal test

  go_test(
  name = "go_default_test",
  srcs = ["foo_test.go"],
  importpath = "github.com/example/project/foo",
  library = ":go_default_library",
  )

  External test

  go_test(
  name = "go_default_xtest",
  srcs = ["bar_test.go"],
  deps = [":go_default_library"],
  importpath = "github.com/example/project/foo",
  )

• For each binary, add a go_binary_ rule like the one below.

  .. code:: bzl

  go_binary(
  name = "foo",
  srcs = ["main.go"],
  deps = [":go_default_library"],
  importpath = "github.com/example/project/foo",
  )

• For instructions on how to depend on external libraries,
  see _vendoring

FAQ

Can I still use the go tool?

Yes, this setup was deliberately chosen to be compatible with ``go build``.
Make sure your project appears in ``GOPATH``, and it should work.

Note that ``go build`` won't be aware of dependencies listed in ``WORKSPACE``, so
these will be downloaded into ``GOPATH``. You may also need to check in generated
files.

What's up with the ``go_default_library`` name?

This was used to keep import paths consistent in libraries that can be built
with go build before the importpath attribute was available.

In order to compile and link correctly, the Go rules need to be able to
translate Bazel labels to Go import paths. Libraries that don't set the
importpath attribute explicitly have an implicit dependency on //:go_prefix,
a special rule that specifies an import path prefix. The import path is
the prefix concatenated with the Bazel package and target name. For example,
if your prefix was github.com/example/project, and your library was
//foo/bar:bar, the Go rules would decide the import path was
github.com/example/project/foo/bar/bar. The stutter at the end is incompatible
with go build, so if the label name is go_default_library, the import path
is just the prefix concatenated with the package name. So if your library is
//foo/bar:go_default_library, the import path is
github.com/example/project/foo/bar.

We are working on deprecating go_prefix and making importpath mandatory (see
#721). When this work is complete, the go_default_library name won't be needed.
We may decide to stop using this name in the future (see #265).