2026-03-12 14:41:33 +00:00
# Building WEFT OS
## Prerequisites
Linux (x86_64 or aarch64). Building on Windows is supported for workspace validation only; runtime components require Linux kernel interfaces.
2026-03-12 19:48:17 +00:00
System packages (openSUSE):
2026-03-12 14:41:33 +00:00
```sh
2026-03-12 19:48:17 +00:00
sudo zypper install -y \
libwayland-devel libxkbcommon-devel \
2026-03-12 19:52:34 +00:00
libglvnd-devel libgbm-devel libdrm-devel \
libinput-devel seatd-devel libudev-devel systemd-devel \
2026-03-12 14:41:33 +00:00
pkg-config clang cmake python3
```
Rust toolchain: pinned in `rust-toolchain.toml` . Run `rustup show` to confirm the active toolchain matches.
## Workspace crates (non-Servo)
```sh
cargo build --workspace \
--exclude weft-servo-shell \
--exclude weft-app-shell
```
These crates do not require Servo and build in under two minutes.
## weft-compositor, weft-servo-shell, weft-app-shell (Linux)
```sh
cargo build -p weft-compositor
cargo build -p weft-servo-shell
cargo build -p weft-app-shell
```
Without `--features servo-embed` , the servo-shell and app-shell stubs compile and print READY without running an actual WebView. This is the default and the CI baseline.
## Servo embedding (optional, slow)
```sh
cargo build -p weft-servo-shell --features servo-embed
cargo build -p weft-app-shell --features servo-embed
```
This fetches and compiles the Servo fork (`github.com/marcoallegretti/servo`, branch `servo-weft` ). Expect 30– 60 minutes on a clean build. Servo's dependencies include SpiderMonkey (C++), which requires `clang` and `python3` .
## Demo apps (wasm32-wasip2)
Each demo is a standalone crate in `examples/` . Pre-built `app.wasm` binaries are committed. To rebuild:
```sh
rustup target add wasm32-wasip2
cd examples/org.weft.demo.counter
cargo build --release
# output: target/wasm32-wasip2/release/app.wasm
```
## weft-runtime with Wasmtime
```sh
cargo build -p weft-runtime --features wasmtime-runtime,net-fetch
```
Without `--features wasmtime-runtime` , the runtime prints READY and exits (stub mode, used in CI on platforms without Linux system dependencies).
## Signing packages
```sh
weft-pack generate-key ./keys
weft-pack sign ./examples/org.weft.demo.counter --key ./keys/weft-sign.key
weft-pack verify ./examples/org.weft.demo.counter --key ./keys/weft-sign.pub
```
## NixOS VM (requires Nix with flakes)
Build the VM image:
```sh
bash infra/vm/build.sh
```
Run with QEMU:
```sh
bash infra/vm/run.sh
```
See `infra/nixos/weft-packages.nix` for the package derivations. The `outputHashes` entry for the Servo git dependency must be filled in before the `servo-embed` packages will build under Nix.
## CI
docs: add engineering contract, contributor toolkit and templates
Add AGENTS.md as the single engineering contract: sources of truth,
evidence and proof requirements, ownership, working modes, the reviewed
change loop, maintenance isolation, decision authority, dependency and
fork rules, the 0.0.x to 0.1.0 release progression, and branch and
publication rules.
Add .agents/ with scope, implement, verify, maintenance and release
procedures; reviewer, architecture debt scout, simplicity and refactoring
roles; skills for the compositor, Servo rendering, runtime capabilities,
appd sessions, packages and data, Linux deployment, integration
verification and documentation; and verify.py, which runs the existing
check profiles with --locked from any directory, stops on the first
failure and supports --dry-run.
check_toolkit.py validates local links and heading anchors, metadata,
catalog coverage and issue forms. A new contributor-toolkit CI job runs
both. The structure follows the Resina Design System toolkit at
1e768064f57a1e403ab271822383e732795905a6, adapted to WEFT.
Validation, against the committed lockfiles:
- verify.py toolkit: checker passes, 28 runner/checker tests pass
- verify.py portable, demos, packages: pass
- verify.py linux, runtime, servo-embed: fail on existing defects
(clippy collapsible_if in the winit backend, three clippy lints in
weft-runtime with wasmtime-runtime, and an E0308 in the selected Servo
revision's servo-layout); the runner reports the failing status
Add CONTRIBUTING.md, issue forms for defects and changes, maintenance
problems and decisions of direction, and a pull request template asking
for ownership, proof and the validation actually performed. README.md
links the contribution guide.
2026-10-08 23:40:08 +00:00
Four jobs run on every push to `main` and on pull requests:
2026-03-12 14:41:33 +00:00
- `cross-platform` — fmt, clippy, tests on Ubuntu and Windows (excludes Wayland crates)
- `linux-only` — clippy and tests for `weft-compositor` , `weft-servo-shell` , `weft-app-shell`
- `servo-embed-linux` — `cargo check --features servo-embed` for servo-shell and app-shell
docs: add engineering contract, contributor toolkit and templates
Add AGENTS.md as the single engineering contract: sources of truth,
evidence and proof requirements, ownership, working modes, the reviewed
change loop, maintenance isolation, decision authority, dependency and
fork rules, the 0.0.x to 0.1.0 release progression, and branch and
publication rules.
Add .agents/ with scope, implement, verify, maintenance and release
procedures; reviewer, architecture debt scout, simplicity and refactoring
roles; skills for the compositor, Servo rendering, runtime capabilities,
appd sessions, packages and data, Linux deployment, integration
verification and documentation; and verify.py, which runs the existing
check profiles with --locked from any directory, stops on the first
failure and supports --dry-run.
check_toolkit.py validates local links and heading anchors, metadata,
catalog coverage and issue forms. A new contributor-toolkit CI job runs
both. The structure follows the Resina Design System toolkit at
1e768064f57a1e403ab271822383e732795905a6, adapted to WEFT.
Validation, against the committed lockfiles:
- verify.py toolkit: checker passes, 28 runner/checker tests pass
- verify.py portable, demos, packages: pass
- verify.py linux, runtime, servo-embed: fail on existing defects
(clippy collapsible_if in the winit backend, three clippy lints in
weft-runtime with wasmtime-runtime, and an E0308 in the selected Servo
revision's servo-layout); the runner reports the failing status
Add CONTRIBUTING.md, issue forms for defects and changes, maintenance
problems and decisions of direction, and a pull request template asking
for ownership, proof and the validation actually performed. README.md
links the contribution guide.
2026-10-08 23:40:08 +00:00
- `contributor-toolkit` — `python .agents/scripts/verify.py toolkit`