Building Aether

This page contains more detailed information about building Aether. ./mach build builds the ports/aether browser, which includes the Servo engine. You might want to skip straight to instructions for your system:

• Linux
• macOS
• Windows
• NixOS
• WSL
• Android
• OpenHarmony

mach

You need to use mach to build Aether. mach is a Python program that does plenty of things to make working on Servo easier, like building and running Servo, running tests, and updating dependencies.

Windows users: you will need to replace ./mach with .\mach in the commands in this book if you are using cmd.

Use --help to list the subcommands, or get help with a specific subcommand:

$ ./mach --help
$ ./mach build --help

When you use mach to run another program, such as Aether, that program may have its own options with the same names as mach options. You can use --, surrounded by spaces, to tell mach not to touch any subsequent options and leave them for the other program.

$ ./mach run --help         # Gets help for `mach run`.
$ ./mach run -d --help      # Still gets help for `mach run`.
$ ./mach run -d -- --help   # Gets help for the debug build of Aether.

This also applies to the Servo unit tests, where there are three layers of options: mach options, cargo test options, and libtest options.

$ ./mach test-unit --help           # Gets help for `mach test-unit`.
$ ./mach test-unit -- --help        # Gets help for `cargo test`.
$ ./mach test-unit -- -- --help     # Gets help for the test harness (libtest).

Work is ongoing to make it possible to build Servo without mach. Where possible, consider whether you can use native Cargo functionality before adding new functionality to mach.

Build profiles

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) (selected by default if no profile is passed)
• release builds, which are slower to build but more performant
• production builds, which are used for official releases only

There are also two special variants of production builds for performance-related use cases:

• production-stripped builds are ideal for benchmarking Servo over time, with debug symbols stripped for faster initial startup
• profiling builds are ideal for profiling and troubleshooting performance issues; they behave like a debug or release build, but have the same performance as a production build

You can change these settings in a servobuild file (see servobuild.example) or in the root Cargo.toml.

Optional build settings

Some build settings can only be enabled manually:

• AddressSanitizer builds are enabled with ./mach build --with-asan
• ThreadSanitizer builds are enabled with ./mach build --with-tsan
• crown linting is recommended when hacking on DOM code, and is enabled with ./mach build --use-crown
• SpiderMonkey debug builds are enabled with ./mach build --debug-mozjs, or [build] debug-mozjs = true in your servobuild file

A full list of arguments can be seen by running ./mach build --help.

Running Aether

On the desktop, a build produces target/debug/aether or target/release/aether. You can run it directly, but we recommend using mach instead.

To run Aether with mach, use ./mach run -d -- or ./mach run -r --, depending on the build profile you want to run. For example, both of the commands below run the debug build with the same options:

$ target/debug/aether https://example.com
$ ./mach run -d -- https://example.com

Android and OpenHarmony still package the native library as libservoshell.so. Pass --port=servoshell to build the upstream demo shell instead of Aether.