Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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 -->
- Loading branch information
Showing
5 changed files
with
80 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters