|
1 | 1 | Stylo |
2 | 2 | ===== |
3 | 3 |
|
4 | | -This repo contains Servo’s downstream fork of [Stylo](https://searchfox.org/mozilla-central/source/servo). |
| 4 | +**High-Performance CSS Style Engine** |
5 | 5 |
|
6 | | -The branches are as follows: |
| 6 | +[](https://github.com/servo/stylo/actions) |
| 7 | +[](https://crates.io/crates/stylo) |
| 8 | +[](https://docs.rs/stylo) |
| 9 | + |
7 | 10 |
|
8 | | -- [`upstream`](https://github.com/servo/style/tree/upstream) has upstream mozilla-central filtered to the paths we care about ([style.paths](style.paths)), but is otherwise unmodified |
9 | | -- [`main`](https://github.com/servo/style/tree/ci) has our downstream patches, plus the scripts and workflows for syncing with mozilla-central, to be rebased onto `upstream` |
| 11 | +Stylo is a high-performance, browser-grade CSS style engine written in Rust that powers [Servo](https://servo.org) and [Firefox](https://firefox.com). This repo contains Servo’s downstream version of Stylo. The upstream version lives in mozilla-central with the rest of the Gecko/Firefox codebase. |
10 | 12 |
|
11 | | -## Building Servo against your local Stylo |
| 13 | +Coordination of Stylo development happens: |
12 | 14 |
|
13 | | -Assuming your local `servo` and `stylo` directories are siblings, you can build `servo` against `stylo` by adding the following to `servo/Cargo.toml`: |
| 15 | +- Here in Github Issues |
| 16 | +- In the [#stylo](https://servo.zulipchat.com/#narrow/channel/417109-stylo) channel of the [Servo Zulip](https://servo.zulipchat.com/) |
| 17 | +- In the [#layout](https://chat.mozilla.org/#/room/#layout:mozilla.org) room of the Mozilla Matrix instance (matrix.mozilla.org) |
14 | 18 |
|
15 | | -```toml |
16 | | -[patch."https://github.com/servo/stylo"] |
17 | | -selectors = { path = "../stylo/selectors" } |
18 | | -servo_arc = { path = "../stylo/servo_arc" } |
19 | | -stylo_atoms = { path = "../stylo/stylo_atoms" } |
20 | | -style = { path = "../stylo/style" } |
21 | | -stylo_config = { path = "../stylo/stylo_config" } |
22 | | -stylo_dom = { path = "../stylo/stylo_dom" } |
23 | | -style_malloc_size_of = { path = "../stylo/malloc_size_of", package = "malloc_size_of" } |
24 | | -style_traits = { path = "../stylo/style_traits" } |
25 | | -``` |
| 19 | +## High-Level Documentation |
26 | 20 |
|
27 | | -## Syncing `upstream` with mozilla-central |
| 21 | +- This [Mozilla Hacks article](https://hacks.mozilla.org/2017/08/inside-a-super-fast-css-engine-quantum-css-aka-stylo) contains a high-level overview of the Stylo architecture. |
| 22 | +- There is a [chapter](https://book.servo.org/architecture/style.html) in the Servo Book (although it is a little out of date). |
28 | 23 |
|
29 | | -Start by generating a filtered copy of mozilla-central. This will cache the raw mozilla-central in `_cache/upstream`, storing the result in `_filtered`: |
| 24 | +## Branches |
30 | 25 |
|
31 | | -```sh |
32 | | -$ ./sync.sh _filtered |
33 | | -``` |
| 26 | +The branches are as follows: |
34 | 27 |
|
35 | | -If `_filtered` already exists, you will need to delete it and try again: |
| 28 | +- [**upstream**](https://github.com/servo/style/tree/upstream) has upstream [mozilla-central](https://searchfox.org/mozilla-central/source/servo) filtered to the paths we care about ([style.paths](style.paths)), but is otherwise unmodified. |
| 29 | +- [**main**](https://github.com/servo/style/tree/ci) adds our downstream patches, plus the scripts and workflows for syncing with mozilla-central on top of **upstream**. |
36 | 30 |
|
37 | | -```sh |
38 | | -$ rm -Rf _filtered |
39 | | -``` |
| 31 | +> [!WARNING] |
| 32 | +> This repo syncs from upstream by creating a new branch and then rebasing our changes on top of it. This means that `git pull` will not work across syncs (you will need to use `git fetch`, `git reset` and `git rebase`). |
40 | 33 |
|
41 | | -Now overwrite our `upstream` with those commits and push: |
| 34 | +More information on the syncing process is available in [SYNCING.md](SYNCING.md) |
42 | 35 |
|
43 | | -```sh |
44 | | -$ git fetch -f --progress ./_filtered master:upstream |
45 | | -$ git push -fu --progress origin upstream |
46 | | -``` |
| 36 | +## Crates |
47 | 37 |
|
48 | | -## Rebasing `main` onto `upstream` |
| 38 | +A guide to the crates contained within this repo |
49 | 39 |
|
50 | | -Start by fetching `upstream` into your local repo: |
| 40 | +### Stylo Crates |
51 | 41 |
|
52 | | -```sh |
53 | | -$ git fetch -f origin upstream:upstream |
54 | | -``` |
| 42 | +These crates are largely implementation details of Stylo, although you may need to use some of them directly if you use Stylo. |
55 | 43 |
|
56 | | -In general, the filtering process is deterministic, yielding the same commit hashes each time, so we can rebase normally: |
| 44 | +| Directory | Crate | Notes | |
| 45 | +| --- | --- | --- | |
| 46 | +| style | [](https://crates.io/crates/stylo) | The main Stylo crate containing the entire CSS engine | |
| 47 | +| style_traits | [](https://crates.io/crates/stylo_traits) | Types and traits which allow other code to interoperate with Stylo without depending on the main crate directly. | |
| 48 | +| stylo_dom | [](https://crates.io/crates/stylo_dom) | Similar to stylo_traits (but much smaller) | |
| 49 | +| stylo_atoms | [](https://crates.io/crates/stylo_atoms) | [Atoms](https://docs.rs/string_cache/latest/string_cache/struct.Atom.html) for CSS and HTML event related strings | |
| 50 | +| stylo_config | [](https://crates.io/crates/stylo_config) | Configuration for Stylo. Can be used to set runtime preferences (enabling/disabling properties, etc) | |
| 51 | +| stylo_static_prefs | [](https://crates.io/crates/stylo_static_prefs) | Static configuration for Stylo. Config be overridden by patching in a replacement crate. | |
| 52 | +| style_derive | [](https://crates.io/crates/stylo_derive) | Internal derive macro for stylo crate | |
57 | 53 |
|
58 | | -```sh |
59 | | -$ git rebase upstream |
60 | | -``` |
| 54 | +### Standalone Crates |
61 | 55 |
|
62 | | -But if the filtering config changes or Mozilla moves to GitHub, the commit hashes on `upstream` may change. In this case, we need to tell git where the old upstream ends and our own commits start (notice the `~`): |
| 56 | +These crates form part of Stylo but are also be useful standalone. |
63 | 57 |
|
64 | | -```sh |
65 | | -$ git log --pretty=\%H --grep='Servo initial downstream commit' |
66 | | -e62d7f0090941496e392e1dc91df103a38e3f488 |
| 58 | +| Directory | Crate | Notes | |
| 59 | +| --- | --- | --- | |
| 60 | +| selectors | [](https://crates.io/crates/selectors) | CSS Selector matching | |
| 61 | +| servo_arc | [](https://crates.io/crates/servo_arc) | A variant on `std::Arc` | |
67 | 62 |
|
68 | | -$ git rebase --onto upstream e62d7f0090941496e392e1dc91df103a38e3f488~ |
69 | | -Successfully rebased and updated refs/heads/main. |
70 | | -``` |
| 63 | +You may also be interested in the `cssparser` crate which lives in the [servo/rust-cssparser](https://github.com/servo/rust-cssparser) repo. |
71 | 64 |
|
72 | | -`start-rebase.sh` takes care of this automatically, but you should still use `git rebase` for subsequent steps like `--continue` and `--abort`: |
| 65 | +### Support Crates |
73 | 66 |
|
74 | | -```sh |
75 | | -$ ./start-rebase.sh upstream |
76 | | -$ ./start-rebase.sh upstream -i # interactive |
77 | | -$ git rebase --continue # not ./start-rebase.sh --continue |
78 | | -$ git rebase --abort # not ./start-rebase.sh --abort |
79 | | -``` |
| 67 | +Low-level crates which could technically be used standalone but are unlikely to be generally useful in practice. |
| 68 | + |
| 69 | +| Directory | Crate | Notes | |
| 70 | +| --- | --- | --- | |
| 71 | +| malloc_size_of | [](https://crates.io/crates/stylo_malloc_size_of) | Heap size measurement for Stylo values | |
| 72 | +| to_shmem | [](https://crates.io/crates/to_shmem) | Internal utility crate for sharing memory across processes. | |
| 73 | +| to_shmem_derive | [](https://crates.io/crates/to_shmem_derive) | Internal derive macro for to_shmem crate | |
80 | 74 |
|
81 | | -Or if we aren’t ready to rebase onto the tip of upstream: |
| 75 | +## Building Servo Against a Local Copy of Stylo |
| 76 | + |
| 77 | +Assuming your local `servo` and `stylo` directories are siblings, you can build `servo` against `stylo` by adding the following to `servo/Cargo.toml`: |
82 | 78 |
|
83 | | -```sh |
84 | | -$ ./start-rebase.sh upstream~10 -i |
| 79 | +```toml |
| 80 | +[patch."https://github.com/servo/stylo"] |
| 81 | +selectors = { path = "../stylo/selectors" } |
| 82 | +servo_arc = { path = "../stylo/servo_arc" } |
| 83 | +stylo_atoms = { path = "../stylo/stylo_atoms" } |
| 84 | +stylo = { path = "../stylo/style" } |
| 85 | +stylo_config = { path = "../stylo/stylo_config" } |
| 86 | +stylo_dom = { path = "../stylo/stylo_dom" } |
| 87 | +stylo_malloc_size_of = { path = "../stylo/malloc_size_of" } |
| 88 | +stylo_traits = { path = "../stylo/style_traits" } |
85 | 89 | ``` |
| 90 | + |
| 91 | +## Releases |
| 92 | + |
| 93 | +Releases are made every time this repository rebases its changes on top of the latest version of upstream Stylo. There are a lot of crates here. In order to publish them, they must be done in order. One order that works is: |
| 94 | + |
| 95 | +- selectors |
| 96 | +- stylo_static_prefs |
| 97 | +- stylo_config |
| 98 | +- stylo_atoms |
| 99 | +- stylo_malloc_size_of |
| 100 | +- stylo_dom |
| 101 | +- stylo_derive |
| 102 | +- stylo_traits |
| 103 | +- stylo |
| 104 | + |
| 105 | +## License |
| 106 | + |
| 107 | +Stylo is licensed under MPL 2.0 |
0 commit comments