webrender hacking setup doc

hacking-setup.md

WebRender Hacking Setup

(not a tutorial for the innards, just the environment)

If you need help or have questions about any of this, please ask on #servo on irc.mozilla.org.

Rust

WebRender is written in the Rust programming language. There are a number of great resources for learning Rust, but you probably want to start with "The Book" and perhaps work through Rust by Example.

Setup

This document assumes that you have your preferred way of cloning git repositories from github, and that you have your platform's native compiler toolchain installed (e.g., Visual Studio 2015 on Windows).

First, obtain a current Rust setup. Use rustup.rs to get this going on all platforms.

1. Visit rustup.rs to obtain step 1 for your platform.
2. Install the nightly toolchain: rustup toolchain install nightly-msvc
3. Install the std lib sources (to make debugging much nicer): rustup component add rust-src
4. Make the nightly toolchain the default: rustup default nightly-msvc
5. To update the toolchain in the future: rustup update

If you prefer to develop using Visual Studio, check out the Visual Rust extension, or nightly versions from their github project.

Visual Studio Code also provides a great development environment (without debugger); check out the Rusty Code extension. (Newer versions of Rusty Code than what might be in the marketplace are likely going to give a better experience. Ask for help if you'd like to try these out.)

Finally, check out the WebRender sources from https://github.com/servo/webrender. Use whichever git your prefer (Visual Studio, VS Code, GitHub Desktop client, command line git, etc.).

Build

This step can be done through the various IDEs, but I'll show the command line steps because they are cross-platform. Inside the webrender checkout, there are a few subdirectories representing different components:

• webrender -- the core rendering backend targetting OpenGL
• webrender_traits -- the "front end" that decouples the backend from applications that use WebRender
• wrench -- a debugging and testing tool, with frame recording and replay capabilities (among others)
• sample -- a sample program that uses WebRender to display content

Build and run the sample:

1. cd webrender/sample
2. cargo build
3. cargo run -- note, the actual generated binary will be in ../target/debug/wr-sample[.exe]. You can run that directly as well.

Build and run wrench, this time in release mode:

1. cd webrender/wrench
2. cargo build --release
3. cargo run --release -- show res/test.yaml
4. While running, press h to show onscreen help; e.g., p to toggle the profiler display.
5. There are many more options; try cargo run -- --help (or ../target/release/wrench --help). One day soon there will be a wrench/README.md.

Hack

Some documentation for WebRender is available.

In general, after making changes, just cargo build again, or cargo run if using cargo to run (it'll rebuild if necessary).

To hack on WebRender by itself, you'll likely want to obtain a number of traces for replay via wrench. These can be built by someone else and sent to you, or you can create some yourself (if Servo can properly lay out the content) by building Servo and then running with the -Z wr-record flag to create a binary recording. That binary recording can then be replayed using wrench.

Issues, pull requests, etc. are all handled via github, using the normal mechanisms.