1# The Servo Parallel Browser Engine Project 2 3[![Linux Build Status](https://img.shields.io/travis/servo/servo/master.svg?label=Linux%20build)](https://travis-ci.org/servo/servo) [![Windows Build Status](https://img.shields.io/appveyor/ci/servo/servo/master.svg?label=Windows%20build)](https://ci.appveyor.com/project/servo/servo/branch/master) [![Changelog #228](https://img.shields.io/badge/changelog-%23228-9E978E.svg)](https://changelog.com/podcast/228) 4 5Servo is a prototype web browser engine written in the 6[Rust](https://github.com/rust-lang/rust) language. It is currently developed on 764-bit OS X, 64-bit Linux, 64-bit Windows, and Android. 8 9Servo welcomes contribution from everyone. See 10[`CONTRIBUTING.md`](CONTRIBUTING.md) and [`HACKING_QUICKSTART.md`](docs/HACKING_QUICKSTART.md) 11for help getting started. 12 13Visit the [Servo Project page](https://servo.org/) for news and guides. 14 15## Setting up your environment 16 17### Rustup.rs 18 19Building servo requires [rustup](https://rustup.rs/), version 1.8.0 or more recent. 20If you have an older version, run `rustup self update`. 21 22To install on Windows, download and run [`rustup-init.exe`](https://win.rustup.rs/) 23then follow the onscreen instructions. 24 25To install on other systems, run: 26 27```sh 28curl https://sh.rustup.rs -sSf | sh 29``` 30 31This will also download the current stable version of Rust, which Servo won’t use. 32To skip that step, run instead: 33 34``` 35curl https://sh.rustup.rs -sSf | sh -s -- --default-toolchain none 36``` 37 38See also [Other installation methods]( 39https://github.com/rust-lang-nursery/rustup.rs/#other-installation-methods) 40 41### Other dependencies 42 43Please select your operating system: 44* [OS X](#os-x) 45* [Debian-based Linuxes](#on-debian-based-linuxes) 46* [Fedora](#on-fedora) 47* [Arch Linux](#on-arch-linux) 48* [openSUSE](#on-opensuse-linux) 49* [Gentoo Linux](#on-gentoo-linux) 50* [Microsoft Windows](#on-windows-msvc) 51* [Android](#cross-compilation-for-android) 52 53#### OS X 54#### On OS X (homebrew) 55 56``` sh 57brew install automake pkg-config python cmake yasm 58pip install virtualenv 59``` 60#### On OS X (MacPorts) 61 62``` sh 63sudo port install python27 py27-virtualenv cmake yasm 64``` 65#### On OS X >= 10.11 (El Capitan), you also have to install OpenSSL 66 67``` sh 68brew install openssl 69 70export OPENSSL_INCLUDE_DIR="$(brew --prefix openssl)/include" 71export OPENSSL_LIB_DIR="$(brew --prefix openssl)/lib" 72 73./mach build ... 74``` 75 76If you've already partially compiled servo but forgot to do this step, run `./mach clean`, set the shell variables, and recompile. 77 78#### On Debian-based Linuxes 79 80``` sh 81sudo apt install git curl autoconf libx11-dev \ 82 libfreetype6-dev libgl1-mesa-dri libglib2.0-dev xorg-dev \ 83 gperf g++ build-essential cmake virtualenv python-pip \ 84 libssl1.0-dev libbz2-dev libosmesa6-dev libxmu6 libxmu-dev \ 85 libglu1-mesa-dev libgles2-mesa-dev libegl1-mesa-dev libdbus-1-dev \ 86 libharfbuzz-dev ccache 87``` 88 89If you using a version prior to **Ubuntu 17.04** or **Debian Sid**, replace `libssl1.0-dev` with `libssl-dev`. 90 91If you are on **Ubuntu 14.04** and encountered errors on installing these dependencies involving `libcheese`, see [#6158](https://github.com/servo/servo/issues/6158) for a workaround. 92 93If `virtualenv` does not exist, try `python-virtualenv`. 94 95#### On Fedora 96 97``` sh 98sudo dnf install curl libtool gcc-c++ libXi-devel \ 99 freetype-devel mesa-libGL-devel mesa-libEGL-devel glib2-devel libX11-devel libXrandr-devel gperf \ 100 fontconfig-devel cabextract ttmkfdir python python-virtualenv python-pip expat-devel \ 101 rpm-build openssl-devel cmake bzip2-devel libXcursor-devel libXmu-devel mesa-libOSMesa-devel \ 102 dbus-devel ncurses-devel harfbuzz-devel ccache mesa-libGLU-devel 103``` 104#### On CentOS 105 106``` sh 107sudo yum install curl libtool gcc-c++ libXi-devel \ 108 freetype-devel mesa-libGL-devel mesa-libEGL-devel glib2-devel libX11-devel libXrandr-devel gperf \ 109 fontconfig-devel cabextract ttmkfdir python python-virtualenv python-pip expat-devel \ 110 rpm-build openssl-devel cmake3 bzip2-devel libXcursor-devel libXmu-devel mesa-libOSMesa-devel \ 111 dbus-devel ncurses-devel python34 harfbuzz-devel ccache 112``` 113#### On openSUSE Linux 114``` sh 115sudo zypper install libX11-devel libexpat-devel libbz2-devel Mesa-libEGL-devel Mesa-libGL-devel cabextract cmake \ 116 dbus-1-devel fontconfig-devel freetype-devel gcc-c++ git glib2-devel gperf \ 117 harfbuzz-devel libOSMesa-devel libXcursor-devel libXi-devel libXmu-devel libXrandr-devel libopenssl-devel \ 118 python-pip python-virtualenv rpm-build glu-devel ccache 119``` 120#### On Arch Linux 121 122``` sh 123sudo pacman -S --needed base-devel git python2 python2-virtualenv python2-pip mesa cmake bzip2 libxmu glu \ 124 pkg-config ttf-fira-sans harfbuzz ccache 125``` 126#### On Gentoo Linux 127 128```sh 129sudo emerge net-misc/curl \ 130 media-libs/freetype media-libs/mesa dev-util/gperf \ 131 dev-python/virtualenv dev-python/pip dev-libs/openssl \ 132 x11-libs/libXmu media-libs/glu x11-base/xorg-server \ 133 media-libs/harfbuzz dev-util/ccache 134``` 135#### On Windows (MSVC) 136 1371. Install Python for Windows (https://www.python.org/downloads/release/python-2714/). The Windows x86-64 MSI installer is fine. 138You should change the installation to install the "Add python.exe to Path" feature. 139 1402. Install virtualenv. 141 142 In a normal Windows Shell (cmd.exe or "Command Prompt" from the start menu), do: 143 ``` 144pip install virtualenv 145``` 146 If this does not work, you may need to reboot for the changed PATH settings (by the python installer) to take effect. 147 1483. Install Git for Windows (https://git-scm.com/download/win). DO allow it to add git.exe to the PATH (default 149settings for the installer are fine). 150 1514. Install Visual Studio Community 2017 (https://www.visualstudio.com/vs/community/). You MUST add "Visual C++" to the 152list of installed components. It is not on by default. Visual Studio 2017 MUST installed to the default location or mach.bat will not find it. 153> If you encountered errors with the environment above, do the following for a workaround: 154> 1. Download and install [Build Tools for Visual Studio 2017](https://www.visualstudio.com/thank-you-downloading-visual-studio/?sku=BuildTools&rel=15) 155> 2. Install `python2.7 x86-x64` and `virtualenv` 156> 3. Run `mach.bat build -d`. 157 158>If you have troubles with `x64 type` prompt as `mach.bat` set by default: 159> 1. you may need to choose and launch the type manually, such as `x86_x64 Cross Tools Command Prompt for VS 2017` in the Windows menu.) 160> 2. `cd to/the/path/servo` 161> 3. `python mach build -d` 162 163#### Cross-compilation for Android 164 165Pre-installed Android tools are needed. See wiki for 166[details](https://github.com/servo/servo/wiki/Building-for-Android) 167 168## The Rust compiler 169 170Servo's build system uses rustup.rs to automatically download a Rust compiler. 171This is a specific version of Rust Nightly determined by the 172[`rust-toolchain`](https://github.com/servo/servo/blob/master/rust-toolchain) file. 173 174## Building 175 176Servo is built with [Cargo](https://crates.io/), the Rust package manager. We also use Mozilla's 177Mach tools to orchestrate the build and other tasks. 178 179### Normal build 180 181To build Servo in development mode. This is useful for development, but 182the resulting binary is very slow. 183 184``` sh 185git clone https://github.com/servo/servo 186cd servo 187./mach build --dev 188./mach run tests/html/about-mozilla.html 189``` 190 191Or on Windows MSVC, in a normal Command Prompt (cmd.exe): 192``` cmd 193git clone https://github.com/servo/servo 194cd servo 195mach.bat build --dev 196``` 197 198For benchmarking, performance testing, or 199real-world use, add the `--release` flag to create an optimized build: 200 201``` sh 202./mach build --release 203./mach run --release tests/html/about-mozilla.html 204``` 205 206### Checking for build errors, without building 207 208If you’re making changes to one crate that cause build errors in another crate, 209consider this instead of a full build: 210 211```sh 212./mach check 213``` 214 215It will run `cargo check`, which runs the analysis phase of the compiler 216(and so shows build errors if any) but skips the code generation phase. 217This can be a lot faster than a full build, 218though of course it doesn’t produce a binary you can run. 219 220### Building for Android target 221 222``` sh 223git clone https://github.com/servo/servo 224cd servo 225 226export ANDROID_SDK="/path/to/sdk" 227export ANDROID_NDK="/path/to/ndk" 228export ANDROID_TOOLCHAIN="/path/to/toolchain" 229export PATH="$PATH:/path/to/toolchain/bin" 230 231./mach build --release --android 232./mach package --release --android 233``` 234 235Rather than setting the `ANDROID_*` environment variables every time, you can 236also create a `.servobuild` file and then edit it to contain the correct paths 237to the Android SDK/NDK tools: 238 239``` 240cp servobuild.example .servobuild 241# edit .servobuild 242``` 243 244## Running 245 246Run Servo with the command: 247 248```sh 249./servo [url] [arguments] # if you run with nightly build 250./mach run [url] [arguments] # if you run with mach 251 252# For example 253./mach run https://www.google.com 254``` 255 256### Commandline Arguments 257 258- `-p INTERVAL` turns on the profiler and dumps info to the console every 259 `INTERVAL` seconds 260- `-s SIZE` sets the tile size for painting; defaults to 512 261- `-z` disables all graphical output; useful for running JS / layout tests 262- `-Z help` displays useful output to debug servo 263 264### Keyboard Shortcuts 265 266- `Ctrl`+`-` zooms out 267- `Ctrl`+`=` zooms in 268- `Alt`+`left arrow` goes backwards in the history 269- `Alt`+`right arrow` goes forwards in the history 270- `Esc` exits servo 271 272## Developing 273 274There are lots of mach commands you can use. You can list them with `./mach 275--help`. 276 277 278The generated documentation can be found on http://doc.servo.org/servo/index.html 279