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.
  • You must have python 2.7 installed already.
  • You must have depot_tools installed already.

Most development is done on Ubuntu (currently 14.04, Trusty Tahr). There are some instructions for other distros below, 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).

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

Download prebuilt Goma client

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

Note: the package with ref=latest is chosen by default. However, we may use other cipd ref, and provide the script to automate Goma installation and update in the future.

Login to Goma service

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

$ ${HOME}/goma/goma_auth.py login

Note: goma_auth.py understands https_proxy environment variable.

How to build Chromium with Goma?

This section explains the typical workflow for using Goma.

Start compiler_proxy daemon

$ ${HOME}/goma/goma_ctl.py ensure_start

Note: goma_ctl.py understands https_proxy environment variable.

Build chromium using Goma

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

Or, enable Goma by setting the GN arg 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, stop compiler_proxy, update Goma client, and restart compiler_proxy.

$ ${HOME}/goma/goma_ctl.py ensure_stop
$ cipd install infra/goma/client/linux-amd64 -root ${HOME}/goma
$ ${HOME}/goma/goma_ctl.py ensure_start

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}/goma/goma_ctl.py restart

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

$ ${GOMA}/goma/goma_ctl.py ensure_stop

Don't forget to start goma before build.

$ ${GOMA}/goma/goma_ctl.py ensure_start

Troubleshooting

goma_ctl.py 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.

    $ ${HOME}/goma_auth.py info
    
  2. Plese make sure you are registered as a Goma user.

    TODO: write this. We do not have available backend now.

  3. 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 $HOME/goma
  • goma-report.tgz generated by $HOME/goma/goma_ctl.py report It contains all logs generated by goma client. TODO: explain what is shared and reason to share?

TODO: create template on crbug.com?