Auto merge of #14187 - emilio:rr-docs, r=jdm

Add a few minimal debugging docs.

r? @jdm (or anyone else)

<!-- Reviewable:start -->
---
This change is [<img src="https://reviewable.io/review_button.svg" height="34" align="absmiddle" alt="Reviewable"/>](https://reviewable.io/reviews/servo/servo/14187)
<!-- Reviewable:end -->

components/layout/Cargo.toml

@@ -27,7 +27,7 @@ log = "0.3.5"
 msg = {path = "../msg"}
 net_traits = {path = "../net_traits"}
 ordered-float = "0.2.2"
-parking_lot = {version = "0.3.3", features = ["nightly"]}
+parking_lot = "0.3.3"
 plugins = {path = "../plugins"}
 profile_traits = {path = "../profile_traits"}
 range = {path = "../range"}

components/style/Cargo.toml

@@ -17,7 +17,7 @@ gecko = ["nsstring_vendor"]
 servo = ["serde/unstable", "serde", "serde_derive", "heapsize_derive",
          "style_traits/servo", "app_units/plugins", "servo_atoms", "html5ever-atoms",
          "cssparser/heap_size", "cssparser/serde-serialization",
-         "url/heap_size", "plugins", "parking_lot/nightly"]
+         "url/heap_size", "plugins"]
 testing = []
 
 [dependencies]

docs/HACKING_QUICKSTART.md

@@ -260,6 +260,10 @@ If you need to create a new test file, it should be located in `tests/wpt/mozill
 ./mach test-wpt --manifest-update
 ```
 
+### Debugging a test
+
+See the [debugging guide](./debugging.md) to get started in how to debug Servo.
+
 ## Documentation:
 
 - Servo's directory structure: [ORGANIZATION.md](./ORGANIZATION.md)

docs/debugging.md

@@ -0,0 +1,70 @@
+# Servo debugging guide
+
+There are a few ways to debug Servo. `mach` supports a `--debug` flag that
+searches a suitable debugger for you and runs servo with the appropriate
+arguments under it:
+
+```
+./mach run --debug test.html
+```
+
+You can also specify an alternative debugger using the `--debugger` flag:
+
+```
+./mach run --debugger=my-debugger test.html
+```
+
+You can also, of course, run directly your debugger on the Servo binary:
+
+```
+$ gdb --args ./target/debug/servo test.html
+```
+
+## Debugging SpiderMonkey.
+
+You can build Servo with a debug version of SpiderMonkey passing the
+`--debug-mozjs` flag to `./mach build`.
+
+Note that this sometimes can cause problems when an existing build exists, so
+you might have to delete the `mozjs` build directory, or run `./mach clean`
+before your first `--debug-mozjs` build.
+
+## Debugging Servo with [rr][rr].
+
+To record a trace under rr you can either use:
+
+```
+$ ./mach run --debugger=rr testcase.html
+```
+
+Or:
+
+```
+$ rr record ./target/debug/servo testcase.html
+```
+
+### Running WPT tests under rr's chaos mode.
+
+Matt added a mode to Servo's testing commands to record traces of Servo running
+a test or set of tests until the result is unexpected.
+
+To use this, you can pass the `--chaos` argument to `mach test-wpt`:
+
+```
+$ ./mach test-wpt --chaos path/to/test
+```
+
+Note that for this to work you need to have `rr` in your `PATH`.
+
+Also, note that this might generate a lot of traces, so you might want to delete
+them when you're done. They're under `$HOME/.local/share/rr`.
+
+### Known gotchas
+
+If you use a Haswell processor that supports Hardware Lock Ellision, rr might
+not work for you. There's a `rr` [bug][rr-bug] open about this. Until that gets
+fixed, you can ensure that the `parking_lot` dependency isn't built with the
+`nightly` feature, which as of this writing is the only dependency that uses it.
+
+[rr]: http://rr-project.org/
+[rr-bug]: https://github.com/mozilla/rr/issues/1883

python/servo/post_build_commands.py

@@ -59,6 +59,10 @@ class PostBuildCommands(CommandBase):
         env = self.build_env()
         env["RUST_BACKTRACE"] = "1"
 
+        # Make --debugger imply --debug
+        if debugger:
+            debug = True
+
         if android is None:
             android = self.config["build"]["android"]