Platform/GFX/Quantum Render

What is it

The goal of the Quantum Render project is to take the WebRender compositor in Servo and embed it in Firefox. It will replace Gecko's existing compositor, interfacing with Gecko's main-thread layout code. As WebRender is written in Rust and uses a very different design approach, we expect to get stability and performance benefits from this switch.

Vital stats

Canonical code repository: https://hg.mozilla.org/projects/graphics
Git mirror: https://github.com/mozilla/gecko-projects/tree/graphics
TreeHerder: https://treeherder.mozilla.org/#/jobs?repo=graphics
Bugzilla Component: Core :: Graphics: WebRender
Tracking metabug: bug 1311790
Mailing list: dev-tech-gfx@lists.mozilla.org
IRC channel: #gfx
Project owner: Milan Srekovic

Getting the code

Using mercurial

To clone the repo from scratch, run this:

 hg clone https://hg.mozilla.org/projects/graphics

Or if you have an existing mozilla repo, add this to your .hgrc file:

 [paths]
 graphics = ssh://hg.mozilla.org/projects/graphics/

and pull using hg pull graphics

Using git

See the README at https://github.com/mozilla/gecko-projects, use "graphics" as the BRANCH

Build instructions

Once you have the code, see the README.webrender file in the root directory for build instructions. This can also be seen online at https://hg.mozilla.org/projects/graphics/file/tip/README.webrender. Builds are currently supported on Linux 64-bit, Mac OS X 64-bit, and Windows 64-bit. Android support is being worked on in bug 1323612.

Testing third-party rust library changes

Sometimes when hacking on Quantum Render, you'll need to make a change to one of the upstream dependencies of the webrender library (say for example euclid). However, you may need to test out your changes in the QR build. The way to do this is not obvious, because the QR build uses the vendored copy of euclid (in third_party/rust/euclid) which you can't directly modify without violating the checksum checks. Instead, what you need to do is this:

• First we make a copy of the vendored euclid repo

 cd $MOZILLA_ROOT/third_party/rust
 cp -R euclid euclid_modified

• Then, make your desired changes to euclid_modified.
• Then, we need to tell the build system to use euclid_modified instead of euclid. Note that for this to work, the version numbers in the Cargo.toml files should be the same in euclid and euclid_modified. The following steps add a [replace] section to the top-level libgkrust Cargo.toml file to use the modified euclid. See http://doc.crates.io/manifest.html#the-replace-section for details. You'll need to replace the 0.10.3 in the command below with whatever the library version in (as of this writing euclid is at v0.10.3 in the graphics repo).

 cd $MOZILLA_ROOT/toolkit/library/rust/
 echo -e '[replace]\n"euclid:0.10.3" = { path = "../../../third_party/rust/euclid_modified" }" >> Cargo.toml
 cargo update -p euclid # This updates Cargo.lock

• And then build with your modified euclid:

 cd $MOZILLA_ROOT
 mach build

Hacking

There are lots of places to help hack on Quantum Render. See the sections below for some info on where to get started.

On WebRender

A good overview of WebRender and what it is can be found in this blog post. WebRender is developed as a standalone library in the WebRender github repo. Look through the issues list to find things to work on.

On Gecko integration

If you are familiar with the way Gecko normally works, the Quantum Render changes should be relatively straightforward. Instead of using a ClientLayerManager, we create a WebRenderLayerManager instance. This layer manager creates its own layer instances, and when those layers have their Render() function called, they generate WebRender-specific commands. These commands are sent over the PWebRenderBridge IPDL channel, which is conceptually similar to PLayerTransaction in Gecko. The commands are received in WebRenderBridgeParent which interprets the messages, and talks to the core WebRender library using the API in webrender_ffi.h (via various wrapper abstractions in gfx/webrender_bindings/). The API is implemented in the webrender_bindings crate, which is written in Rust.

Look through open unassigned bugs (with no open dependencies) in the WebRender bugzilla component to find things to work on.

On reftests

Many of the existing gecko reftests (over 13000 of them) are passing with Quantum Render. However, there are still around 150 failing reftests. These are listed in this Google sheet. You're welcome to work on getting these passing - please follow the procedure below:

• Identify a single reftest you wish to work on. Try to pick one that sounds unrelated to other reftests that people are working on, because often one patch will fix multiple related reftests.
• File a bug for that reftest, and mark it as blocking bug 1322815 (webrender-reftests).
• Update the Google sheet with the bug number and your name.
• Work on the fix. The best way to do this is to remove the fails-if or skip-if annotation in your local checkout and run the reftest using mach reftest. Debug and fix as needed. Note that you can likely work on the bug on Windows/OS X locally, but we only run the tests on Linux in automation. So for best results, prefer working on Linux locally when possible.
• If you need to do try pushes, use syntax try: -b do -p linux64-qr -u all[linux64-qr] -t none. You should do at least one try push after writing your fix to verify it works in automation, as well as to identify any other tests that are fixed by your patch. Make sure to update the annotations for all newly-passing tests as part of your final commit. Try not to introduce regressions, although breaking a small number of tests to make a larger number pass might be acceptable.
• Land your fix with pre- or post-review as appropriate.

In general, tests that are marked skip-if(webrender) are the worst, because they cause the reftest run to crash or hang and prevent other reftests from running. Slightly better than this are the random-if(webrender) tests - these can intermittently fail or pass, and so mean that there is a race condition somewhere. Slighly better than this are the fail-if(webrender) tests - these fail, but at least they do so consistently. Best of all are the ones with no webrender annotation at all, which means they behave the same as a Gecko build would.

Committing changes

The process for making changes is very similar to that for integration branches like inbound. File a bug in the WebRender component, attach patches, get review, push to the graphics repo. However, we also allow using an "accelerated" workflow which allows us to move faster by commiting first and getting review afterwards. The process is basically the same as the regular workflow (attach patches to bug via MozReview or uploading attachments, flag people for review), except you can land your patches before the review is granted. If you do land patches before review is granted, append a "?" to the reviewer string (e.g. "r=kats?") to indicate that it will be reviewed post-landing. Note that there is also a dummy bugzilla account for the entire graphics team (search for ":gfx"). Flagging this account as the reviewer indicates that you don't care who does the review, and anybody in the graphics team can do it. Members of the graphics team are expected to have the :gfx account on their user watchlist so they will see review requests to the team.

Try syntax

You can (and are encouraged to) push changes to tryserver to test them out before landing them in the graphics branch. You can use normal trychooser syntax, with the following extra platforms for the Quantum Render builds:

• linux64-qr - Quantum Render builds on Linux (always 64-bit)
• macosx64-qr - Quantum Render builds on OS X (always 64-bit)
• win64-qr - Quantum Render builds on Windows (always 64-bit)

So, for example, to build all the desktop 64-bit builds with and without webrender, you could use this trychooser syntax:

 try: -b do -p macosx64,macosx64-qr,linux64,linux64-qr,win64,win64-qr -u none -t none

Or to run all the test jobs on Linux QR builds:

 try: -b do -p linux64-qr -u all[linux64-qr] -t none

Sheriffing

Currently the graphics repo is self-managed - that is, the graphics team members are responsible for doing their own sheriffing - this includes starring failures, backing out of bad commits, doing merges, etc. Currently the graphics branch is NOT being merged to m-c; however, we are regularly merging from m-c to the graphics branch (see section below). In particular this means that QuantumRender-specific changes should land on the graphics branch and not on other integration branches.

We do have a pulsebot instance watching commits to the graphics repo, and it will automatically close the associated bug with a comment pointing to the commits. It will also report commits to #gfx.

Starring failures

In general we want to try and keep zero unstarred failures on the graphics branch. Most failures are pre-existing intermittents, but we should star them anyway in order to make sure we didn't introduce new failures or make something perma-fail. Oftentimes there will be random one-off failures or new failures that come in from m-c which we can mostly ignore (but still need to star). Starring failures is basically a black art - if in doubt about what to do with a failure, ask one of the m-c sheriffs or ping kats in #gfx who is currently doing most of the sheriff stuff.

Merging from mozilla-central

The following commands (on a m-c mercurial clone which has the graphics repo as an additional upstream path) will do a merge from m-c:

  hg update graphics       # switch to graphics branch
  hg pull -u graphics      # get latest graphics changesets
  hg pull central          # get latest m-c changesets
  hg merge central         # perform a merge. you may get prompted to resolve conflicts in this step
  hg commit -m "Merge m-c to graphics"  # commit the merge
  mach build               # ensure that the merge builds properly, make additional commits as needed
  hg push graphics -r tip  # push the merge

Note that changes in m-c (code changes, or addition of new reftests) might cause failures in QR reftest jobs after merging over to the graphics branch. The person doing the merge is responsible for keeping an eye out for these failures. In the interest of keeping the tree green, these failures can be dealt with by just updating the reftest.list files as necessary (add skip-if(webrender) for crashing tests, fails-if(webrender) for failing tests, etc.) and also updating the reftest spreadsheet with new failures.

Automation

The graphics branch currently runs all the usual tests (i.e. jobs that are run on mozilla-central) on each push. In addition, it also runs some new jobs specific to the Quantum Render code. Specifically, it runs 64-bit build jobs with --enable-webrender set, for Linux, OS X, and Windows. Both debug and opt builds are created. These can be seen on the graphics TreeHerder page in their own rows labelled with "qr" or "QuantumRender". The Linux QR builds also runs some reftest jobs (see the section #On_reftests above).

Further reading

There is more information at the following locations:

• https://public.etherpad-mozilla.org/p/gfx