vvuk · December 7, 2021 11:50 · Dec 13, 2016 · Dec 13, 2016 · Dec 13, 2016
diff --git a/hacking-setup.md b/hacking-setup.md
@@ -25,17 +25,20 @@ Finally, check out the WebRender sources from `https://github.com/servo/webrende
 
 ## 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`

diff --git a/hacking-setup.md b/hacking-setup.md
@@ -10,6 +10,7 @@ WebRender is written in the [Rust](https://rust-lang.org) programming language.
 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](https://rust-lang.org) setup.  Use [rustup.rs](https://rustup.rs) to get this going on all platforms.
+
 1. Visit [rustup.rs](https://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`

diff --git a/hacking-setup.md b/hacking-setup.md
@@ -0,0 +1,53 @@
+# 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](https://rust-lang.org) programming language.  There are a number of [great resources](https://www.rust-lang.org/en-US/documentation.html) for learning Rust, but you probably want to start with ["The Book"](https://doc.rust-lang.org/book/) and perhaps work through [Rust by Example](http://rustbyexample.com/).
+
+## 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](https://rust-lang.org) setup.  Use [rustup.rs](https://rustup.rs) to get this going on all platforms.
+1. Visit [rustup.rs](https://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](https://marketplace.visualstudio.com/items?itemName=vosen.VisualRust) extension, or nightly versions from [their github project](https://github.com/PistonDevelopers/VisualRust).
+
+[Visual Studio Code](https://code.visualstudio.com/) also provides a great development environment (without debugger); check out the [Rusty Code](https://marketplace.visualstudio.com/items?itemName=saviorisdead.RustyCode) 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](https://doc.servo.org/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](https://servo.org) 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.
+
+