Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Building Servo

This page contains more detailed information about building Servo. You might want to skip straight to instructions for building Servo on your system:

mach

You need to use mach to build Servo. 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 servoshell, 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 servoshell.

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
debug release production
mach option -d
--debug		 -r
--release		 --prod
--production
optimised? no yes yes, more than in release
maximum RUST_LOG level trace info info
debug assertions? yesyes(!)no
debug info? yesnono
symbols? yesnoyes
finds resources in
current working dir?		 yesyesno(!)

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
production production-stripped profiling
mach --profile production production-stripped profiling
debug info? nonoyes
symbols? yesnoyes
finds resources in
current working dir?		 nonoyes(!)

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
  • 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 servoshell

When you build it yourself, servoshell will be in target/debug/servo or target/release/servo. You can run it directly as shown above, but we recommend using mach instead.

To run servoshell with mach, replace ./servo with ./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 of servoshell with the same options:

$ target/debug/servo https://demo.servo.org
$ ./mach run -d -- https://demo.servo.org