webrender: the upstream home is a Mercurial folder, not this repository

The upstream home is a folder in mozilla-central

The first substantive paragraph is about where the code really lives. The upstream home for this code is the gfx/wr folder of the mozilla-central repository, hosted on Mercurial, and the GitHub repository is to be considered a downstream mirror.

The mirror is not identical, though. It carries additional metadata that does not exist upstream, and the metadata named is the GitHub wiki pages, which is where the few pages describing internals and conventions actually live.

That dictates the workflow. Improvements are generally to be submitted upstream in Gecko, and only those relevant to the Servo project or unsuitable for upstream may be accepted in the mirror. Readers who already know the mozilla-central contribution workflow are told that filing bugs in Bugzilla, against the Core product and the Graphics: WebRender component, and submitting patches there would be preferred.

So a bug reported here is a bug reported to a mirror, which is worth knowing before you file one.

The only tag here is named rustc-perf and is four years old

There is one release recorded for this repository, and it is not a WebRender release. It is tagged rustc-perf and dated 2022-03-28.

A tag named after a compiler benchmark run tells you what it was cut for, which is a performance comparison rather than a release. It also means there is no version of WebRender published from here, and no changelog tied to a version.

That is consistent with how the file says to consume the code. Consumers do not depend on a published crate; they patch a git source with local paths. So there is nothing to upgrade to and nothing to pin, and a change lands by editing the manifest in the consuming project.

The only history kept in the repository is the lockfile and the upstream record in mozilla-central, which means the version a given build used has to be read out of the consuming tree rather than out of a tag here.

Consumers patch a git source with two local paths

The documented way to use a local copy with Servo is to edit the Servo build's Cargo.toml and add a patch block at the end of the file:

[patch."https://github.com/servo/webrender"]
"webrender" = { path = "<path>/webrender" }
"webrender_api" = { path = "<path>/webrender_api" }

Two crates are redirected, the renderer and its API. Everything else in the tree is pulled normally, and the build then proceeds as usual.

The same file describes the other direction of the flow. After updating shaders in WebRender, you go to the Servo directory, run ./mach update-cargo -p webrender, and open a pull request against Servo.

So there are two distinct paths for a change: one for using local code, and one for shipping an update upward. Neither involves a version number, because there is no version to move.

Both profiles abort on panic and release builds keep debug info

The workspace profile section is short and worth reading twice. The release profile sets debug to true, which keeps debug information in release builds, and sets the panic strategy to abort. The development profile sets panic to abort as well, with no debug setting of its own.

Aborting rather than unwinding has a consequence that matters for a renderer. There is no stack unwinding on a panic, so a fault inside a shader compilation path, a glyph rasterization path or a texture upload has nowhere to go but out of the process. For a library embedded in a browser that is a deliberate trade: no unwinding cost on the hot path, at the price of a crash instead of a recoverable error.

Keeping debug information in release builds points the other way, toward being able to symbolise a crash after the fact, which is consistent with a component that is expected to run inside someone else's process and be diagnosed from outside.

Two dependencies are patched, one of them from a personal fork

The workspace patches two things from crates.io.

The first is a local path. A crate named firefox-on-glean is redirected to a directory called fog in the repository, which is a vendored copy rather than a published version, and it sits at the top level of the tree rather than inside the crates directory.

The second is a fork. The glutin version, which is the windowing library, is redirected to a git repository on a branch named wr, and the comment above it says it is a patched version that works on Android. The version requirement stays at 0.28 while the source moves, so the manifest claims compatibility with a release it is not actually using.

There is also a single pinned dependency elsewhere in the workspace, glean at an exact version of 61.0.0 with an equality sign in front of it, which is the strictest form of version pinning available and stops any other crate in the graph from choosing a different one.

Tests run on OSMesa, and font libraries still change the result

Rendering tests are not run against a real GPU. They run using OSMesa, so that results are consistent across platforms, and the file immediately qualifies that: there may still be differences depending on the font libraries on your system. A linked gist is offered as a way to make the text tests useful on a particular distribution, Fedora named as the example.

So the consistency guarantee covers the rasterisation path and not the text path, which is where two Linux machines diverge most often.

The tree explains why a software path exists at all. There is a swgl directory at the top level, a software GL implementation, and the workspace manifest raises the optimisation level for the glsl package in both the development and release profiles, with a comment saying that optimising glsl more makes a big difference in swgl build times. The shader translation step is therefore slow enough to be worth compiling at a higher optimisation level even while developing.

Seven top-level directories are not workspace members

The workspace manifest lists five members: examples, webrender, webrender_api, wrench, and one subdirectory of example-compositor.

The top level of the repository holds considerably more than that. Besides those five there is fog, swgl, glsl-to-cxx, peek-poke, webrender_build, wr_glyph_rasterizer and wr_malloc_size_of, plus ci-scripts and the various configuration files.

Those directories are path dependencies rather than members, which is why they can sit at the root without joining the workspace. Two of them explain a lot about how tightly this code is coupled to Mozilla's own tree. peek-poke is a Gecko testing utility, and servo-tidy.toml is Servo's configuration file rather than a Rust one. glsl-to-cxx exists because the shaders are shared with a C++ codebase and have to be translated at build time.

The continuous integration configuration is a Taskcluster file rather than a GitHub workflow, which is the other sign of where this code is expected to be built.

Editorial conclusion

WebRender is the right thing to read if you want to see how a browser composes 2D content on the GPU, because the workspace separates the API surface, the renderer, the glyph rasterizer and the shader build step into distinct crates. Three things to know before you change anything in it. Contributions are expected to land in mozilla-central first, so a patch here may be rejected upstream and Bugzilla is the stated channel for bugs. There is no version to pin: the only tag is named rustc-perf and predates the current work by years, so consumers patch a git path rather than depend on a release. And both build profiles abort on panic, which means a fault in a shader or glyph path takes the whole process down rather than unwinding, so reproduce changes under a debugger rather than hoping for a catch.

Frequently asked questions

Official sources

1. License: MPL-2.0
2. Project website
3. README
4. Releases
5. servo/webrender on GitHub