Skip to content

Commit 34d9be7

Browse files
delandelan
authoredJul 9, 2024
Update in-tree docs to point to the new book (servo#32743)
* Update in-tree docs to point to the new book * Revive build setup section in README as quickstart guide * Apply feedback about titles
1 parent 72e6a1f commit 34d9be7

12 files changed

+63
-1413
lines changed
 

‎CONTRIBUTING.md

+2-89
Original file line numberDiff line numberDiff line change
@@ -1,92 +1,5 @@
11
# Contributing to Servo
22

3-
Servo welcomes contribution from everyone. Here are the guidelines if you are
4-
thinking of helping us:
5-
6-
7-
## Contributions
8-
9-
Contributions to Servo or its dependencies should be made in the form of GitHub
10-
pull requests. Each pull request will be reviewed by a core contributor
11-
(someone with permission to land patches) and either landed in the main tree or
12-
given feedback for changes that would be required. All contributions should
13-
follow this format, even those from core contributors.
14-
15-
Should you wish to work on an issue, please claim it first by commenting on
16-
the GitHub issue that you want to work on it. This is to prevent duplicated
17-
efforts from contributors on the same issue.
18-
19-
Head over to [Servo Starters](https://starters.servo.org/) to find
20-
good tasks to start with. If you come across words or jargon that do not make
21-
sense, please check [the glossary](docs/glossary.md) first. If there's no
22-
matching entry, please make a pull request to add one with the content `TODO`
23-
so we can correct that!
24-
25-
See [`HACKING_QUICKSTART.md`](docs/HACKING_QUICKSTART.md) for more information
26-
on how to start working on Servo.
27-
28-
## Pull request checklist
29-
30-
- Branch from the main branch and, if needed, rebase to the current main branch
31-
before submitting your pull request. If it doesn't merge cleanly with main
32-
you may be asked to rebase your changes.
33-
34-
- Commits should be as small as possible, while ensuring that each commit is
35-
correct independently (i.e., each commit should compile and pass tests).
36-
37-
- Commits should be accompanied by a Developer Certificate of Origin
38-
(http://developercertificate.org) sign-off, which indicates that you (and
39-
your employer if applicable) agree to be bound by the terms of the
40-
[project license](LICENSE). In git, this is the `-s` option to `git commit`.
41-
42-
- If your patch is not getting reviewed or you need a specific person to review
43-
it, you can @-reply a reviewer asking for a review in the pull request or a
44-
comment, or you can ask for a review in [the Servo chat](https://servo.zulipchat.com/).
45-
46-
- Add tests relevant to the fixed bug or new feature. For a DOM change this
47-
will usually be a web platform test; for layout, a reftest. See our [testing
48-
guide](https://github.com/servo/servo/wiki/Testing) for more information.
49-
50-
For specific git instructions, see [GitHub workflow 101](https://github.com/servo/servo/wiki/Github-workflow).
51-
52-
## Running tests in pull requests
53-
54-
When you push to a pull request, GitHub automatically checks that your changes have no compilation, lint, or tidy errors.
55-
56-
To run unit tests or Web Platform Tests against a pull request, add one or more of the labels below to your pull request. If you do not have permission to add labels to your pull request, add a comment on your bug requesting that they be added.
57-
58-
| Label | Effect |
59-
|---|---|
60-
| `T-full` | Unit tests: Linux, macOS, Windows<br>Layout tests: Linux, macOS<br>Legacy layout tests: Linux, macOS |
61-
| `T-linux-wpt-2013` | Unit tests: Linux<br>Legacy layout tests: Linux |
62-
| `T-linux-wpt-2020` | Unit tests: Linux<br>Layout tests: Linux |
63-
| `T-macos` | Unit tests: macOS |
64-
| `T-windows` | Unit tests: Windows |
65-
66-
## AI contributions
67-
68-
Contributions must not include content generated by large language models or other probabilistic tools, including but not limited to Copilot or ChatGPT. This policy covers code, documentation, pull requests, issues, comments, and any other contributions to the Servo project.
69-
70-
For now, we’re taking a cautious approach to these tools due to their effects — both unknown and observed — on project health and maintenance burden. This field is evolving quickly, so we are open to revising this policy at a later date, given proposals for particular tools that mitigate these effects. Our rationale is as follows:
71-
72-
**Maintainer burden:** Reviewers depend on contributors to write and test their code before submitting it. We have found that these tools make it easy to generate large amounts of plausible-looking code that the contributor does not understand, is often untested, and does not function properly. This is a drain on the (already limited) time and energy of our reviewers.
73-
74-
**Correctness and security:** Even when code generated by AI tools does seem to function, there is no guarantee that it is correct, and no indication of what security implications it may have. A web browser engine is built to run in hostile execution environments, so all code must take into account potential security issues. Contributors play a large role in considering these issues when creating contributions, something that we cannot trust an AI tool to do.
75-
76-
**Copyright issues:** Publicly available models are trained on copyrighted content, both accidentally and intentionally, and their output often includes that content verbatim. Since the legality of this is uncertain, these contributions may violate the licenses of copyrighted works.
77-
78-
**Ethical issues:** AI tools require an unreasonable amount of energy and water to build and operate, their models are built with heavily exploited workers in unacceptable working conditions, and they are being used to undermine labor and justify layoffs. These are harms that we do not want to perpetuate, even if only indirectly.
79-
80-
## Conduct
81-
82-
Servo Code of Conduct is published at <https://servo.org/coc/>.
83-
84-
## Communication
85-
86-
Servo contributors frequent the [Servo Zulip chat](https://servo.zulipchat.com/).
87-
88-
## Technical Steering Committee
89-
90-
Technical oversight of the Servo Project is provided by the
91-
[Technical Steering Committee](https://github.com/servo/project/blob/main/governance/tsc/README.md).
3+
Moved to the Servo book:
924

5+
- [Contributing to Servo](https://book.servo.org/contributing.html)

‎README.md

+28-181
Original file line numberDiff line numberDiff line change
@@ -4,75 +4,44 @@ Servo is a prototype web browser engine written in the
44
[Rust](https://github.com/rust-lang/rust) language. It is currently developed on
55
64-bit macOS, 64-bit Linux, 64-bit Windows, and Android.
66

7-
Servo welcomes contribution from everyone. See
8-
[`CONTRIBUTING.md`](CONTRIBUTING.md) and [`HACKING_QUICKSTART.md`](docs/HACKING_QUICKSTART.md)
9-
for help getting started.
7+
Servo welcomes contribution from everyone. Check out [The Servo Book](https://book.servo.org) to get started, or go to [servo.org](https://servo.org/) for news and guides.
108

11-
Visit the [Servo Project page](https://servo.org/) for news and guides.
9+
## Getting started
1210

13-
## Getting Servo
14-
15-
``` sh
16-
git clone https://github.com/servo/servo
17-
cd servo
18-
```
19-
20-
- Your CARGO_HOME needs to point to (or be in) the same drive as your
21-
Servo repository ([#28530](https://github.com/servo/servo/issues/28530)).
22-
- The Servo repository is big! If you have an unreliable network connection, consider
23-
[making a shallow clone](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/).
24-
25-
26-
## Build Setup
27-
28-
* [macOS](#macos)
29-
* [Linux](#Linux)
30-
* [Windows](#windows)
31-
* [Android](https://github.com/servo/servo/wiki/Building-for-Android)
32-
33-
If these instructions fail or you would like to install dependencies
34-
manually, try the [manual build setup][manual-build].
11+
For more detailed build instructions, see the Servo book under [Setting up your environment](https://book.servo.org/hacking/setting-up-your-environment.html), [Building Servo](https://book.servo.org/hacking/building-servo.html), and [Building for Android](https://book.servo.org/hacking/building-for-android.html).
3512

3613
### macOS
3714

38-
- Ensure that the version showed by `python --version` is >= 3.10:
39-
- Install [Xcode](https://developer.apple.com/xcode/)
40-
- Install [Homebrew](https://brew.sh/)
41-
- Run `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`. Ensure that `rust`
42-
and `cargo` are available commands &mdash; you may need to restart your shell.
43-
- Run `./mach bootstrap`<br/>
44-
*Note: This will install the recommended version of GStreamer globally on your system.*
15+
- Download and install [`python`](https://www.python.org/downloads/macos/), [Xcode](https://developer.apple.com/xcode/), and [`brew`](https://brew.sh/)
16+
- Install `rustup`: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
17+
- Restart your shell to make sure `cargo` is available
18+
- Install the other dependencies: `./mach bootstrap`
19+
- Build servoshell: `./mach build`
4520

4621
### Linux
4722

48-
- Run `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`. Ensure that `rust`
49-
and `cargo` are available commands &mdash; you may need to restart your shell.
50-
- Install Python (version >= 3.10):
51-
- **Debian-like:** Run `sudo apt install python3-pip python3-venv`
52-
- **Fedora:** Run `sudo dnf install python3 python3-pip python3-devel`
53-
- **Arch:** Run `sudo pacman -S --needed python python-pip`
54-
- **Gentoo:** Run `sudo emerge dev-python/pip`
55-
- Run `./mach bootstrap`
23+
- Install `curl` and `python`:
24+
- Arch: `sudo pacman -S --needed curl python python-pip`
25+
- Debian, Ubuntu: `sudo apt install curl python3-pip python3-venv`
26+
- Fedora: `sudo dnf install curl python3 python3-pip python3-devel`
27+
- Gentoo: `sudo emerge net-misc/curl dev-python/pip`
28+
- Install `rustup`: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
29+
- Restart your shell to make sure `cargo` is available
30+
- Install the other dependencies: `./mach bootstrap`
31+
- Build servoshell: `./mach build`
5632

5733
### Windows
5834

59-
- Download and run [`rustup-init.exe`](https://win.rustup.rs/)
60-
- Make sure to select *Quick install via the Visual Studio Community
61-
installer* or otherwise install Visual Studio 2022.
62-
- In the *Visual Studio Installer* ensure the following components are installed for Visual Studio 2022:
63-
- **Windows 10 SDK (10.0.19041.0)** (`Microsoft.VisualStudio.Component.Windows10SDK.19041`)
64-
- **MSVC v143 - VS 2022 C++ x64/x86 build tools (Latest)** (`Microsoft.VisualStudio.Component.VC.Tools.x86.x64`)
65-
- **C++ ATL for latest v143 build tools (x86 & x64)** (`Microsoft.VisualStudio.Component.VC.ATL`)
66-
- **C++ MFC for latest v143 build tools (x86 & x64)** (`Microsoft.VisualStudio.Component.VC.ATLMFC`)
67-
- Install [chocolatey](https://chocolatey.org/)
68-
- Install [Python 3.11](https://www.python.org/downloads/windows/)
69-
- Run `mach bootstrap`
70-
+ *This will install CMake, Git, and Ninja via choco in an
71-
Administrator console. Allow the scripts to run and once
72-
the operation finishes, close the new console.*
73-
- Run `refreshenv`
74-
75-
See also [Windows Troubleshooting Tips][windows-tips].
35+
- Download and install [`python`](https://www.python.org/downloads/windows/), [`choco`](https://chocolatey.org/install#individual), and [`rustup`](https://win.rustup.rs/)
36+
- Be sure to select *Quick install via the Visual Studio Community installer*
37+
- In the Visual Studio Installer, ensure the following components are installed:
38+
- **Windows 10 SDK (10.0.19041.0)** (`Microsoft.VisualStudio.Component.Windows10SDK.19041`)
39+
- **MSVC v143 - VS 2022 C++ x64/x86 build tools (Latest)** (`Microsoft.VisualStudio.Component.VC.Tools.x86.x64`)
40+
- **C++ ATL for latest v143 build tools (x86 & x64)** (`Microsoft.VisualStudio.Component.VC.ATL`)
41+
- **C++ MFC for latest v143 build tools (x86 & x64)** (`Microsoft.VisualStudio.Component.VC.ATLMFC`)
42+
- Restart your shell to make sure `cargo` is available
43+
- Install the other dependencies: `.\mach bootstrap`
44+
- Build servoshell: `.\mach build`
7645

7746
### Android
7847

@@ -94,126 +63,4 @@ See also [Windows Troubleshooting Tips][windows-tips].
9463
"platforms;android-33" \
9564
"system-images;android-33;google_apis;x86_64"
9665
```
97-
For information about building and running the Android build, see
98-
the [Android documentation][android-docs].
99-
100-
## Building
101-
102-
Servo is built with [Cargo](https://crates.io/), the Rust package manager.
103-
We also use Mozilla's Mach tools to orchestrate the build and other tasks.
104-
You can call Mach like this:
105-
106-
On Unix systems:
107-
```
108-
./mach [command] [arguments]
109-
```
110-
On Windows Commandline:
111-
```
112-
mach.bat [command] [arguments]
113-
```
114-
The examples below will use Unix, but the same applies to Windows.
115-
116-
### The Rust compiler
117-
118-
Servo's build system uses rustup.rs to automatically download a Rust compiler.
119-
This is a specific version of Rust Nightly determined by the
120-
[`rust-toolchain.toml`](https://github.com/servo/servo/blob/main/rust-toolchain.toml) file.
121-
122-
### Normal build
123-
124-
To build Servo in development mode.
125-
This is useful for development, but the resulting binary is very slow:
126-
127-
``` sh
128-
./mach build --dev
129-
./mach run tests/html/about-mozilla.html
130-
```
131-
132-
### Release build
133-
For benchmarking, performance testing, or real-world use.
134-
Add the `--release` flag to create an optimized build:
135-
136-
``` sh
137-
./mach build --release
138-
./mach run --release tests/html/about-mozilla.html
139-
```
140-
141-
### Android build
142-
143-
For an armv7 Android build run the following command.
144-
145-
```shell
146-
./mach build --android
147-
```
148-
149-
### Checking for build errors, without building
150-
151-
If you’re making changes to one crate that cause build errors in another crate,
152-
consider this instead of a full build:
153-
154-
```sh
155-
./mach check
156-
```
157-
158-
It will run `cargo check`, which runs the analysis phase of the compiler
159-
(and so shows build errors if any) but skips the code generation phase.
160-
This can be a lot faster than a full build,
161-
though of course it doesn’t produce a binary you can run.
162-
163-
## Running
164-
165-
Run Servo with the command:
166-
167-
```sh
168-
./servo [url] [arguments] # if you run with nightly build
169-
./mach run [url] [arguments] # if you run with mach
170-
171-
# For example
172-
./mach run https://www.google.com
173-
```
174-
175-
### Commandline Arguments
176-
177-
- `-p INTERVAL` turns on the profiler and dumps info to the console every
178-
`INTERVAL` seconds
179-
- `-s SIZE` sets the tile size for painting; defaults to 512
180-
- `-z` disables all graphical output; useful for running JS / layout tests
181-
- `-Z help` displays useful output to debug servo
182-
183-
### Keyboard Shortcuts
184-
185-
- `Ctrl`+`L` opens URL prompt (`Cmd`+`L` on Mac)
186-
- `Ctrl`+`R` reloads current page (`Cmd`+`R` on Mac)
187-
- `Ctrl`+`-` zooms out (`Cmd`+`-` on Mac)
188-
- `Ctrl`+`=` zooms in (`Cmd`+`=` on Mac)
189-
- `Alt`+`left arrow` goes backwards in the history (`Cmd`+`left arrow` on Mac)
190-
- `Alt`+`right arrow` goes forwards in the history (`Cmd`+`right arrow` on Mac)
191-
- `Ctrl`+`Q` exits Servo (`Cmd`+`Q` on Mac)
192-
- `Esc` exits fullscreen
193-
194-
### Runtime dependencies
195-
196-
#### Linux
197-
198-
* `GStreamer` >=1.18
199-
* `gst-plugins-base` >=1.18
200-
* `gst-plugins-good` >=1.18
201-
* `gst-plugins-bad` >=1.18
202-
* `gst-plugins-ugly` >=1.18
203-
* `libXcursor`
204-
* `libXrandr`
205-
* `libXi`
206-
* `libxkbcommon`
207-
* `vulkan-loader`
208-
209-
## Developing
210-
211-
There are lots of mach commands you can use. You can list them with `./mach
212-
--help`.
213-
214-
215-
The generated documentation can be found on https://doc.servo.org/servo/index.html
216-
217-
[manual-build]: https://github.com/servo/servo/wiki/Building#manual-build-setup
218-
[windows-tips]: https://github.com/servo/servo/wiki/Building#troubleshooting-the-windows-build
219-
[android-docs]: https://github.com/servo/servo/wiki/Building-for-Android
66+
- Follow the instructions above for the platform you are building on

‎docs/COMMAND_LINE_ARGS.md

+5-30
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,7 @@
1-
Command Line Arguments
2-
========================
3-
# General
1+
# Command line arguments
42

5-
You can see available commands with:
6-
```
7-
./mach -h
8-
./mach <sub-command> -h
9-
```
10-
Only arguments that need more explanation will be documented here.
3+
Moved to the Servo book:
114

12-
# Run
13-
## Enable Experimental Features
14-
Use `--pref` to enable experimental features like experimental DOM APIs, JavaScript APIs and CSS properties.
15-
16-
e.g. To enable Web VR and Bluetooth features:
17-
```
18-
./mach run -d -- --pref dom.webvr.enabled --pref dom.bluetooth.enabled ...
19-
```
20-
21-
You can find all the available preferences at [resources/prefs.json](../resources/prefs.json).
22-
23-
# Debugging
24-
## Remote Debugging
25-
Use `--devtools 6000` to start the devtools server on port 6000.
26-
27-
e.g.
28-
```
29-
./mach run -d --devtools=6000 https://servo.org
30-
```
31-
32-
To connect to the server, follow [this guide](https://developer.mozilla.org/en-US/docs/Tools/Remote_Debugging/Debugging_Firefox_Desktop#Connect).
5+
- [Running servoshell](https://book.servo.org/running-servoshell.html)
6+
- Hacking on Servo
7+
- [Running servoshell](https://book.servo.org/hacking/running-servoshell.html)

‎docs/HACKING_QUICKSTART.md

+2-422
Large diffs are not rendered by default.

‎docs/ORGANIZATION.md

+5-109
Original file line numberDiff line numberDiff line change
@@ -1,110 +1,6 @@
1-
# Servo's directory structure:
2-
* components
3-
* bluetooth
4-
* Implementation of the bluetooth thread.
5-
* bluetooth_traits
6-
* APIs to the bluetooth crate for crates that don't want to depend on the bluetooth crate for build speed reasons.
7-
* canvas
8-
* Implementation of painting threads for 2D and WebGL canvases.
9-
* canvas_traits
10-
* APIs to the canvas crate for crates that don't want to depend on the canvas crate for build speed reasons.
11-
* compositing
12-
* Integration with OS windowing/rendering and event loop.
13-
* constellation
14-
* Management of resources for a top-level browsing context (ie. tab).
15-
* devtools
16-
* In-process server to allow manipulating browser instances via a remote Firefox developer tools client.
17-
* devtools_traits
18-
* APIs to the devtools crate for crates that don't want to depend on the devtools crate for build speed reasons.
19-
* fonts
20-
* Code for dealing with fonts and text shaping.
21-
* fonts_traits
22-
* APIs to the fonts crate for crates that don't want to depend on the fonts crate for build speed reasons.
23-
* layout
24-
* Converts page content into positioned, styled boxes and passes the result to the renderer.
25-
* layout_thread
26-
* Runs the threads for layout, communicates with the script thread, and calls into the layout crate to do the layout.
27-
* msg
28-
* Shared APIs for communicating between specific threads and crates.
29-
* net
30-
* Network protocol implementations, and state and resource management (caching, cookies, etc.).
31-
* net_traits
32-
* APIs to the net crate for crates that don't want to depend on the net crate for build speed reasons.
33-
* plugins
34-
* Syntax extensions, custom attributes, and lints.
35-
* profile
36-
* Memory and time profilers.
37-
* profile_traits
38-
* APIs to the profile crate for crates that don't want to depend on the profile crate for build speed reasons.
39-
* script
40-
* Implementation of the DOM (native Rust code and bindings to SpiderMonkey).
41-
* script_layout_interface
42-
* The API the script crate provides for the layout crate.
43-
* script_traits
44-
* APIs to the script crate for crates that don't want to depend on the script crate for build speed reasons.
45-
* selectors
46-
* CSS selector matching.
47-
* servo
48-
* Entry points for the servo application and libservo embedding library.
49-
* style
50-
* APIs for parsing CSS and interacting with stylesheets and styled elements.
51-
* style_traits
52-
* APIs to the style crate for crates that don't want to depend on the style crate for build speed reasons.
53-
* util
54-
* Assorted utility methods and types that are commonly used throughout the project.
55-
* webdriver_server
56-
* In-process server to allow manipulating browser instances via a WebDriver client.
57-
* webgpu
58-
* Implementation of threads for the WebGPU API.
59-
* etc
60-
* Useful tools and scripts for developers.
61-
* mach
62-
* A command-line tool to help with developer tasks.
63-
* ports
64-
* winit
65-
* Embedding implementation for the `winit` windowing library.
66-
* python
67-
* servo
68-
* Implementations of servo-specific mach commands.
69-
* tidy
70-
* Python package of code lints that are automatically run before merging changes.
71-
* resources
72-
* Files used at run time. Need to be included somehow when distributing binary builds.
73-
* support
74-
* android
75-
* Libraries that require special handling for building for Android platforms
76-
* rust-task_info
77-
* Library for obtaining information about memory usage for a process
78-
* target
79-
* debug
80-
* Build artifacts generated by `./mach build --debug`.
81-
* doc
82-
* Documentation is generated here by the `rustdoc` tool when running `./mach doc`
83-
* release
84-
* Build artifacts generated by `./mach build --release`.
85-
* tests
86-
* dromaeo
87-
* Harness for automatically running the Dromaeo testsuite.
88-
* html
89-
* Manual tests and experiments.
90-
* jquery
91-
* Harness for automatically running the jQuery testsuite.
92-
* power
93-
* Tools for measurement of power consumption.
94-
* unit
95-
* Unit tests using rustc’s built-in test harness.
96-
* wpt
97-
* W3C web-platform-tests and csswg-tests along with tools to run them and expected failures.
1+
# Servo’s directory structure
982

99-
# Major dependencies
100-
* <https://github.com/servo/rust-mozjs>, <https://github.com/servo/mozjs>: bindings to SpiderMonkey
101-
* <https://github.com/hyperium/hyper>: an HTTP implementation
102-
* <https://github.com/servo/html5ever>: an HTML5 parser
103-
* <https://github.com/servo/ipc-channel>: an IPC implementation
104-
* <https://github.com/image-rs/image>: image decoders
105-
* <https://github.com/rust-windowing/winit>: cross-platform windowing and input
106-
* <https://github.com/jrmuizel/raqote>: a pure Rust 2D graphics library
107-
* <https://github.com/servo/rust-cssparser>: a CSS parser
108-
* <https://github.com/housleyjk/ws-rs>: a WebSocket protocol implementation
109-
* <https://github.com/servo/rust-url>: an implementation of the URL specification
110-
* <https://github.com/servo/webrender>: a GPU renderer
3+
Moved to the Servo book:
4+
5+
- Servo’s architecture
6+
- [Directory structure](https://book.servo.org/architecture/directory-structure.html)

‎docs/STYLE_GUIDE.md

+3-26
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,6 @@
11
# Style Guide
22

3-
The majority of our style recommendations are automatically enforced via our
4-
automated linters. This document has guidelines that are less easy to lint for.
3+
Moved to the Servo book:
54

6-
## Shell scripts
7-
8-
Shell scripts are suitable for small tasks or wrappers, but it's preferable to use Python for
9-
anything with a hint of complexity or in general.
10-
11-
Shell scripts should be written using bash, starting with this shebang:
12-
```
13-
#!/usr/bin/env bash
14-
```
15-
16-
Note that the version of bash available on macOS by default is quite old, so be
17-
careful when using new features.
18-
19-
Scripts should enable a few options at the top for robustness:
20-
```
21-
set -o errexit
22-
set -o nounset
23-
set -o pipefail
24-
```
25-
26-
Rememeber to quote all variables, using the full form: `"${SOME_VARIABLE}"`.
27-
28-
Use `"$(some-command)"` instead of backticks for command substitution. Note
29-
that these should be quoted as well.
5+
- Pre-book docs
6+
- [docs/STYLE_GUIDE.md](https://book.servo.org/old/STYLE_GUIDE.html)

‎docs/components/style.md

+3-144
Original file line numberDiff line numberDiff line change
@@ -1,147 +1,6 @@
11
# Servo's style system overview
22

3-
This document provides an overview of Servo's style system. For more extensive details,
4-
refer to the [style doc comments][style-doc], or the [Styling
5-
Overview][wiki-styling-overview] in the wiki, which includes a conversation between
6-
Boris Zbarsky and Patrick Walton about how style sharing works.
3+
Moved to the Servo book:
74

8-
<a name="selector-impl"></a>
9-
## Selector Implementation
10-
11-
To ensure compatibility with Stylo (a project integrating Servo's style system into Gecko),
12-
selectors must be consistent.
13-
14-
The consistency is implemented in [selectors' SelectorImpl][selector-impl],
15-
containing the logic related to parsing pseudo-elements and other pseudo-classes
16-
apart from [tree-structural ones][tree-structural-pseudo-classes].
17-
18-
Servo extends the selector implementation trait in order to allow a few more
19-
things to be shared between Stylo and Servo.
20-
21-
The main Servo implementation (the one that is used in regular builds) is
22-
[SelectorImpl][servo-selector-impl].
23-
24-
<a name="dom-glue"></a>
25-
## DOM glue
26-
27-
In order to keep DOM, layout and style in different modules, there are a few
28-
traits involved.
29-
30-
Style's [`dom` traits][style-dom-traits] (`TDocument`, `TElement`, `TNode`,
31-
`TRestyleDamage`) are the main "wall" between layout and style.
32-
33-
Layout's [`wrapper`][layout-wrapper] module makes sure that
34-
layout traits have the required traits implemented.
35-
36-
<a name="stylist"></a>
37-
## The Stylist
38-
39-
The [`stylist`][stylist] structure holds all the selectors and
40-
device characteristics for a given document.
41-
42-
The stylesheets' CSS rules are converted into [`Rule`][selectors-rule]s.
43-
They are then introduced in a [`SelectorMap`][selectors-selectormap] depending
44-
on the pseudo-element (see [`PerPseudoElementSelectorMap`][per-pseudo-selectormap]),
45-
stylesheet origin (see [`PerOriginSelectorMap`][per-origin-selectormap]), and
46-
priority (see the `normal` and `important` fields in
47-
[`PerOriginSelectorMap`][per-origin-selectormap]).
48-
49-
This structure is effectively created once per [pipeline][docs-pipeline], in the
50-
corresponding LayoutThread.
51-
52-
<a name="properties"></a>
53-
## The `properties` module
54-
55-
The [properties module][properties-module] is a mako template. Its complexity is derived
56-
from the code that stores properties, [`cascade` function][properties-cascade-fn] and computation logic of the returned value which is exposed in the main function.
57-
58-
<a name="pseudo-elements"></a>
59-
## Pseudo-Element resolution
60-
61-
Pseudo-elements are a tricky section of the style system. Not all
62-
pseudo-elements are very common, and so some of them might want to skip the
63-
cascade.
64-
65-
Servo has, as of right now, five [pseudo-elements][servo-pseudo-elements]:
66-
67-
* [`::before`][mdn-pseudo-before] and [`::after`][mdn-pseudo-after].
68-
* [`::selection`][mdn-pseudo-selection]: This one is only partially
69-
implemented, and only works for text inputs and textareas as of right now.
70-
* `::-servo-details-summary`: This pseudo-element represents the `<summary>` of
71-
a `<details>` element.
72-
* `::-servo-details-content`: This pseudo-element represents the contents of
73-
a `<details>` element.
74-
75-
Both `::-servo-details-*` pseudo-elements are private (i.e. they are only parsed
76-
from User-Agent stylesheets).
77-
78-
Servo has three different ways of cascading a pseudo-element, which are defined
79-
in [`PseudoElementCascadeType`][pseudo-cascade-type]:
80-
81-
<a name="pe-cascading-eager"></a>
82-
### "Eager" cascading
83-
84-
This mode computes the computed values of a given node's pseudo-element over the
85-
first pass of the style system.
86-
87-
This is used for all public pseudo-elements, and is, as of right now, **the only
88-
way a public pseudo-element should be cascaded** (the explanation for this is
89-
below).
90-
91-
<a name="pe-cascading-precomputed"></a>
92-
### "Precomputed" cascading
93-
94-
Or, better said, no cascading at all. A pseudo-element marked as such is not
95-
cascaded.
96-
97-
The only rules that apply to the styles of that pseudo-element are universal
98-
rules (rules with a `*|*` selector), and they are applied directly over the
99-
element's style if present.
100-
101-
`::-servo-details-content` is an example of this kind of pseudo-element, all the
102-
rules in the UA stylesheet with the selector `*|*::-servo-details-content` (and
103-
only those) are evaluated over the element's style (except the `display` value,
104-
that is overwritten by layout).
105-
106-
This should be the **preferred type for private pseudo-elements** (although some
107-
of them might need selectors, see below).
108-
109-
<a name="pe-cascading-lazy"></a>
110-
### "Lazy" cascading
111-
112-
Lazy cascading allows to compute pseudo-element styles lazily, that is, just
113-
when needed.
114-
115-
Currently (for Servo, not that much for stylo), **selectors supported for this
116-
kind of pseudo-elements are only a subset of selectors that can be matched on
117-
the layout tree, which does not hold all data from the DOM tree**.
118-
119-
This subset includes tags and attribute selectors, enough for making
120-
`::-servo-details-summary` a lazy pseudo-element (that only needs to know
121-
if it is in an `open` details element or not).
122-
123-
Since no other selectors would apply to it, **this is (at least for now) not an
124-
acceptable type for public pseudo-elements, but should be considered for private
125-
pseudo-elements**.
126-
127-
[style-doc]: https://doc.servo.org/style/index.html
128-
[wiki-styling-overview]: https://github.com/servo/servo/wiki/Styling-overview
129-
[selector-impl]: https://doc.servo.org/selectors/parser/trait.SelectorImpl.html
130-
[selector-impl-ext]: https://doc.servo.org/style/selector_parser/trait.SelectorImplExt.html
131-
[servo-selector-impl]: https://doc.servo.org/style/servo/selector_parser/struct.SelectorImpl.html
132-
[tree-structural-pseudo-classes]: https://www.w3.org/TR/selectors4/#structural-pseudos
133-
[style-dom-traits]: https://doc.servo.org/style/dom/index.html
134-
[layout-wrapper]: https://doc.servo.org/layout/wrapper/index.html
135-
[pseudo-cascade-type]: https://doc.servo.org/style/selector_parser/enum.PseudoElementCascadeType.html
136-
[servo-pseudo-elements]: https://doc.servo.org/style/selector_parser/enum.PseudoElement.html
137-
[mdn-pseudo-before]: https://developer.mozilla.org/en/docs/Web/CSS/::before
138-
[mdn-pseudo-after]: https://developer.mozilla.org/en/docs/Web/CSS/::after
139-
[mdn-pseudo-selection]: https://developer.mozilla.org/en/docs/Web/CSS/::selection
140-
[stylist]: https://doc.servo.org/style/stylist/struct.Stylist.html
141-
[selectors-selectormap]: https://doc.servo.org/style/selector_map/struct.SelectorMap.html
142-
[selectors-rule]: https://doc.servo.org/style/stylist/struct.Rule.html
143-
[per-pseudo-selectormap]: https://doc.servo.org/style/selector_parser/struct.PerPseudoElementMap.html
144-
[per-origin-selectormap]: https://doc.servo.org/style/stylist/struct.PerOriginSelectorMap.html
145-
[docs-pipeline]: https://github.com/servo/servo/blob/main/docs/glossary.md#pipeline
146-
[properties-module]: https://doc.servo.org/style/properties/index.html
147-
[properties-cascade-fn]: https://doc.servo.org/style/properties/fn.cascade.html
5+
- Servo’s architecture
6+
- [Style](https://book.servo.org/architecture/style.html)

‎docs/components/webxr.md

+3-75
Original file line numberDiff line numberDiff line change
@@ -1,78 +1,6 @@
11
# How WebXR works in Servo
22

3-
## Terminology
3+
Moved to the Servo book:
44

5-
Servo's WebXR implementation involves three main components:
6-
1. The script thread (runs all JS for a page)
7-
2. The WebGL thread (maintains WebGL canvas data and invokes GL operations corresponding to [WebGL APIs](https://registry.khronos.org/webgl/specs/latest/1.0/))
8-
3. The compositor (AKA the main thread)
9-
10-
Additionally, there are a number of WebXR-specific concepts:
11-
* The [discovery object](https://doc.servo.org/webxr_api/trait.DiscoveryAPI.html) (ie. how Servo discovers if a device can provide a WebXR session)
12-
* The [WebXR registry](https://doc.servo.org/webxr_api/struct.MainThreadRegistry.html) (the compositor's interface to WebXR)
13-
* The [layer manager](https://doc.servo.org/webxr_api/layer/trait.LayerManagerAPI.html) (manages WebXR layers for a given session and frame operations on those layers)
14-
* The [layer grand manager](https://doc.servo.org/webxr_api/layer/trait.LayerGrandManagerAPI.html) (manages all layer managers for WebXR sessions)
15-
16-
Finally, there are graphics-specific concepts that are important for the low-level details of rendering with WebXR:
17-
* [surfman](https://github.com/servo/webxr/blob/main/webxr/glwindow/mod.rs#L448-L452) is a crate that abstracts away platform-specific details of OpenGL hardware-accelerated rendering
18-
* [surface](https://doc.servo.org/surfman/platform/unix/default/surface/type.Surface.html) is a hardware buffer that are tied to a specific OpenGL context
19-
* [surface texture](https://doc.servo.org/surfman/platform/unix/default/surface/type.SurfaceTexture.html) is an OpenGL texture that wraps a surface. Surface textures can be shared between OpenGL contexts.
20-
* [surfman context](https://doc.servo.org/surfman/platform/unix/default/context/type.Context.html) represents a particular OpenGL context, and is backed by platform-specific implementations (such as EGL on Unix-based platforms)
21-
* [ANGLE](https://github.com/servo/mozangle/) is an OpenGL implementation on top of Direct3D which is used in Servo to provide a consistent OpenGL backend on Windows-based platforms
22-
23-
## How Servo's compositor starts
24-
25-
The embedder is responsible for creating a window and [triggering the rendering context creation](https://github.com/servo/servo/blob/d7d0451424faf1bf9c705068bea1aa8cf582d6ad/ports/servoshell/headed_window.rs#L134) appropriately.
26-
Servo creates the rendering context by [creating a surfman context](https://github.com/servo/servo/blob/d7d0451424faf1bf9c705068bea1aa8cf582d6ad/components/gfx/rendering_context.rs#L48-L58) which will
27-
be [used by the compositor](https://github.com/servo/servo/blob/d7d0451424faf1bf9c705068bea1aa8cf582d6ad/components/servo/lib.rs#L467) for all [web content rendering operations](https://github.com/servo/servo/blob/d7d0451424faf1bf9c705068bea1aa8cf582d6ad/components/servo/lib.rs#L269-L281).
28-
29-
## How a session starts
30-
31-
When a webpage invokes `navigator.xr.requestSession(..)` through JS, this corresponds to the [XrSystem::RequestSession](https://github.com/servo/servo/blob/d7d0451424faf1bf9c705068bea1aa8cf582d6ad/components/script/dom/xrsystem.rs#L158) method in Servo.
32-
This method [sends a message](https://github.com/servo/webxr/blob/614420b9830615376563fc6e1d98c52119f97123/webxr-api/registry.rs#L103-L108) to the [WebXR message handler](https://github.com/servo/webxr/blob/614420b9830615376563fc6e1d98c52119f97123/webxr-api/registry.rs#L193-L195)
33-
that lives on the main thread, under the [control of the compositor](https://github.com/servo/servo/blob/d7d0451424faf1bf9c705068bea1aa8cf582d6ad/components/compositing/compositor.rs#L2049).
34-
35-
The WebXR message handler iterates over all known discovery objects and attempts to [request a session](https://github.com/servo/webxr/blob/614420b9830615376563fc6e1d98c52119f97123/webxr-api/registry.rs#L217-L231)
36-
from each of them. The discovery objects encapsulate creating a session for each supported backend.
37-
38-
As of Feb 3, 2024, there are five WebXR backends:
39-
* [magicleap](https://github.com/servo/webxr/tree/main/webxr/magicleap) - supports Magic Leap 1.0 devices
40-
* [googlevr](https://github.com/servo/webxr/tree/main/webxr/googlevr) - supports Google VR
41-
* [headless](https://github.com/servo/webxr/tree/main/webxr/headless) - supports a window-less, device-less device for automated tests
42-
* [glwindow](https://github.com/servo/webxr/tree/main/webxr/glwindow) - supports a GL-based window for manual testing in desktop environments without real devices
43-
* [openxr](https://github.com/servo/webxr/tree/main/webxr/openxr) - supports devices that implement the OpenXR standard
44-
45-
WebXR sessions need to [create a layer manager](https://github.com/servo/webxr/blob/main/webxr/glwindow/mod.rs#L448-L452)
46-
at some point in order to be able to create and render to WebXR layers. This happens in several steps:
47-
1. some initialization happens on the main thread
48-
2. the main thread [sends a synchronous message](https://github.com/servo/servo/blob/d7d0451424faf1bf9c705068bea1aa8cf582d6ad/components/canvas/webgl_thread.rs#L3182-L3187) to the WebGL thread
49-
3. the WebGL thread [receives the message](https://github.com/servo/servo/blob/d7d0451424faf1bf9c705068bea1aa8cf582d6ad/components/canvas/webgl_thread.rs#L392-L396)
50-
4. some backend-specific, graphics-specific initialization happens on the WebGL thread, hidden behind the [layer manager factory](https://doc.servo.org/webxr_api/struct.LayerManagerFactory.html) abstraction
51-
5. the new layer manager is [stored in the WebGL thread](https://github.com/servo/servo/blob/d7d0451424faf1bf9c705068bea1aa8cf582d6ad/components/canvas/webgl_thread.rs#L3058-L3061)
52-
6. the main thread [receives a unique identifier](https://github.com/servo/servo/blob/d7d0451424faf1bf9c705068bea1aa8cf582d6ad/components/canvas/webgl_thread.rs#L3189-L3196) representing the new layer manager
53-
54-
This cross-thread dance is important because the device performing the rendering often has strict requirements for the compatibility of any
55-
WebGL context that is used for rendering, and most GL state is only observable on the thread that created it.
56-
57-
## How an OpenXR session is created
58-
59-
The OpenXR discovery process starts at [OpenXrDiscovery::request_session](https://github.com/servo/webxr/blob/614420b9830615376563fc6e1d98c52119f97123/webxr/openxr/mod.rs#L309).
60-
The discovery object only has access to whatever state was passed in its constructor, as well as a [SessionBuilder](https://doc.servo.org/webxr_api/struct.SessionBuilder.html)
61-
object that contains values required to create a new session.
62-
63-
Creating an OpenXR session first [creates an OpenXR instance](https://github.com/servo/webxr/blob/614420b9830615376563fc6e1d98c52119f97123/webxr/openxr/mod.rs#L192),
64-
which allows coniguring which extensions are in use. There are different extensions used to initialize OpenXR on different platforms; for Window
65-
the [D3D extension](https://github.com/servo/webxr/blob/614420b9830615376563fc6e1d98c52119f97123/webxr/openxr/mod.rs#L213) can be used
66-
since Servo relies on ANGLE for its OpenGL implementation.
67-
68-
Once an OpenXR instance exists, the session builder is used to create a new WebXR session that [runs in its own thread](https://github.com/servo/webxr/blob/614420b9830615376563fc6e1d98c52119f97123/webxr/openxr/mod.rs#L331).
69-
All WebXR sessions can either [run in a thread](https://github.com/servo/webxr/blob/614420b9830615376563fc6e1d98c52119f97123/webxr-api/session.rs#L513-L538)
70-
or have Servo [run them on the main thread](https://github.com/servo/webxr/blob/614420b9830615376563fc6e1d98c52119f97123/webxr-api/session.rs#L540-L552).
71-
This choice has implications for how the graphics for the WebXR session can be set up, based on what GL state must be available for sharing.
72-
73-
OpenXR's new session thread [initializes an OpenXR device](https://github.com/servo/webxr/blob/614420b9830615376563fc6e1d98c52119f97123/webxr/openxr/mod.rs#L332-L337),
74-
which is responsible for creating the actual OpenXR session. This session object is [created on the WebGL thread](https://github.com/servo/webxr/blob/614420b9830615376563fc6e1d98c52119f97123/webxr/openxr/mod.rs#L864-L878)
75-
as part of creating the OpenXR layer manager, since it relies on [sharing the underlying GPU device](https://github.com/servo/webxr/blob/614420b9830615376563fc6e1d98c52119f97123/webxr/openxr/mod.rs#L443-L460) that the WebGL thread uses.
76-
77-
Once the session object has been created, the main thread can [obtain a copy](https://github.com/servo/webxr/blob/614420b9830615376563fc6e1d98c52119f97123/webxr/openxr/mod.rs#L878)
78-
and resume initializing the [remaining properties](https://github.com/servo/webxr/blob/614420b9830615376563fc6e1d98c52119f97123/webxr/openxr/mod.rs#L882-L1026) of the new device.
5+
- Servo’s architecture
6+
- [WebXR](https://book.servo.org/architecture/webxr.html)

‎docs/debugging.md

+3-59
Original file line numberDiff line numberDiff line change
@@ -1,62 +1,6 @@
11
# Servo debugging guide
22

3-
There are a few ways to debug Servo. `mach` supports a `--debug` flag that
4-
searches a suitable debugger for you and runs Servo with the appropriate
5-
arguments under it:
3+
Moved to the Servo book:
64

7-
```
8-
./mach run --debug test.html
9-
```
10-
11-
You can also specify an alternative debugger using the `--debugger` flag:
12-
13-
```
14-
./mach run --debugger=my-debugger test.html
15-
```
16-
17-
You can also, of course, run directly your debugger on the Servo binary:
18-
19-
```
20-
$ gdb --args ./target/debug/servo test.html
21-
```
22-
23-
## Debugging SpiderMonkey.
24-
25-
You can build Servo with a debug version of SpiderMonkey passing the
26-
`--debug-mozjs` flag to `./mach build`.
27-
28-
Note that this sometimes can cause problems when an existing build exists, so
29-
you might have to delete the `mozjs` build directory, or run `./mach clean`
30-
before your first `--debug-mozjs` build.
31-
32-
## Debugging Servo with [rr][rr].
33-
34-
To record a trace under rr you can either use:
35-
36-
```
37-
$ ./mach run --debugger=rr testcase.html
38-
```
39-
40-
Or:
41-
42-
```
43-
$ rr record ./target/debug/servo testcase.html
44-
```
45-
46-
### Running WPT tests under rr's chaos mode.
47-
48-
Matt added a mode to Servo's testing commands to record traces of Servo running
49-
a test or set of tests until the result is unexpected.
50-
51-
To use this, you can pass the `--chaos` argument to `mach test-wpt`:
52-
53-
```
54-
$ ./mach test-wpt --chaos path/to/test
55-
```
56-
57-
Note that for this to work you need to have `rr` in your `PATH`.
58-
59-
Also, note that this might generate a lot of traces, so you might want to delete
60-
them when you're done. They're under `$HOME/.local/share/rr`.
61-
62-
[rr]: http://rr-project.org/
5+
- Hacking on Servo
6+
- [Debugging](https://book.servo.org/hacking/debugging.html)

‎docs/glossary.md

+3-32
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,6 @@
1-
# How to use this glossary
2-
3-
This is a collection of common terms that have a specific meaning in the context of the Servo project. The goal is to provide high-level definitions and useful links for further reading, rather than complete documentation about particular parts of the code.
4-
5-
If there is a word or phrase used in Servo's code, issue tracker, mailing list, etc. that is confusing, please make a pull request that adds it to this file with a body of `TODO`. This will signal more knowledgeable people to add a more meaningful definition.
6-
71
# Glossary
82

9-
### Compositor ###
10-
11-
The thread that receives input events from the operating system and forwards them to the constellation. It is also in charge of compositing complete renders of web content and displaying them on the screen as fast as possible.
12-
13-
### Constellation ###
14-
15-
The thread that controls a collection of related web content. This could be thought of as an owner of a single tab in a tabbed web browser; it encapsulates session history, knows about all frames in a frame tree, and is the owner of the pipeline for each contained frame.
16-
17-
### Display list ###
18-
19-
A list of concrete rendering instructions. The display list is post-layout, so all items have stacking-context-relative pixel positions, and z-index has already been applied, so items later in the display list will always be on top of items earlier in it.
20-
21-
### Layout thread ###
22-
23-
A thread that is responsible for laying out a DOM tree into layers of boxes for a particular document. Receives commands from the script thread to lay out a page and either generate a new display list for use by the renderer thread, or return the results of querying the layout of the page for use by script.
24-
25-
### Pipeline ###
26-
27-
A unit encapsulating a means of communication with the script, layout, and renderer threads for a particular document. Each pipeline has a globally-unique id which can be used to access it from the constellation.
28-
29-
### Renderer thread (alt. paint thread) ###
30-
31-
A thread which translates a display list into a series of drawing commands that render the contents of the associated document into a buffer, which is then sent to the compositor.
32-
33-
### Script thread (alt. script task) ###
3+
Moved to the Servo book:
344

35-
A thread that executes JavaScript and stores the DOM representation of all documents that share a common [origin](https://tools.ietf.org/html/rfc6454). This thread translates input events received from the constellation into DOM events [per the specification](https://w3c.github.io/uievents/), invokes the HTML parser when new page content is received, and evaluates JS for events like timers and `<script>` elements.
5+
- Pre-book docs
6+
- [docs/glossary.md](https://book.servo.org/old/glossary.html)

‎etc/doc.servo.org/index.html

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<!doctype html>
22
<title>Servo, the parallel browser engine</title>
3-
<meta http-equiv=refresh content="0;url=servo/index.html">
3+
<meta http-equiv=refresh content="0;url=https://book.servo.org/">
44

55
Documentation for Servo, the parallel browser engine.
6-
Start with <a href="servo/index.html">the <code>servo</code> crate</a>
6+
Start with <a href="https://book.servo.org/">The Servo Book</a>.

‎tests/wpt/README.md

+4-244
Original file line numberDiff line numberDiff line change
@@ -1,246 +1,6 @@
1-
This folder contains the web platform tests and the
2-
code required to integrate them with Servo.
3-
To learn how to write tests, go [here](http://web-platform-tests.org/writing-tests/index.html).
1+
# Web tests (including [Web Platform Tests](https://web-platform-tests.org))
42

5-
Contents
6-
========
3+
Moved to the Servo book:
74

8-
In particular, this folder contains:
9-
10-
* `config.ini`: some configuration for the web-platform-tests.
11-
* `include.ini`: the subset of web-platform-tests we currently run.
12-
* `tests`: copy of the web-platform-tests.
13-
* `meta`: expected failures for the web-platform-tests we run.
14-
* `mozilla`: web-platform-tests that cannot be upstreamed.
15-
16-
Running the tests
17-
=================
18-
19-
The simplest way to run the web-platform-tests in Servo is `./mach
20-
test-wpt` in the root directory. This will run the subset of
21-
JavaScript tests defined in `include.ini` and log the output to
22-
stdout.
23-
24-
A subset of tests may be run by providing positional arguments to the
25-
mach command, either as filesystem paths or as test urls e.g.
26-
27-
./mach test-wpt tests/wpt/tests/dom/historical.html
28-
29-
to run the dom/historical.html test, or
30-
31-
./mach test-wpt dom
32-
33-
to run all the DOM tests.
34-
35-
There are also a large number of command line options accepted by the
36-
test harness; these are documented by running with `--help`.
37-
38-
Running all tests
39-
------------------------------
40-
41-
Running all the WPT tests with debug mode results in a lot of timeout.
42-
If one wants to run all the tests,
43-
build with `mach build -r`
44-
and
45-
test with `mach test-wpt --release`
46-
47-
Running the tests with an external WPT server
48-
---------------------------------------------
49-
50-
Normally wptrunner starts its own WPT server, but occasionally you
51-
might want to run multiple instances of `mach test-wpt`, such as when
52-
debugging one test while running the full suite in the background, or
53-
when running a single test many times in parallel (--processes only
54-
works across different tests).
55-
56-
This would lead to a “Failed to start HTTP server” errors, because you
57-
can only run one WPT server at a time. To fix this:
58-
59-
1. Follow the steps in [**Running the tests manually**](#running-the-tests-manually)
60-
2. Add a `break` to [start_servers in serve.py](https://github.com/servo/servo/blob/ce92b7bfbd5855aac18cb4f8a8ec59048041712e/tests/wpt/web-platform-tests/tools/serve/serve.py#L745-L783) as follows:
61-
```
62-
--- a/tests/wpt/tests/tools/serve/serve.py
63-
+++ b/tests/wpt/tests/tools/serve/serve.py
64-
@@ -746,6 +746,7 @@ def start_servers(logger, host, ports, paths, routes, bind_address, config,
65-
mp_context, log_handlers, **kwargs):
66-
servers = defaultdict(list)
67-
for scheme, ports in ports.items():
68-
+ break
69-
assert len(ports) == {"http": 2, "https": 2}.get(scheme, 1)
70-
71-
# If trying to start HTTP/2.0 server, check compatibility
72-
```
73-
3. Run `mach test-wpt` as many times as needed
74-
75-
If you get unexpected TIMEOUT in testharness tests, then the custom
76-
testharnessreport.js may have been installed incorrectly (see
77-
[**Running the tests manually**](#running-the-tests-manually)
78-
for more details).
79-
80-
81-
Running the tests manually
82-
--------------------------
83-
84-
(See also [the relevant section of the upstream README][upstream-running].)
85-
86-
It can be useful to run a test without the interference of the test runner, for
87-
example when using a debugger such as `gdb`. To do this, we need to start the
88-
WPT server manually, which requires some extra configuration.
89-
90-
To do this, first add the following to the system's hosts file:
91-
92-
127.0.0.1 www.web-platform.test
93-
127.0.0.1 www1.web-platform.test
94-
127.0.0.1 www2.web-platform.test
95-
127.0.0.1 web-platform.test
96-
127.0.0.1 xn--n8j6ds53lwwkrqhv28a.web-platform.test
97-
127.0.0.1 xn--lve-6lad.web-platform.test
98-
99-
Navigate to `tests/wpt/web-platform-tests` for the remainder of this section.
100-
101-
Normally wptrunner [installs Servo’s version of testharnessreport.js][environment],
102-
but when starting the WPT server manually, we get the default version, which
103-
won’t report test results correctly. To fix this:
104-
105-
1. Create a directory `local-resources`
106-
2. Copy `tools/wptrunner/wptrunner/testharnessreport-servo.js` to `local-resources/testharnessreport.js`
107-
3. Edit `local-resources/testharnessreport.js` to substitute the variables as follows:
108-
* `%(output)d`
109-
* → `1` if you want to play with the test interactively (≈ pause-after-test)
110-
* → `0` if you don’t care about that (though it’s also ok to use `1` always)
111-
* `%(debug)s` → `true`
112-
4. Create a `./config.json` as follows (see `tools/wave/config.default.json` for defaults):
113-
```
114-
{"aliases": [{
115-
"url-path": "/resources/testharnessreport.js",
116-
"local-dir": "local-resources"
117-
}]}
118-
```
119-
120-
[environment]: https://github.com/servo/servo/blob/ce92b7bfbd5855aac18cb4f8a8ec59048041712e/tests/wpt/web-platform-tests/tools/wptrunner/wptrunner/environment.py#L231-L237
121-
122-
Then start the server with `./wpt serve`. To check if `testharnessreport.js` was installed correctly:
123-
124-
* The standard output of `curl http://web-platform.test:8000/resources/testharnessreport.js`
125-
should look like [testharnessreport-servo.js], not like [the default testharnessreport.js]
126-
* The standard output of `target/release/servo http://web-platform.test:8000/css/css-pseudo/highlight-pseudos-computed.html`
127-
(or any [testharness test]) should contain lines starting with:
128-
* `TEST START`
129-
* `TEST STEP`
130-
* `TEST DONE`
131-
* `ALERT: RESULT:`
132-
133-
[testharnessreport-servo.js]: https://github.com/servo/servo/blob/ce92b7bfbd5855aac18cb4f8a8ec59048041712e/tests/wpt/web-platform-tests/tools/wptrunner/wptrunner/testharnessreport-servo.js
134-
[the default testharnessreport.js]: https://github.com/servo/servo/blob/ce92b7bfbd5855aac18cb4f8a8ec59048041712e/tests/wpt/web-platform-tests/resources/testharnessreport.js
135-
[testharness test]: http://web-platform-tests.org/writing-tests/testharness.html
136-
137-
To prevent browser SSL warnings when running HTTPS tests locally,
138-
you will need to run Servo with `--certificate-path resources/cert-wpt-only`.
139-
140-
[upstream-running]: https://github.com/w3c/web-platform-tests#running-the-tests
141-
142-
Running the tests in Firefox
143-
----------------------------
144-
145-
When working with tests, you may want to compare Servo's result with Firefox.
146-
You can supply `--product firefox` along with the path to a Firefox binary (as
147-
well as few more odds and ends) to run tests in Firefox from your Servo
148-
checkout:
149-
150-
GECKO="$HOME/projects/mozilla/gecko"
151-
GECKO_BINS="$GECKO/obj-firefox-release-artifact/dist/Nightly.app/Contents/MacOS"
152-
./mach test-wpt dom --product firefox --binary $GECKO_BINS/firefox --certutil-binary $GECKO_BINS/certutil --prefs-root $GECKO/testing/profiles
153-
154-
Updating test expectations
155-
==========================
156-
157-
When fixing a bug that causes the result of a test to change, the expected
158-
results for that test need to be changed. This can be done manually, by editing
159-
the `.ini` file under the `meta` folder that corresponds to the test. In
160-
this case, remove the references to tests whose expectation is now `PASS`, and
161-
remove `.ini` files that no longer contain any expectations.
162-
163-
When a larger number of changes is required, this process can be automated.
164-
This first requires saving the raw, unformatted log from a test run, for
165-
example by running:
166-
167-
./mach test-wpt --log-raw /tmp/servo.log
168-
169-
Once the log is saved, run from the root directory:
170-
171-
./mach update-wpt /tmp/servo.log
172-
173-
The same process can be done for the legacy layout engine:
174-
175-
./mach test-wpt --legacy-layout --log-raw /tmp/servo-legacy.log
176-
./mach update-wpt --legacy-layout /tmp/servo-legacy.log
177-
178-
The updated expectations will be in `tests/wpt/meta/` and
179-
`tests/wpt/meta-legacy-layout/` respectively.
180-
181-
Writing new tests
182-
=================
183-
184-
The simplest way to create a new test is to use the following command:
185-
186-
./mach create-wpt tests/wpt/path/to/new/test.html
187-
188-
This will create test.html in the appropriate directory using the WPT
189-
template for JavaScript tests. Tests are written using [testharness.js](https://github.com/w3c/testharness.js/). Documentation can be found [here](http://testthewebforward.org/docs/testharness-library.html).
190-
To create a new reference test instead, use the following:
191-
192-
./mach create-wpt --reftest tests/wpt/path/to/new/reftest.html --reference tests/wpt/path/to/reference.html
193-
194-
`reference.html` will be created if it does not exist, and `reftest.html`
195-
will be created using the WPT reftest template. To know more about reftests, check [this](http://web-platform-tests.org/writing-tests/reftests.html).
196-
These new tests can then be run in the following manner like any other WPT test:
197-
198-
./mach test-wpt tests/wpt/path/to/new/test.html
199-
./mach test-wpt tests/wpt/path/to/new/reftest.html
200-
201-
202-
203-
Editing tests
204-
=============
205-
206-
web-platform-tests may be edited in-place and the changes committed to
207-
the servo tree. These changes will be upstreamed when the tests are
208-
next synced.
209-
210-
Servo-specific tests
211-
====================
212-
213-
The `mozilla` directory contains tests that cannot be upstreamed for some
214-
reason (e.g. because they depend on Servo-specific APIs), as well as some
215-
legacy tests that should be upstreamed at some point. When run they are
216-
mounted on the server under `/_mozilla/`.
217-
218-
Analyzing reftest results
219-
=========================
220-
221-
Reftest results can be analyzed from a raw log file. To generate this run
222-
with the `--log-raw` option e.g.
223-
224-
./mach test-wpt --log-raw wpt.log
225-
226-
This file can then be fed into the
227-
[reftest analyzer](https://hg.mozilla.org/mozilla-central/raw-file/tip/layout/tools/reftest/reftest-analyzer-structured.xhtml)
228-
which will show all failing tests (not just those with unexpected results).
229-
Note that this ingests logs in a different format to [original version of the
230-
tool](https://hg.mozilla.org/mozilla-central/raw-file/tip/layout/tools/reftest/reftest-analyzer.xhtml)
231-
written for gecko reftests.
232-
233-
The reftest analyzer allows pixel-level comparison of the test and reference
234-
screenshots. Tests that both fail and have an unexpected result are marked
235-
with a `!`.
236-
237-
Updating the WPT manifest
238-
=========================
239-
240-
MANIFEST.json can be regenerated automatically with the mach command `update-manifest` e.g.
241-
242-
./mach update-manifest
243-
244-
This is equivalent to running
245-
246-
./mach test-wpt --manifest-update SKIP_TESTS
5+
- Hacking on Servo
6+
- [Automated testing](https://book.servo.org/hacking/testing.html)

0 commit comments

Comments
 (0)
Please sign in to comment.