2015-11-26 20:18:21 +00:00
# The Servo Parallel Browser Engine Project
2012-02-08 19:29:12 +00:00
2016-04-15 20:32:49 +00:00
[![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)
2014-09-09 18:33:47 +00:00
Servo is a prototype web browser engine written in the
2015-04-09 03:10:42 +00:00
[Rust ](https://github.com/rust-lang/rust ) language. It is currently developed on
2016-05-28 00:34:55 +00:00
64bit OS X, 64bit Linux, and Android.
2012-08-18 02:41:22 +00:00
2013-10-14 15:28:11 +00:00
Servo welcomes contribution from everyone. See
2016-04-19 00:43:00 +00:00
[`CONTRIBUTING.md` ](CONTRIBUTING.md ) and [`HACKING_QUICKSTART.md` ](docs/HACKING_QUICKSTART.md )
2015-10-26 05:33:41 +00:00
for help getting started.
2013-10-14 15:28:11 +00:00
2015-12-04 03:06:17 +00:00
Visit the [Servo Project page ](https://servo.org/ ) for news and guides.
2015-11-17 10:45:38 +00:00
2016-08-17 00:16:55 +00:00
## Setting up your environment
2012-10-18 06:24:02 +00:00
2016-08-17 00:16:55 +00:00
Please select your operating system:
* [OS X ](#os-x )
* [Debian-based Linuxes ](#on-debian-based-linuxes )
* [Fedora ](#on-fedora )
* [Arch Linux ](#on-arch-linux )
2016-10-01 20:15:03 +00:00
* [openSUSE ](#on-opensuse-linux )
2016-08-17 00:16:55 +00:00
* [Gentoo Linux ](#on-gentoo-linux )
2016-10-06 21:56:38 +00:00
* [Microsoft Windows (MSVC) ](#on-windows-msvc )
* [Microsoft Windows (mingw) ](#on-windows-mingw )
2016-08-17 00:16:55 +00:00
* [Android ](#cross-compilation-for-android )
#### OS X
#### On OS X (homebrew)
2012-05-10 22:20:26 +00:00
2013-04-04 16:49:08 +00:00
``` sh
2016-10-25 10:51:03 +00:00
brew install automake pkg-config python cmake yasm
2014-08-05 13:31:21 +00:00
pip install virtualenv
2013-04-04 16:49:08 +00:00
```
2016-08-17 00:16:55 +00:00
#### On OS X (MacPorts)
2012-08-22 18:50:10 +00:00
2013-04-04 16:49:08 +00:00
``` sh
2016-10-25 10:51:03 +00:00
sudo port install python27 py27-virtualenv cmake yasm
2013-04-04 16:49:08 +00:00
```
2016-10-18 17:49:43 +00:00
#### On OS X >= 10.11 (El Capitan), you also have to install OpenSSL
2016-02-19 19:58:51 +00:00
``` sh
brew install openssl
2016-09-14 15:29:51 +00:00
export OPENSSL_INCLUDE_DIR="$(brew --prefix openssl)/include"
export OPENSSL_LIB_DIR="$(brew --prefix openssl)/lib"
2016-09-21 02:40:02 +00:00
2016-08-11 05:10:38 +00:00
./mach build ...
```
2016-10-18 17:49:43 +00:00
If you've already partially compiled servo but forgot to do this step, run `./mach clean` , set the shell variables, and recompile.
2016-07-21 02:23:18 +00:00
2016-08-17 00:16:55 +00:00
#### On Debian-based Linuxes
2012-05-10 22:20:26 +00:00
2013-04-04 16:49:08 +00:00
``` sh
2016-04-02 07:43:33 +00:00
sudo apt-get install git curl freeglut3-dev autoconf \
2014-03-01 00:40:38 +00:00
libfreetype6-dev libgl1-mesa-dri libglib2.0-dev xorg-dev \
2016-01-12 19:27:13 +00:00
gperf g++ build-essential cmake virtualenv python-pip \
2015-12-23 15:05:37 +00:00
libssl-dev libbz2-dev libosmesa6-dev libxmu6 libxmu-dev \
2016-08-18 16:22:06 +00:00
libglu1-mesa-dev libgles2-mesa-dev libegl1-mesa-dev libdbus-1-dev
2013-04-04 16:49:08 +00:00
```
2015-09-02 05:31:34 +00:00
If 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.
2012-05-10 22:20:26 +00:00
2016-01-02 14:10:10 +00:00
If `virtualenv` does not exist, try `python-virtualenv` .
2016-08-17 00:16:55 +00:00
#### On Fedora
2014-04-17 01:31:08 +00:00
``` sh
2015-05-22 20:33:08 +00:00
sudo dnf install curl freeglut-devel libtool gcc-c++ libXi-devel \
2016-02-06 06:21:48 +00:00
freetype-devel mesa-libGL-devel mesa-libEGL-devel glib2-devel libX11-devel libXrandr-devel gperf \
2015-09-16 15:39:10 +00:00
fontconfig-devel cabextract ttmkfdir python python-virtualenv python-pip expat-devel \
2016-05-26 11:08:22 +00:00
rpm-build openssl-devel cmake bzip2-devel libXcursor-devel libXmu-devel mesa-libOSMesa-devel \
2016-08-18 16:22:06 +00:00
dbus-devel
2014-04-17 01:31:08 +00:00
```
2016-10-01 20:15:03 +00:00
#### On openSUSE Linux
``` sh
sudo zypper install libX11-devel libexpat-devel libbz2-devel Mesa-libEGL-devel Mesa-libGL-devel cabextract cmake \
dbus-1-devel fontconfig-devel freetype-devel gcc-c++ git glib2-devel gperf \
harfbuzz-devel libOSMesa-devel libXcursor-devel libXi-devel libXmu-devel libXrandr-devel libopenssl-devel \
2016-10-02 08:41:18 +00:00
python-pip python-virtualenv rpm-build glu-devel
2016-10-01 20:15:03 +00:00
```
2016-08-17 00:16:55 +00:00
#### On Arch Linux
2014-09-06 09:17:27 +00:00
``` sh
2016-06-19 16:19:49 +00:00
sudo pacman -S --needed base-devel git python2 python2-virtualenv python2-pip mesa cmake bzip2 libxmu glu pkg-config
2014-09-06 09:17:27 +00:00
```
2016-08-17 00:16:55 +00:00
#### On Gentoo Linux
2015-10-02 21:56:31 +00:00
```sh
sudo emerge net-misc/curl media-libs/freeglut \
media-libs/freetype media-libs/mesa dev-util/gperf \
dev-python/virtualenv dev-python/pip dev-libs/openssl \
x11-libs/libXmu media-libs/glu x11-base/xorg-server
```
2016-10-06 21:56:38 +00:00
#### On Windows MSVC
Install Git for Windows (https://git-scm.com/download/win). DO allow it to add git.exe to the PATH (default
settings for the installer are fine).
Install Visual Studio 2015 Community Edition (https://www.visualstudio.com/). You MUST add "Visual C++" to the
list of installed components. It is not on by default.
Install Python for Windows (https://www.python.org/downloads/release/python-2711/). The windows x86-64 MSI installer is fine.
You should change the installation to install the "Add python.exe to Path" feature.
Install virtualenv.
In a normal Windows Shell (cmd.exe or "Command Prompt" from the start menu), do:
```
pip install virtualenv
```
If this does not work, you may need to reboot for the changed PATH settings (by the python installer) to take effect.
#### On Windows mingw
2016-01-25 21:29:52 +00:00
Download Python for Windows [here ](https://www.python.org/downloads/release/python-2711/ ). This is
required for the SpiderMonkey build on Windows.
Install MSYS2 from [here ](https://msys2.github.io/ ). After you have done so, open an MSYS shell
2016-07-25 02:56:13 +00:00
window and update the core libraries and install new packages. The extra step at the end is to
2016-10-01 15:48:10 +00:00
downgrade GCC to 5.4, as the GCC6 versions in mingw currently fail to compile some of our
2016-07-25 02:56:13 +00:00
dependencies. We are upgrading to a gcc-free build on Windows as soon as possible:
2016-01-25 21:29:52 +00:00
```sh
2016-06-12 11:47:29 +00:00
pacman -Su
2016-01-25 21:29:52 +00:00
pacman -Sy git mingw-w64-x86_64-toolchain mingw-w64-x86_64-freetype \
mingw-w64-x86_64-icu mingw-w64-x86_64-nspr mingw-w64-x86_64-ca-certificates \
mingw-w64-x86_64-expat mingw-w64-x86_64-cmake tar diffutils patch \
2016-08-18 16:22:06 +00:00
patchutils make python2-setuptools
2016-07-25 02:56:13 +00:00
export GCC_URL=http://repo.msys2.org/mingw/x86_64/mingw-w64-x86_64-gcc
export GCC_EXT=5.4.0-1-any.pkg.tar.xz
pacman -U --noconfirm $GCC_URL-$GCC_EXT $GCC_URL-ada-$GCC_EXT \
$GCC_URL-fortran-$GCC_EXT $GCC_URL-libgfortran-$GCC_EXT $GCC_URL-libs-$GCC_EXT \
$GCC_URL-objc-$GCC_EXT
2016-01-25 21:29:52 +00:00
easy_install-2.7 pip virtualenv
```
Open a new MSYS shell window as Administrator and remove the Python binaries (they
are not compatible with our `mach` driver script yet, unfortunately):
```sh
cd /mingw64/bin
mv python2.exe python2-mingw64.exe
mv python2.7.exe python2.7-mingw64.exe
```
Now, open a MINGW64 (not MSYS!) shell window, and you should be able to build servo as usual!
2016-08-17 00:16:55 +00:00
#### Cross-compilation for Android
2013-08-28 02:21:34 +00:00
2014-09-09 18:33:47 +00:00
Pre-installed Android tools are needed. See wiki for
2015-12-04 03:06:17 +00:00
[details ](https://github.com/servo/servo/wiki/Building-for-Android )
2013-08-28 02:21:34 +00:00
2014-08-22 20:34:52 +00:00
## The Rust compiler
2015-12-30 13:50:38 +00:00
Servo's build system automatically downloads a Rust compiler to build itself.
2015-05-19 15:45:31 +00:00
This is normally a specific revision of Rust upstream, but sometimes has a
backported patch or two.
2015-12-30 13:50:38 +00:00
If you'd like to know which nightly build of Rust we use, see
2016-03-08 12:48:29 +00:00
[`rust-nightly-date` ](https://github.com/servo/servo/blob/master/rust-nightly-date ).
2013-01-10 02:52:17 +00:00
2012-10-18 06:24:02 +00:00
## Building
2012-05-05 23:51:26 +00:00
2014-09-09 18:33:47 +00:00
Servo is built with Cargo, the Rust package manager. We also use Mozilla's
Mach tools to orchestrate the build and other tasks.
### Normal build
2013-07-10 17:12:46 +00:00
2015-05-14 16:26:18 +00:00
To build Servo in development mode. This is useful for development, but
the resulting binary is very slow.
2013-04-04 16:49:08 +00:00
``` sh
2014-09-09 18:33:47 +00:00
git clone https://github.com/servo/servo
2013-04-04 16:49:08 +00:00
cd servo
2015-05-14 16:26:18 +00:00
./mach build --dev
2014-09-09 14:18:18 +00:00
./mach run tests/html/about-mozilla.html
2013-04-04 16:49:08 +00:00
```
2013-03-13 15:36:44 +00:00
2016-10-06 21:56:38 +00:00
Or on Windows MSVC, in a normal Command Prompt (cmd.exe):
``` cmd
git clone https://github.com/servo/servo
cd servo
mach.bat build --dev
```
2015-05-14 16:26:18 +00:00
For benchmarking, performance testing, or
2015-05-04 17:57:06 +00:00
real-world use, add the `--release` flag to create an optimized build:
``` sh
./mach build --release
./mach run --release tests/html/about-mozilla.html
```
2014-09-09 14:18:18 +00:00
### Building for Android target
2013-08-28 02:21:34 +00:00
``` sh
2014-09-09 18:33:47 +00:00
git clone https://github.com/servo/servo
2013-08-28 02:21:34 +00:00
cd servo
2016-05-24 10:09:29 +00:00
export ANDROID_SDK="/path/to/sdk"
export ANDROID_NDK="/path/to/ndk"
export ANDROID_TOOLCHAIN="/path/to/toolchain"
export PATH="$PATH:/path/to/toolchain/bin"
./mach build --release --android
2016-07-04 22:58:27 +00:00
./mach package --release --android
2013-08-28 02:21:34 +00:00
```
2014-10-03 21:45:28 +00:00
Rather than setting the `ANDROID_*` environment variables every time, you can
also create a `.servobuild` file and then edit it to contain the correct paths
to the Android SDK/NDK tools:
```
cp servobuild.example .servobuild
# edit .servobuild
```
2013-07-10 17:12:46 +00:00
## Running
2016-05-20 14:18:58 +00:00
Use `./mach run [url]` to run Servo. Also, don't miss the info on the [browserhtml page ](https://github.com/browserhtml/browserhtml ) on how to run the Browser.html
full tech demo (it provides a more browser-like experience than just browsing a single
URL with servo).
2015-02-28 17:33:52 +00:00
2013-07-10 17:12:46 +00:00
### Commandline Arguments
- `-p INTERVAL` turns on the profiler and dumps info to the console every
`INTERVAL` seconds
2014-12-08 17:28:10 +00:00
- `-s SIZE` sets the tile size for painting; defaults to 512
2013-10-22 20:52:14 +00:00
- `-z` disables all graphical output; useful for running JS / layout tests
2016-07-21 02:23:18 +00:00
- `-Z help` displays useful output to debug servo
2013-07-10 17:12:46 +00:00
### Keyboard Shortcuts
2016-10-01 13:02:18 +00:00
- `Ctrl` +`-` zooms out
- `Ctrl` +`=` zooms in
2016-06-24 17:55:46 +00:00
- `Alt` +`left arrow` goes backwards in the history
- `Alt` +`right arrow` goes forwards in the history
2013-07-16 22:01:15 +00:00
- `Esc` exits servo
2013-07-10 17:12:46 +00:00
## Developing
2014-09-09 18:33:47 +00:00
There are lots of mach commands you can use. You can list them with `./mach
--help`.
2015-08-06 07:36:22 +00:00
The generated documentation can be found on http://doc.servo.org/servo/index.html