the Chromium logo

The Chromium Projects
Chromium OS > Chromium OS Developer Guide >

Go in Chromium OS

This page provides information on using Go in Chromium OS, including recommendations for project organization, importing and managing third party packages, and writing ebuilds.

Projects should generally follow the official recommendation to organize their Go workspaces: golang.org/doc/code.html These are some additional recommendations and naming conventions for organizing Go project workspaces in Chromium OS:

Recommendations for local development and builds

Set the GOPATH environment variable to contain two elements:

  1. Path to the local Go workspace (directory containing "src/<project>/").
  2. Path to all locally installed (emerged) Go packages: "/usr/lib/gopath".

When compiling for host, invoke the Go command as "x86_64-pc-linux-gnu-go", or simply, "go".

Go cross compiler for a board is installed automatically when "setup_board" is run in the chroot.

Setting up ebuilds for third party Go packages

Write an ebuild to fetch and install third party packages to "/usr/lib/gopath".

Setting up ebuilds for Chromium OS Go projects

IMPORTANT: Never use "go get" from an ebuild. Instead, write ebuilds for external dependencies and let Portage make them available under "/usr/lib/gopath". If a project is only providing common "chromiumos/" Go packages for use by other projects, its ebuild only needs to fetch and install the package files to "/usr/lib/gopath".

For a typical Go project that needs to build and install executables:

A single ebuild can install executable binaries, as well as provide Go packages for other projects to import.

Upgrading ebuilds for third party Go projects

When we need to upgrade a newer version of an existing third party package, simply update the ebuild files and the Manifest.

Location of ebuilds and repositories

Useful functions and variables

The cros-go eclass is defined here: chromiumos-overlay/eclass/cros-go.eclass CROS_GO_SOURCE Path to the upstream repository and commit id. Go repositories on "github.com" and "*.googlesource.com" are supported. The source string contains the path of the git repository containing Go packages, and a commit-id (or version tag). For example:

CROS_GO_SOURCE="github.com/golang/glog 44145f04b68cf362d9c4df2182967c2275eaefed"

will fetch the sources from github.com/golang/glog at the specified commit-id, and

CROS_GO_SOURCE="github.com/pkg/errors v0.8.0"

will fetch the sources from github.com/pkg/errors at version v0.8.0. By default, the import path for Go packages in the repository is the same as repository path. This can be overridden by appending a colon to the repository path, followed by an alternate import path. For example:

CROS_GO_SOURCE="github.com/go-yaml/yaml:gopkg.in/yaml.v2 v2.2.1"

will fetch the sources from github.com/go-yaml/yaml at the version v2.2.1, and install the package under "gopkg.in/yaml.v2". CROS_GO_SOURCE can contain multiple items when defined as an array:

CROS_GO_SOURCE=(
    "github.com/golang/glog 44145f04b68cf362d9c4df2182967c2275eaefed"
    "github.com/pkg/errors v0.8.0"
    "github.com/go-yaml/yaml:gopkg.in/yaml.v2 v2.2.1"
)

CROS_GO_WORKSPACE Path to the Go workspace, default is "${S}". The Go workspace is searched for packages to build and install. If all Go packages in the repository are under "go/src/":

CROS_GO_WORKSPACE="${S}/go"

CROS_GO_WORKSPACE can contain multiple items when defined as an array:

CROS_GO_WORKSPACE=(
    "${S}"
    "${S}/tast-base"
)

CROS_GO_BINARIES Go executable binaries to build and install. Each path must contain a package "main". The last component of the package path will become the name of the executable. The executable name can be overridden by appending a colon to the package path, followed by an alternate name. The install path for an executable can be overridden by appending a colon to the package path, followed by the desired install path/name for it. For example:

CROS_GO_BINARIES=(
    "golang.org/x/tools/cmd/godoc"
    "golang.org/x/tools/cmd/guru:goguru"
    "golang.org/x/tools/cmd/stringer:/usr/local/bin/gostringer"
)

will build and install "godoc", "goguru", and "gostringer" binaries. CROS_GO_VERSION Version string to embed in the executable binary. The variable main.Version is set to this value at build time. For example:

CROS_GO_VERSION="${PVR}"

will set main.Version string variable to package version and revision (if any) of the ebuild. CROS_GO_PACKAGES Go packages to install in "/usr/lib/gopath". Packages are installed in "/usr/lib/gopath" such that they can be imported later from Go code using the exact paths listed here. For example:

CROS_GO_PACKAGES=(	"github.com/golang/glog")

will install package files to "/usr/lib/gopath/src/github.com/golang/glog" and other Go projects can use the package with

import "github.com/golang/glog"

If the last component of a package path is "...", it is expanded to include all Go packages under the directory. CROS_GO_TEST Go packages to test. Package tests are run with -short flag by default. Package tests are always built and run locally on host. Default is to test all packages in CROS_GO_WORKSPACE(s). cros-go_src_uri Construct a valid SRC_URI from CROS_GO_SOURCE. Set the SRC_URI in an ebuild with:

SRC_URI="$(cros-go_src_uri)"

cros-go_gopath A valid GOPATH for CROS_GO_WORKSPACE. Set the GOPATH in an ebuild with:

GOPATH="$(cros-go_gopath)"

cros_go Wrapper function for invoking the Go tool from an ebuild. It provides the following functionality:

For most ebuilds, setting the CROS_GO_BINARIES variable should be enough to build and install Go binaries. Implementation of CROS_GO_BINARIES uses the cros_go wrapper internally.