mirror of
https://github.com/servo/servo.git
synced 2025-08-08 23:15:33 +01:00
Update in-tree docs to point to the new book (#32743)
* Update in-tree docs to point to the new book * Revive build setup section in README as quickstart guide * Apply feedback about titles
This commit is contained in:
Delan Azabani
GitHub
parent
72e6a1f007
commit
34d9be70f9
12 changed files with 63 additions and 1413 deletions
209
README.md
209
README.md
|
|
@ -4,75 +4,44 @@ Servo is a prototype web browser engine written in the
|
|||
[Rust](https://github.com/rust-lang/rust) language. It is currently developed on
|
||||
64-bit macOS, 64-bit Linux, 64-bit Windows, and Android.
|
||||
|
||||
Servo welcomes contribution from everyone. See
|
||||
[`CONTRIBUTING.md`](CONTRIBUTING.md) and [`HACKING_QUICKSTART.md`](docs/HACKING_QUICKSTART.md)
|
||||
for help getting started.
|
||||
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.
|
||||
|
||||
Visit the [Servo Project page](https://servo.org/) for news and guides.
|
||||
## Getting started
|
||||
|
||||
## Getting Servo
|
||||
|
||||
``` sh
|
||||
git clone https://github.com/servo/servo
|
||||
cd servo
|
||||
```
|
||||
|
||||
- Your CARGO_HOME needs to point to (or be in) the same drive as your
|
||||
Servo repository ([#28530](https://github.com/servo/servo/issues/28530)).
|
||||
- The Servo repository is big! If you have an unreliable network connection, consider
|
||||
[making a shallow clone](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/).
|
||||
|
||||
|
||||
## Build Setup
|
||||
|
||||
* [macOS](#macos)
|
||||
* [Linux](#Linux)
|
||||
* [Windows](#windows)
|
||||
* [Android](https://github.com/servo/servo/wiki/Building-for-Android)
|
||||
|
||||
If these instructions fail or you would like to install dependencies
|
||||
manually, try the [manual build setup][manual-build].
|
||||
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).
|
||||
|
||||
### macOS
|
||||
|
||||
- Ensure that the version showed by `python --version` is >= 3.10:
|
||||
- Install [Xcode](https://developer.apple.com/xcode/)
|
||||
- Install [Homebrew](https://brew.sh/)
|
||||
- Run `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`. Ensure that `rust`
|
||||
and `cargo` are available commands — you may need to restart your shell.
|
||||
- Run `./mach bootstrap`<br/>
|
||||
*Note: This will install the recommended version of GStreamer globally on your system.*
|
||||
- Download and install [`python`](https://www.python.org/downloads/macos/), [Xcode](https://developer.apple.com/xcode/), and [`brew`](https://brew.sh/)
|
||||
- Install `rustup`: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
|
||||
- Restart your shell to make sure `cargo` is available
|
||||
- Install the other dependencies: `./mach bootstrap`
|
||||
- Build servoshell: `./mach build`
|
||||
|
||||
### Linux
|
||||
|
||||
- Run `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`. Ensure that `rust`
|
||||
and `cargo` are available commands — you may need to restart your shell.
|
||||
- Install Python (version >= 3.10):
|
||||
- **Debian-like:** Run `sudo apt install python3-pip python3-venv`
|
||||
- **Fedora:** Run `sudo dnf install python3 python3-pip python3-devel`
|
||||
- **Arch:** Run `sudo pacman -S --needed python python-pip`
|
||||
- **Gentoo:** Run `sudo emerge dev-python/pip`
|
||||
- Run `./mach bootstrap`
|
||||
- Install `curl` and `python`:
|
||||
- Arch: `sudo pacman -S --needed curl python python-pip`
|
||||
- Debian, Ubuntu: `sudo apt install curl python3-pip python3-venv`
|
||||
- Fedora: `sudo dnf install curl python3 python3-pip python3-devel`
|
||||
- Gentoo: `sudo emerge net-misc/curl dev-python/pip`
|
||||
- Install `rustup`: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
|
||||
- Restart your shell to make sure `cargo` is available
|
||||
- Install the other dependencies: `./mach bootstrap`
|
||||
- Build servoshell: `./mach build`
|
||||
|
||||
### Windows
|
||||
|
||||
- Download and run [`rustup-init.exe`](https://win.rustup.rs/)
|
||||
- Make sure to select *Quick install via the Visual Studio Community
|
||||
installer* or otherwise install Visual Studio 2022.
|
||||
- In the *Visual Studio Installer* ensure the following components are installed for Visual Studio 2022:
|
||||
- **Windows 10 SDK (10.0.19041.0)** (`Microsoft.VisualStudio.Component.Windows10SDK.19041`)
|
||||
- **MSVC v143 - VS 2022 C++ x64/x86 build tools (Latest)** (`Microsoft.VisualStudio.Component.VC.Tools.x86.x64`)
|
||||
- **C++ ATL for latest v143 build tools (x86 & x64)** (`Microsoft.VisualStudio.Component.VC.ATL`)
|
||||
- **C++ MFC for latest v143 build tools (x86 & x64)** (`Microsoft.VisualStudio.Component.VC.ATLMFC`)
|
||||
- Install [chocolatey](https://chocolatey.org/)
|
||||
- Install [Python 3.11](https://www.python.org/downloads/windows/)
|
||||
- Run `mach bootstrap`
|
||||
+ *This will install CMake, Git, and Ninja via choco in an
|
||||
Administrator console. Allow the scripts to run and once
|
||||
the operation finishes, close the new console.*
|
||||
- Run `refreshenv`
|
||||
|
||||
See also [Windows Troubleshooting Tips][windows-tips].
|
||||
- Download and install [`python`](https://www.python.org/downloads/windows/), [`choco`](https://chocolatey.org/install#individual), and [`rustup`](https://win.rustup.rs/)
|
||||
- Be sure to select *Quick install via the Visual Studio Community installer*
|
||||
- In the Visual Studio Installer, ensure the following components are installed:
|
||||
- **Windows 10 SDK (10.0.19041.0)** (`Microsoft.VisualStudio.Component.Windows10SDK.19041`)
|
||||
- **MSVC v143 - VS 2022 C++ x64/x86 build tools (Latest)** (`Microsoft.VisualStudio.Component.VC.Tools.x86.x64`)
|
||||
- **C++ ATL for latest v143 build tools (x86 & x64)** (`Microsoft.VisualStudio.Component.VC.ATL`)
|
||||
- **C++ MFC for latest v143 build tools (x86 & x64)** (`Microsoft.VisualStudio.Component.VC.ATLMFC`)
|
||||
- Restart your shell to make sure `cargo` is available
|
||||
- Install the other dependencies: `.\mach bootstrap`
|
||||
- Build servoshell: `.\mach build`
|
||||
|
||||
### Android
|
||||
|
||||
|
|
@ -94,126 +63,4 @@ See also [Windows Troubleshooting Tips][windows-tips].
|
|||
"platforms;android-33" \
|
||||
"system-images;android-33;google_apis;x86_64"
|
||||
```
|
||||
For information about building and running the Android build, see
|
||||
the [Android documentation][android-docs].
|
||||
|
||||
## Building
|
||||
|
||||
Servo is built with [Cargo](https://crates.io/), the Rust package manager.
|
||||
We also use Mozilla's Mach tools to orchestrate the build and other tasks.
|
||||
You can call Mach like this:
|
||||
|
||||
On Unix systems:
|
||||
```
|
||||
./mach [command] [arguments]
|
||||
```
|
||||
On Windows Commandline:
|
||||
```
|
||||
mach.bat [command] [arguments]
|
||||
```
|
||||
The examples below will use Unix, but the same applies to Windows.
|
||||
|
||||
### The Rust compiler
|
||||
|
||||
Servo's build system uses rustup.rs to automatically download a Rust compiler.
|
||||
This is a specific version of Rust Nightly determined by the
|
||||
[`rust-toolchain.toml`](https://github.com/servo/servo/blob/main/rust-toolchain.toml) file.
|
||||
|
||||
### Normal build
|
||||
|
||||
To build Servo in development mode.
|
||||
This is useful for development, but the resulting binary is very slow:
|
||||
|
||||
``` sh
|
||||
./mach build --dev
|
||||
./mach run tests/html/about-mozilla.html
|
||||
```
|
||||
|
||||
### Release build
|
||||
For benchmarking, performance testing, or real-world use.
|
||||
Add the `--release` flag to create an optimized build:
|
||||
|
||||
``` sh
|
||||
./mach build --release
|
||||
./mach run --release tests/html/about-mozilla.html
|
||||
```
|
||||
|
||||
### Android build
|
||||
|
||||
For an armv7 Android build run the following command.
|
||||
|
||||
```shell
|
||||
./mach build --android
|
||||
```
|
||||
|
||||
### Checking for build errors, without building
|
||||
|
||||
If you’re making changes to one crate that cause build errors in another crate,
|
||||
consider this instead of a full build:
|
||||
|
||||
```sh
|
||||
./mach check
|
||||
```
|
||||
|
||||
It will run `cargo check`, which runs the analysis phase of the compiler
|
||||
(and so shows build errors if any) but skips the code generation phase.
|
||||
This can be a lot faster than a full build,
|
||||
though of course it doesn’t produce a binary you can run.
|
||||
|
||||
## Running
|
||||
|
||||
Run Servo with the command:
|
||||
|
||||
```sh
|
||||
./servo [url] [arguments] # if you run with nightly build
|
||||
./mach run [url] [arguments] # if you run with mach
|
||||
|
||||
# For example
|
||||
./mach run https://www.google.com
|
||||
```
|
||||
|
||||
### Commandline Arguments
|
||||
|
||||
- `-p INTERVAL` turns on the profiler and dumps info to the console every
|
||||
`INTERVAL` seconds
|
||||
- `-s SIZE` sets the tile size for painting; defaults to 512
|
||||
- `-z` disables all graphical output; useful for running JS / layout tests
|
||||
- `-Z help` displays useful output to debug servo
|
||||
|
||||
### Keyboard Shortcuts
|
||||
|
||||
- `Ctrl`+`L` opens URL prompt (`Cmd`+`L` on Mac)
|
||||
- `Ctrl`+`R` reloads current page (`Cmd`+`R` on Mac)
|
||||
- `Ctrl`+`-` zooms out (`Cmd`+`-` on Mac)
|
||||
- `Ctrl`+`=` zooms in (`Cmd`+`=` on Mac)
|
||||
- `Alt`+`left arrow` goes backwards in the history (`Cmd`+`left arrow` on Mac)
|
||||
- `Alt`+`right arrow` goes forwards in the history (`Cmd`+`right arrow` on Mac)
|
||||
- `Ctrl`+`Q` exits Servo (`Cmd`+`Q` on Mac)
|
||||
- `Esc` exits fullscreen
|
||||
|
||||
### Runtime dependencies
|
||||
|
||||
#### Linux
|
||||
|
||||
* `GStreamer` >=1.18
|
||||
* `gst-plugins-base` >=1.18
|
||||
* `gst-plugins-good` >=1.18
|
||||
* `gst-plugins-bad` >=1.18
|
||||
* `gst-plugins-ugly` >=1.18
|
||||
* `libXcursor`
|
||||
* `libXrandr`
|
||||
* `libXi`
|
||||
* `libxkbcommon`
|
||||
* `vulkan-loader`
|
||||
|
||||
## Developing
|
||||
|
||||
There are lots of mach commands you can use. You can list them with `./mach
|
||||
--help`.
|
||||
|
||||
|
||||
The generated documentation can be found on https://doc.servo.org/servo/index.html
|
||||
|
||||
[manual-build]: https://github.com/servo/servo/wiki/Building#manual-build-setup
|
||||
[windows-tips]: https://github.com/servo/servo/wiki/Building#troubleshooting-the-windows-build
|
||||
[android-docs]: https://github.com/servo/servo/wiki/Building-for-Android
|
||||
- Follow the instructions above for the platform you are building on
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue