Skip to content

Add initial Embedding chapter #223

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jschwe merged 4 commits into from
Apr 10, 2026
Merged

Add initial Embedding chapter #223

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
371bf83
Add initial Embedding chapter
jschwe Apr 8, 2026
3523c2a
finish sentence
jschwe Apr 9, 2026
c80871b
light copyediting
delan Apr 10, 2026
e9b9462
clarify LTS MSRV policy
jschwe Apr 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions src/SUMMARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,11 @@
- [Building Offline](building/building-offline.md)
- [General Troubleshooting](building/general-troubleshooting.md)

# Embedding Servo

- [Overview](embedding/overview.md)
- [LTS Release](embedding/lts-release.md)

# Contributing

- [Getting Started](contributing/getting-started.md)
Expand Down
39 changes: 39 additions & 0 deletions src/embedding/lts-release.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Servo LTS releases

Besides our monthly releases, the Servo community provides best-effort long-term support (LTS) releases.
Since Servo’s public API is still evolving, these LTS releases may be preferable for embedders that have limited resources to stay up to date with the latest Servo release.
LTS releases allow embedders to have scheduled upgrade timeframes and benefit from security fixes, including security fixes for our JavaScript engine.

## Scope of LTS releases

**Servo is provided AS IS and no specific guarantees are given.**
LTS releases (and the details below) are provided on a best-effort basis.
For now, this means:

- A new LTS release / branch is introduced every 6 months, based on the current regular release at the time.
- The expected support duration is 9 months, giving embedders time to migrate to the next LTS release.
- The LTS release will receive security fixes only.
- Patch releases will be released as needed; there is no fixed schedule.
- Only the `servo` library and its dependencies are in scope.
The browser demo, servoshell, is explicitly out of scope.
- The minimum supported Rust version (MSRV) will not be increased on the LTS branch, but may increase when upgrading to the next LTS version
- Releases will be published to crates.io **if possible**, but embedders should expect that `git` dependencies might be required.

## Patching CVEs in downstream crates

Many Rust libraries generally don't backport CVE fixes to older releases / branches.
Since MSRV increases are treated as breaking changes, this can lead to us being unable to upgrade to a newer released version of a library (which patches the CVE).
These situations will be handled on a case-by-case basis, ideally in cooperation with the upstream maintainer, and will likely involve pulling a patched version of the library via `git`.
This means that LTS patch releases of Servo shouldn't be expected to be avaiable on crates.io, since they could have `git` dependencies.

## Limitations

- Servo is provided AS IS and no specific guarantees are given, including security guarantees.
LTS releases are provided on a best-effort basis by interested community members.
- As mentioned above, Servo does not have a 1.0 release yet, which means that production usage of Servo should be carefully evaluated.
The risk profile of using Servo in an app to render known, trusted content is very different from using Servo as a browser to render arbitrary content.

## LTS release maintainers

- @jschwe (Jonathan Schwender)
- TBD
38 changes: 38 additions & 0 deletions src/embedding/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Overview: Embedding Servo

Servo is a web browser engine, which we intend to be easy to embed in other applications.
Currently, the documentation on how to embed Servo is sparse, and this Chapter is an active work in progress.
Please feel free to reach out to us on the [Servo Zulip] chat if you have any questions.

[Servo Zulip]: https://servo.zulipchat.com

## Building servo without mach

It is possible to build servo directly with `cargo`, albeit you will likely need to reimplement some of the mach functionality.
Below is a short overview of things to keep in mind.


### Environment variables

`./mach` sets a number of environment variables to control the build, which is particularly required when cross-compiling to e.g., Android or OpenHarmony.
You can run `./mach print-env` to see which variables are set, and use that to configure your build.

### Media support

`./mach build` enables the `media-gstreamer` feature by default, which is not the case for regular builds.
`media-gstreamer` is required for media support on the common desktop platforms.
On Linux you will need to install the required `gstreamer` libraries via your package manager (e.g. by running ./mach bootstrap).
On macOS `./mach bootstrap` will install the required `gstreamer` libraries by installing the latest packages from https://github.com/servo/servo-build-deps/releases/tag/macOS.
On Windows you can install the gstreamer libraries from https://github.com/servo/servo-build-deps/releases/tag/msvc-deps (version 1.22.8).

### Resources

Servo requires some resources, and provides default versions via the `servo-default-resources` crate if the `baked-in-resources` feature is enabled.
This is achieved by baking the resources into the binary.
Embedders can opt-out, by disabling default-features, and providing their own resource reading mechanism via [servo_embedder_traits::submit_resource_reader].
In such a case the ResourceReader implementation is responsible for providing all resources.

[servo_embedder_traits::submit_resource_reader]: https://docs.rs/servo-embedder-traits/latest/embedder_traits/macro.submit_resource_reader.html

An example usage is the OpenHarmony port, which reads all resources from the filesystem: [ohos/resources.rs](https://github.com/servo/servo/blob/78c9fe2a4c7a645e7ec729094bfe3eb8a6c15189/ports/servoshell/egl/ohos/resources.rs).