Repository navigation
Running Sashfold
sashfold # the browser window, on about:sashfold
sashfold https://example.org/ # opened on a page
The window is written for Windows (Win32) and Linux (a Wayland client of its own; the section below). Every color, size and timing of its chrome comes from themes/default.json (see Themes); the file is looked for beside the executable, then in its parent directory, and it reloads while the window is open.
| Option | Meaning |
|---|---|
--theme <file.json> |
Use another theme file |
--blocklists <dir> |
The folder of content-blocking lists (filters/*.txt in Adblock syntax, nefarious/*.txt sites to keep off), read at start; blocklists/ beside the executable or its parent by default. See Security defaults
|
--downloads <dir> |
Where downloads are saved (the window defaults to your Downloads folder) |
--fonts system|builtin |
Use the machine's fonts, or the built-in face alone (system is the default everywhere except --script) |
--add-font <file.ttf> |
Install a font file for the page as if the machine had it. Repeatable, and applied after --fonts, so --fonts builtin --add-font X.ttf gives the page exactly that face and the built-in one. A file with no outlined face stops the run rather than laying the page out in some other font quietly. This is how a render is taken in the same font a test is scored in |
On Linux the window is a Wayland client spoken directly over the compositor's socket: no toolkit, no libwayland (see The Pledge). It asks the compositor for its own title bar through xdg-decoration (KDE Plasma, sway and the wlroots compositors provide one; GNOME does not, so there the window has no title bar yet), names its cursors through cursor-shape-v1, hands the compositor its icon through xdg-toplevel-icon-v1, reads the keyboard through the xkb keymap the compositor sends (parsed here, virtual modifiers resolved the way libxkbcommon resolves them), and speaks the clipboard through the data device. HiDPI scaling, touch and input methods are not written yet.
bash tools/install-desktop-linux.sh --desktop installs the launcher, the icon at every size the icon theme names, and a Desktop shortcut for the current user; the window's app id is sashfold, which is how the desktop matches it to the launcher's name and icon.
SASHFOLD_WAYLAND_DEBUG=1 prints what the compositor offered and what was bound, every configure, the keymap's parse and each key and present, and writes the keymap it received to $XDG_RUNTIME_DIR/sashfold-keymap.xkb for a keymap the parser refuses.
Every mode below runs without a window, on every OS the engine builds on.
sashfold --render page.html -o out.png [--width N] [--height N]
Lays the page out (a local file or a live URL, through the same session logic as the window — stylesheets, images and fonts included) and writes the picture. A load that fails renders the page the window would show: the error page, or the certificate page.
| Flag | Meaning |
|---|---|
--width N, --height N
|
The viewport (800×720 by default) |
--max-height N |
Cap the picture's height |
--thumbnail small.png [--thumbnail-width N] |
Also write the viewport's top, scaled down |
--report out.json |
Write a JSON account of the load: status, final URL, title, timings per stage, page height, text runs, stylesheets, pictures and fonts with their failures, connections, and what the page's stylesheets ask for that the engine does not do |
--dump-layout |
Print every laid-out box and text run with its position, size and baseline — the instrument for a layout question |
sashfold --bench page.html [--runs N] [--width N]
Times parse, stylesheets, style, layout and paint over several runs, prints rule and image counts, and a network line (page, sheets and images on the first run; connections opened, reused and retried).
sashfold --script tests/shell/live.script [--update-goldens] [--width N] [--height N]
Replays commands against the shell and checks its assertions; this is how the shell is tested in CI. The command reference is on Scripting the shell.
| Mode | Does |
|---|---|
--fetch <url> |
Print the response head, through the same fetch choke point the browser uses |
--dump-dom <file.html> |
Parse the file and print the document tree |
--font-info <file.ttf|file.ttc> |
Describe a font file as the TrueType reader sees it |
--font-list |
List the fonts the font manager catalogued, and how long the scan took |
--font-sampler <out.png> [--font <file.ttf>] |
Draw a QA sheet of a face (Sashfold Mono by default) |
--smoke [-o out.png] |
Render the painter's smoke scene |
bash tools/sashfold100.sh build/sashfold out/ # render the hundred and write the dashboard into out/
bash tools/wpt-fetch.sh # fetch the Web Platform Tests checkout, then:
build/tests/wpt_reftest wpt tests/wpt/directories.txt tests/wpt/passing.txt
See The Sashfold 100 and Testing for what each does and their flags.
Getting started
What works today
Measured
Design decisions
Testing and tools