README

Goma server

Goma is a distributed compiler service for open-source project such as Chromium and Android. It's some kind of replacement of distcc+ccache.

This is reference implementation of server code to be used with Goma client.

[TOC]

Dependencies

The Goma server uses a backend service that implements the Remote Execution API to distribute compile requests across a collection of worker machines and to cache the results of compilations. The Remote Execution API is an open-source standard, with multiple service implementations. The Goma server has been tested with Google's internal Remote Build Execution service, but could use other service implementations with some minor tweaks to the service code.

How to build

Goma server can be built on Linux.

$ GO111MODULE=on go get go.chromium.org/goma/server/cmd/remoteexec_proxy

You will get the binary in $(go env GOPATH)/bin.

How to run

remoteexec_proxy is a single server that acts as proxy server between Goma client and Remote Execution API.

$ remoteexec_proxy --port $PORT \
   --platform-container-image "docker://...@sha256:..." \
   --remoteexec-addr $REMOTEEXEC_ADDR \
   --remote-instance-name $REMOTE_INSTANCE_NAME

for chromium, platform container image should be created with install-build-dep.sh.

Example Dockerfile

FROM ubuntu:16.04
ENV DEBIAN_FRONTEND noninteractive

ADD https://chromium.googlesource.com/chromium/src/+/master/build/install-build-deps.sh?format=TEXT /tmp/install-build-deps.sh.base64
RUN base64 -d /tmp/install-build-deps.sh.base64 > /tmp/install-build-deps.sh \
  && \
  apt-get -y update \
  && \
  apt-get install -f -y build-essential gcc-4.8 g++-4.8 docker.io \
  && \
  bash /tmp/install-build-deps.sh --lib32 --no-prompt \
     --no-chromeos-fonts \
  && \
  rm -rf /var/lib/apt/lists/*

If Remote Execution API requires service account, specify service account JSON file for Remote Execution API by --service-account-json.

Running user is granted by default. If you need to allow other users, you need to specify them by --allowed-users.

Log messages will be output to stderr.

How to use

Install goma client. We provide prebuilt binary with cipd, which is available in depot_tools.

$ cipd install infra/goma/client/linux-amd64 -root ${HOME}/goma

or follow the build instructions to build your own local version of Goma client before running the server code, and install it in $HOME/goma.

Need to authenticate Goma client before use.

$ $HOME/goma/goma_auth.py login

Specify hostname in $GOMA_SERVER_HOST and port in $GOMA_SERVER_PORT, along with a few other environment flags.

$ export GOMA_SERVER_HOST='host-of-remoteexec_proxy-running'
$ export GOMA_SERVER_PORT='port-of-remoteexec_proxy-running'
$ export GOMA_USE_SSL=false
$ export GOMA_ARBITRARY_TOOLCHAIN_SUPPORT=true

For example, if you are running remoteexec_proxy locally with --port 5050, use:

$ export GOMA_SERVER_HOST=localhost
$ export GOMA_SERVER_PORT=5050

Finally, start Goma client:

$ $HOME/goma/goma_ctl.py ensure_start

and in chromium tree.

$ rm -f out/Release/obj/base/base/base64.o
$ GOMA_USE_LOCAL=false autoninja -C out/Release obj/base/base/base64.o
Expand ▾ Collapse ▴

Directories

Path Synopsis
auth Package auth provides authentication service.
auth/account Package account manages service account.
auth/acl Package acl performs access control with ACL.
auth/authdb Package authdb provides access to authentication database.
auth/enduser Package enduser manages end user information with context.
backend Package backend is goma service backend of /cxx-compiler-service/*.
bytestreamio Package bytestreamio provides io interfaces on bytestream service.
cache Package cache provides cache service.
cache/gcs Package gcs provides cache service by google cloud storage.
cache/redis Package redis provides cache service by redis (cloud memorystore).
cmd/auth_server Binary auth_server provides auth service via gRPC.
cmd/cache_server Binary cache_server provides cache service via gRPC.
cmd/exec_server Binary exec_server provides goma exec service via gRPC.
cmd/execlog_server Binary execlog_server provides goma execlog service via gRPC.
cmd/file_server Binary file_server provides goma file service via gRPC.
cmd/frontend Binary frontend is goma frontend.
cmd/goma_grpc_client Binary goma_grpc_client is a simple gRPC client of goma api.
cmd/goma_replay Binary goma_replay is a simple goma client for load testing etc.
cmd/remoteexec_proxy Binary remoteexec-proxy is a proxy server between Goma client and Remote Execution API.
command Package command manages commands/toolchains.
command/descriptor Package descriptor provides command descriptor utilities.
command/descriptor/posixpath Package posixpath handles posix-path (Unix style; slash separeted path).
command/descriptor/winpath Package winpath handles windows-path (backslash separated path).
command/normalizer Package normalizer provides functions to normalize target.
command/pathconv Package pathconv provides path converter between client and server.
exec Package exec provides goma exec service implementation.
execlog Package execlog provides goma execlog service implementation.
file Package file provides goma file service implementation.
frontend Package frontend is goma service frontend (/cxx-compiler-service/*).
fswatch Package fswatch watches directory with fsnotify.
hash Package hash provides a hash function used in goma.
httprpc Package httprpc provides goma httprpc implementation.
httprpc/authdb Package authdb implements authdb service for goma httprpc.
httprpc/bytestream Package bytestream implements bytestream for goma http.
httprpc/exec Package exec implements exec service for goma httprpc.
httprpc/execlog Package execlog implements log service for goma httprpc.
httprpc/file Package file implements file service for goma httprpc.
httprpc/settings Package settings implements settings service for goma httprpc.
log Package log provides logging mechanism for goma servers.
log/errorreporter Package errorreporter provides error reporting functionality.
profiler Package profiler provides convenient function to enable cloud profiler.
proto Package proto is top directory for proto packages.
proto/api
proto/auth
proto/backend
proto/cache
proto/command
proto/exec
proto/execlog
proto/file
proto/nsjail
proto/settings
remoteexec Package remoteexec provides proxy to remoteexec server.
remoteexec/cas Package cas manages content addressable storage.
remoteexec/datasource Package datasource provides data source from local file, bytes etc.
remoteexec/digest Package digest handles content digest for remote executon API, https://github.com/bazelbuild/remote-apis/blob/c1c1ad2c97ed18943adb55f06657440daa60d833/build/bazel/remote/execution/v2/remote_execution.proto#L633
remoteexec/merkletree Package merkletree operates on a merkle tree for remote execution API, https://github.com/bazelbuild/remote-apis/blob/c1c1ad2c97ed18943adb55f06657440daa60d833/build/bazel/remote/execution/v2/remote_execution.proto#L838 see https://en.Wikipedia.org/wiki/Merkle_tree
rpc Package rpc provides goma specific rpc features on gRPC.
rpc/grpctest Package grpctest provides a test server for unit tests that use gRPC.
server Package server provides functions for goma servers.
server/healthz Package healthz provides /healthz for grpc server.