Goma for Chromium contributors

This document describes how to install and use Goma. It is intended for early access for external Chromium contributors.

Getting started

This section explains the one-shot procedure to start using the Goma service. You need to do the following once you start using Goma.

System requirements

  • A x86-64 machine with at least 8GB of RAM.
  • Linux
  • You must have python 2.7 or later installed already.
  • You must have depot_tools installed already. Please make sure your PATH environment variable has depot_tools path.

Most development is done on Ubuntu (currently 16.04, Xenial Xerus). It might work on other distros, but they are mostly unsupported.

Please wait for invitation from Google

You can use the Goma service upon invitation from Google

We will gradually invite active external Chromium contributors to use the Goma service (i.e. using Goma backend server paid for by Google).

For contributors who has tryjob access, sign up the form. Then, follow up with Googlers you work together to nominate yourself. Note that this is a best-effort process. We do not guarantee when you will be invited.

The rest of the procedures will work after you are registered as a Goma user.

Login to Goma service

Please use goma_auth in depot_tools to login. To use Goma service, you must agree to our data usage policy.

$ goma_auth login

Note: goma_auth understands https_proxy environment variable.

How to build Chromium with Goma?

This section explains the typical workflow for using Goma.

Start compiler_proxy daemon

$ goma_ctl ensure_start

Note: goma_ctl understands https_proxy environment variable.

Build chromium using Goma

$ cd ${chromium_src}
$ gn gen out/Default --args="use_goma=true"

Or, execute gn args out/Default and add followings:

use_goma=true

Then, build chromium using Goma.

$ cd ${chromium_src}
$ autoninja -C out/Default

FAQ

How to use the latest Goma client?

If there is a new Goma client commit, the prebuilt Goma client in cipd repository will automatically be updated, but your installation won't be updated automatically.

To update your Goma installation, please make sure no program on your machine is using Goma. i.e. building chromium. Then, run goma_ctl update_hook to download and restart compiler_proxy.

$ goma_ctl update_hook

Known issues

compiler_proxy takes CPU after builds

compiler_proxy might take unnecessary CPU after build finished.

It's ok to restart compiler_proxy when it happens.

$ goma_ctl restart

or, stop if you don't need to use goma for a while.

$ goma_ctl ensure_stop

Don't forget to start goma before build.

$ goma_ctl ensure_start

Troubleshooting

goma_ctl ensure_start shows error: failed to connect to backend servers

  1. Please make sure you have logged in with an email address that you have registered.

    The following command shows which user is currently logged in. Please confirm that the email address shown is the same one that you had used to nominate yourself as a Goma user.

    $ goma_auth info
    

    This also shows your account is registered as a Goma user or not. If not, please file an issue in crbug.com with Infra>Goma component.

  2. Please make sure you do not set GOMA_* environment by yourself.

    The following command should not show anything.

    $ env | grep ^GOMA_
    

If all of above did not help, please file an issue in crbug.com with Infra>Goma component. Please include the following information:

  • output of cipd installed -root ${depot_tools_dir}/.cipd_bin
  • goma-report.tgz generated by goma_ctl report It contains all logs generated by goma client. TODO: explain what is shared and reason to share?

TODO: create template on crbug.com?