surma
93f092e02b
- The cargo target folder is <cache>/cargo-target, next to Wasmtime's cache, which moves to <cache>/wasmtime: Wasmtime's cleanup worker deletes unknown entries in its folder, also Cargo's artifacts. - Builds use the SDK at <cache>/sdk/<content hash>/, so cargo reuses the compiled SDK in every world. /plugins/cargo/sdk/ stays for agents. - Tests run in the release profile and share compiled crates with the release build. - The cargo and cli tests use a persistent cache in CARGO_TARGET_TMPDIR: warm, the cargo suite takes 11 s (was 235 s) and the cli suite 6 s (was 149 s). - nix flake check runs ignored stress tests. AGENTS.md: rules for fast tests.
52 lines
2.2 KiB
Markdown
52 lines
2.2 KiB
Markdown
# Working on Sausage
|
|
|
|
Sausage is meant to be read and changed by agents, including its own agent.
|
|
Keep it that way.
|
|
|
|
## Priorities
|
|
|
|
1. **Correct.** Every behavior in `PROTOCOL.md` has a test in `cli/tests/`.
|
|
2. **Simple and short.** Prefer the obvious code. No abstraction for one
|
|
caller. No configuration that nobody asked for.
|
|
3. **Readable.** A new reader must understand a file without the others.
|
|
Each module starts with a doc comment that says what it owns.
|
|
4. **Efficient** on the paths that run per call.
|
|
5. **Raw and minimal.** Sausage has no permissions, sandboxing beyond WASI,
|
|
limits, or authentication. Do not add them to the core. Add nothing to
|
|
the host that a plugin (or the agent, by changing itself) could do.
|
|
|
|
## Layout
|
|
|
|
- `cli/`: the host (`sausage` binary and library): the core, the native
|
|
`cargo` plugin, the WASI test runner, and the console.
|
|
- `vfs/`: `sausage-vfs`, the virtual filesystem for WASI guests. It knows
|
|
nothing about Sausage.
|
|
- `interface/`: `sausage-interface`: OpenRPC documents, the compatibility
|
|
check, and the generator of client code.
|
|
- `sdk/`: `sausage-plugin`, the SDK for Rust plugins, and `sdk/macros/`, its
|
|
macros. Never published: `cargo` points `sausage-plugin = "0.1"` at its
|
|
local copy.
|
|
- `agent/`: the agent plugin. `sausage init` embeds and builds it.
|
|
- `examples/`: small plugins. They are not workspace members.
|
|
- `PROTOCOL.md`: the contract between the core and the plugins. Change it in
|
|
the same commit as the behavior. `DECISIONS.md` says why; when the two
|
|
disagree, `PROTOCOL.md` and the code win.
|
|
|
|
## Checks
|
|
|
|
```sh
|
|
nix flake check -L # everything below, plus the stress tests; CI runs this on every push
|
|
nix develop -c cargo test --workspace # fast with a warm cache: run it during development
|
|
nix develop -c cargo build --release -p agent --target wasm32-wasip2
|
|
nix develop -c cargo clippy --workspace
|
|
```
|
|
|
|
`nix run -- init` and `nix run -- run` must keep working without other
|
|
setup.
|
|
|
|
Tests must stay fast. Only a few tests may wait for a timing (grace periods,
|
|
deadlines). Poll for a condition with a deadline, do not sleep. `#[ignore]` is
|
|
only for stress tests: `nix flake check` runs them with `--include-ignored`.
|
|
Tests that build plugins use the persistent cache in
|
|
`env!("CARGO_TARGET_TMPDIR")`.
|