Skip to content

Latest commit

 

History

History
104 lines (82 loc) · 3.89 KB

Vendoring.md

File metadata and controls

104 lines (82 loc) · 3.89 KB
Raw

Using external libraries with Go and Bazel

To depend on external libraries, you have two options: vendoring or external repositories.

Vendoring

The first option is to vendor the libraries - that is, copy them all into a "vendor" subdirectory inside your own library, and create your own BUILD files for each vendor repository. Vendoring is a part of Go since 1.5 - see https://golang.org/s/go15vendor for more details, and note that vendoring is enabled by default since Go 1.6.

Take care to observe the following restrictions while using vendoring:

  • You cannot use git submodule since you'll need to be adding the BUILD files at every level of the hierarchy.
  • Since the Bazel rules do not currently support build constraints, you'll need to manually include/exclude files with tags such as //+build !go1.5.

Vendoring may be preferable to using external repositories (see below) if you have different packages that require different versions of external repos.

WORKSPACE repositories

The other option for using external libraries is to import them in your WORKSPACE file. You can use the new_go_repository rule to import repositories that conform the the normal Go directory conventions. This is similar to new_git_repository, but it automatically generates BUILD files for you using gazelle.

You can use go_repository if the project you're importing already has BUILD files. This is like git_repository but it recognizes importpath redirection.

If you prefer to write your own BUILD files for dependencies, you can still use new_git_repository. Be aware that you can only specify one BUILD file for the top-level package.

Experimental: some users may find wtool helpful for managing new_go_repository entries in their WORKSPACE file.

Example

Here is an example from a WORKSPACE file using the repository method for github.com/golang/glog.

# Import Go rules and toolchain.
git_repository(
    name = "io_bazel_rules_go",
    remote = "https://github.com/bazelbuild/rules_go.git",
    tag = "0.4.1",
)
load("@io_bazel_rules_go//go:def.bzl", "go_repositories")

# Import Go dependencies.
new_go_repository(
    name = "com_github_golang_glog",
    importpath = "github.com/golang/glog",
    commit = "23def4e6c14b4da8ac2ed8007337bc5eb5007998",
)

You could use this library in the deps of a go_library with the label @com_github_golang_glog//:go_default_library. If you were vendoring this library, you'd refer to it as //vendor/github.com/golang/glog:go_default_library instead.

General rules

If you write your own BUILD files for dependencies, whether they are vendored or imported through WORKSPACE, here are some things to keep in mind.

  • Don't forget to load the Bazel rules from this repository (go_library, etc). You don't get them for free.
  • Declare a go_prefix, almost certainly matching the import path of the repository you're cloning.
  • Declare a single go_library named go_default_library in each BUILD file, assuming that each directory contains a single Go package. You can't use a single BUILD file to define subpackages, for example.
  • Have public visibility.
  • Exclude any *_test.go files from the go_library srcs. Unlike the go tool, go_library does not do this automatically.
  • Manually exclude files with build tags that wouldn't be satisfied - for example, if a file includes the build constraint //+build !go1.5 and you're using a Go 1.5 or later, you must exclude this file yourself.

Example

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

go_prefix("github.com/golang/glog")

go_library(
    name = "go_default_library",
    srcs = glob(["*.go"], exclude=["*_test.go"]),
    visibility = ["//visibility:public"],
)