WEFT_OS/docs/building.md
Marco Allegretti dcc09f319d
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-09 08:34:48 +00:00

2.9 KiB
Raw Blame History

Building WEFT OS

Prerequisites

Linux (x86_64 or aarch64). Building on Windows is supported for workspace validation only; runtime components require Linux kernel interfaces.

System packages (openSUSE):

sudo zypper install -y \
  libwayland-devel libxkbcommon-devel \
  libglvnd-devel libgbm-devel libdrm-devel \
  libinput-devel seatd-devel libudev-devel systemd-devel \
  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)

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)

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)

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:

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

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

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:

bash infra/vm/build.sh

Run with QEMU:

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

Four jobs run on every push to main and on pull requests:

  • 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
  • contributor-toolkit — python .agents/scripts/verify.py toolkit