diff options
| -rw-r--r-- | docs/HACKING_QUICKSTART.md | 107 |
1 files changed, 54 insertions, 53 deletions
diff --git a/docs/HACKING_QUICKSTART.md b/docs/HACKING_QUICKSTART.md index d9e9c065909..6094e8b913c 100644 --- a/docs/HACKING_QUICKSTART.md +++ b/docs/HACKING_QUICKSTART.md @@ -5,25 +5,25 @@ It doesn't cover how Servo works or how to use Git effectively (see the [documentation](#documentation) section for those), but describes how to set up your environment to compile, run, and debug Servo. -* [Building Servo](#building-servo) -* [Running Servo](#running-servo) -* [mach](#mach) - * [mach and Servo options](#mach-and-servo-options) -* [Some basic Rust](#some-basic-rust) - * [Cargo and crates](#cargo-and-crates) - * [Working on a crate](#working-on-a-crate) -* [Editor support](#editor-support) - * [Visual Studio Code](#visual-studio-code) -* [Debugging](#debugging) - * [Logging](#logging) - * [println!()](#println) - * [Debugger](#debugger) -* [Tests](#tests) - * [Updating a test](#updating-a-test) - * [Add a new test](#add-a-new-test) - * [Debugging a test](#debugging-a-test) -* [Documentation](#documentation) -* [Ask questions](#ask-questions) +- [Building Servo](#building-servo) +- [Running Servo](#running-servo) +- [mach](#mach) + - [mach and Servo options](#mach-and-servo-options) +- [Some basic Rust](#some-basic-rust) + - [Cargo and crates](#cargo-and-crates) + - [Working on a crate](#working-on-a-crate) +- [Editor support](#editor-support) + - [Visual Studio Code](#visual-studio-code) +- [Debugging](#debugging) + - [Logging](#logging) + - [println!()](#println) + - [Debugger](#debugger) +- [Tests](#tests) + - [Updating a test](#updating-a-test) + - [Add a new test](#add-a-new-test) + - [Debugging a test](#debugging-a-test) +- [Documentation](#documentation) +- [Ask questions](#ask-questions) ## Building Servo @@ -35,15 +35,15 @@ Building Servo is quite easy. Install the prerequisites described in the [README There are three main build profiles, which you can build and use independently of one another: -* debug builds, which allow you to use a debugger (lldb) -* release builds, which are slower to build but more performant -* production builds, which are used for official releases only +- debug builds, which allow you to use a debugger (lldb) +- release builds, which are slower to build but more performant +- production builds, which are used for official releases only -| profile | mach option | optimised? | debug<br>info? | debug<br>assertions? | finds resources in<br>current working dir? | -|---|---|---|---|---|---| -| debug | `-d` | no | yes | yes | yes | -| release | `-r` | yes | no | yes(!) | yes | -| production | `--profile production` | yes | yes | no | no | +| profile | mach option | optimised? | debug<br>info? | debug<br>assertions? | finds resources in<br>current working dir? | +| ---------- | ---------------------- | ---------- | -------------- | -------------------- | ------------------------------------------ | +| debug | `-d` | no | yes | yes | yes | +| release | `-r` | yes | no | yes(!) | yes | +| production | `--profile production` | yes | yes | no | no | You can change these settings in a servobuild file (see [servobuild.example](../servobuild.example)) or in the root [Cargo.toml](../Cargo.toml). @@ -51,13 +51,13 @@ You can change these settings in a servobuild file (see [servobuild.example](../ The servo binary is located in `target/debug/servo` (or `target/release/servo`). You can directly run this binary, but we recommend using `./mach` instead: -``` shell +```shell ./mach run -d -- https://github.com ``` … is equivalent to: -``` shell +```shell ./target/debug/servo https://github.com ``` @@ -67,17 +67,17 @@ If you build with `-d`, run with `-d`. If you build with `-r`, run with `-r`. `mach` is a python utility that does plenty of things to make our life easier (build, run, run tests, update dependencies… see `./mach --help`). Beside editing files and git commands, everything else is done via `mach`. -``` shell +```shell ./mach run -d [mach options] -- [servo options] ``` -The `--` separates `mach` options from `servo` options. This is not required, but we recommend it. `mach` and `servo` have some options with the same name (`--help`, `--debug`), so the `--` makes it clear where options apply. +The `--` separates `mach` options from `servo` options. This is not required, but we recommend it. `mach` and `servo` have some options with the same name (`--help`, `--debug`), so the `--` makes it clear where options apply. ### mach and Servo options This guide only covers the most important options. Be sure to look at all the available mach commands and the servo options: -``` shell +```shell ./mach --help # mach options ./mach run -- --help # servo options ``` @@ -128,32 +128,33 @@ See [Cargo's documentation about Cargo.toml and Cargo.lock files](https://doc.ru As explained above, Servo depends on a lot of libraries, which makes it very modular. While working on a bug in Servo, you'll often end up in one of its dependencies. You will then want to compile your own version of the dependency (and maybe compiling against the HEAD of the library will fix the issue!). -For example, I'm trying to bring some cocoa events to Servo. The Servo window on Desktop is constructed with a library named [winit](https://github.com/rust-windowing/winit). winit itself depends on a cocoa library named [cocoa-rs](https://github.com/servo/cocoa-rs). When building Servo, magically, all these dependencies are downloaded and built for you. But because I want to work on this cocoa event feature, I want Servo to use my own version of *winit* and *cocoa-rs*. +For example, I'm trying to bring some cocoa events to Servo. The Servo window on Desktop is constructed with a library named [winit](https://github.com/rust-windowing/winit). winit itself depends on a cocoa library named [cocoa-rs](https://github.com/servo/cocoa-rs). When building Servo, magically, all these dependencies are downloaded and built for you. But because I want to work on this cocoa event feature, I want Servo to use my own version of _winit_ and _cocoa-rs_. This is how my projects are laid out: ``` ~/my-projects/servo/ -~/my-projects/mozjs/ +~/my-projects/cocoa-rs/ ``` -Both folder are git repositories. -To make it so that servo uses `~/my-projects/mozjs/`, first ascertain which version of the crate Servo is using and whether it is a git dependency or one from crates.io. +Both folder are git repositories. + +To make it so that servo uses `~/my-projects/cocoa-rs/`, first ascertain which version of the crate Servo is using and whether it is a git dependency or one from crates.io. -Both information can be found using, in this example, `./mach cargo pkgid mozjs_sys`(`mozjs_sys` is the actual crate name, which doesn't necessarily match the repo folder name). +Both information can be found using, in this example, `cargo pkgid cocoa`(`cocoa` is the name of the package, which doesn't necessarily match the repo folder name). -If the output is in the format `https://github.com/servo/mozjs#mozjs_sys:0.0.0`, you are dealing with a git dependency and you will have to edit the `~/my-projects/servo/Cargo.toml` file and add at the bottom: +If the output is in the format `https://github.com/servo/cocoa-rs#cocoa:0.0.0`, you are dealing with a git dependency and you will have to edit the `~/my-projects/servo/Cargo.toml` file and add at the bottom: -``` toml +```toml [patch] -"https://github.com/servo/mozjs#mozjs_sys:0.0.0" = { path = '../mozjs' } +"https://github.com/servo/cocoa-rs#cocoa:0.0.0" = { path = '../cocoa-rs' } ``` -If the output is in the format `https://github.com/rust-lang/crates.io-index#mozjs_sys#0.0.0`, you are dealing with a crates.io dependency and you will have to edit the `~/my-projects/servo/Cargo.toml` in the following way: +If the output is in the format `https://github.com/rust-lang/crates.io-index#cocoa#0.0.0`, you are dealing with a crates.io dependency and you will have to edit the `~/my-projects/servo/Cargo.toml` in the following way: -``` toml +```toml [patch] -"mozjs_sys:0.0.0" = { path = '../mozjs' } +"cocoa:0.0.0" = { path = '../cocoa-rs' } ``` Both will tell any cargo project to not use the online version of the dependency, but your local clone. @@ -167,14 +168,14 @@ For more details about overriding dependencies, see [Cargo's documentation](http Running plain `cargo` will cause problems! For example, you might get rust-analyzer extension errors about build scripts like -* The style crate requires enabling one of its 'servo' or 'gecko' feature flags and, in the 'servo' +- The style crate requires enabling one of its 'servo' or 'gecko' feature flags and, in the 'servo' case, one of 'servo-layout-2013' or 'servo-layout-2020'. -* (if you are on NixOS) thread 'main' panicked at 'called \`Result::unwrap()\` on an \`Err\` value: +- (if you are on NixOS) thread 'main' panicked at 'called \`Result::unwrap()\` on an \`Err\` value: "Could not run \`PKG_CONFIG_ALLOW_SYSTEM_CFLAGS=\\"1\\" PKG_CONFIG_ALLOW_SYSTEM_LIBS=\\"1\\" \\"pkg-config\\" \\"--libs\\" \\"--cflags\\" \\"fontconfig\\"\` -* (if you are on NixOS) [ERROR rust_analyzer::main_loop] FetchWorkspaceError: rust-analyzer failed to load workspace: Failed to load the project at /path/to/servo/Cargo.toml: Failed to read Cargo metadata from Cargo.toml file /path/to/servo/Cargo.toml, Some(Version { major: 1, minor: 74, patch: 1 }): Failed to run `cd "/path/to/servo" && "cargo" "metadata" "--format-version" "1" "--manifest-path" "/path/to/servo/Cargo.toml" "--filter-platform" "x86_64-unknown-linux-gnu"`: `cargo metadata` exited with an error: error: could not execute process `crown -vV` (never executed) +- (if you are on NixOS) [ERROR rust_analyzer::main_loop] FetchWorkspaceError: rust-analyzer failed to load workspace: Failed to load the project at /path/to/servo/Cargo.toml: Failed to read Cargo metadata from Cargo.toml file /path/to/servo/Cargo.toml, Some(Version { major: 1, minor: 74, patch: 1 }): Failed to run `cd "/path/to/servo" && "cargo" "metadata" "--format-version" "1" "--manifest-path" "/path/to/servo/Cargo.toml" "--filter-platform" "x86_64-unknown-linux-gnu"`: `cargo metadata` exited with an error: error: could not execute process `crown -vV` (never executed) This is because the rustflags (flags passed to the rust compiler) that standard `cargo` provides are different to what `./mach` uses, and so every time Servo is built using `cargo` it will undo all the @@ -220,7 +221,7 @@ but it wouldn’t hurt to try that if you still have problems. When enabling rust-analyzer’s proc macro support, you may start to see errors like -* proc macro \`MallocSizeOf\` not expanded: Cannot create expander for /path/to/servo/target/debug/deps/libfoo-0781e5a02b945749.so: unsupported ABI \`rustc 1.69.0-nightly (dc1d9d50f 2023-01-31)\` rust-analyzer(unresolved-proc-macro) +- proc macro \`MallocSizeOf\` not expanded: Cannot create expander for /path/to/servo/target/debug/deps/libfoo-0781e5a02b945749.so: unsupported ABI \`rustc 1.69.0-nightly (dc1d9d50f 2023-01-31)\` rust-analyzer(unresolved-proc-macro) This means rust-analyzer is using the wrong proc macro server, and you will need to configure the correct one manually. Use mach to query the current sysroot path, and copy the last line of output: @@ -247,14 +248,14 @@ Then configure either your sysroot path or proc macro server path in `.vscode/se Before starting the debugger right away, you might want to get some information about what's happening, how, and when. Luckily, Servo comes with plenty of logs that will help us. Type these 2 commands: -``` shell +```shell ./mach run -d -- --help ./mach run -d -- --debug help ``` A typical command might be: -``` shell +```shell ./mach run -d -- -i -y 1 --debug dump-style-tree /tmp/a.html ``` @@ -262,7 +263,7 @@ A typical command might be: On macOS, you can add some Cocoa-specific debug options: -``` shell +```shell ./mach run -d -- /tmp/a.html -- -NSShowAllViews YES ``` @@ -286,7 +287,7 @@ Use `RUST_BACKTRACE=1` to dump the backtrace when Servo panics. You will want to add your own logs. Luckily, many structures [implement the `fmt::Debug` trait](https://doc.rust-lang.org/std/fmt/#fmtdisplay-vs-fmtdebug), so adding: -``` rust +```rust println!("foobar: {:?}", foobar) ``` @@ -296,7 +297,7 @@ usually just works. If it doesn't, maybe some of foobar's properties don't imple To run the debugger: -``` shell +```shell ./mach run -d --debug -- -y 1 /tmp/a.html ``` @@ -304,7 +305,7 @@ This will start `lldb` on Mac, and `gdb` on Linux. From here, use: -``` shell +```shell (lldb) b a_servo_function # add a breakpoint (lldb) run # run until breakpoint is reached (lldb) bt # see backtrace |