Skip to content

Commit 8f5e4bd

Browse files
softmarshmallowsoftmarshmallow
committed
docs(contributing): give setup its own guide
AGENTS.md is the working map, not the place durable setup knowledge accumulates — and README already sent humans to an agent file for it. CodeRabbit flagged the same thing on #67 when the emsdk bump added a python floor to both AGENTS.md files. Moves the base prerequisites and the vanilla WASM build procedure into docs/contributing/setup.md, alongside the WPT guide that already lives there, and leaves a pointer at each site. README's setup link now points at the guide rather than at AGENTS.md#setup. Captured on the way: `just` had no install line anywhere the build steps could see it, and the vanilla path had no answer for the missing-`.wasm.a` prebuilt panic the justfile silently retries past.
1 parent 43a2507 commit 8f5e4bd

4 files changed

Lines changed: 135 additions & 64 deletions

File tree

‎AGENTS.md‎

Lines changed: 3 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -63,19 +63,9 @@ a comment.
6363

6464
## Setup
6565

66-
```sh
67-
# 1. emsdk submodule (needed for WASM builds only). `bin/activate-emsdk` pins
68-
# the SDK version and needs python >= 3.10 — macOS ships 3.9, so a WASM
69-
# build there wants `brew install python` first.
70-
git submodule update --init
71-
72-
# 2. Rust toolchain auto-pins via rust-toolchain.toml (rustfmt + clippy included)
73-
cargo --version
74-
75-
# 3. ninja is required for skia-bindings
76-
brew install ninja # macOS
77-
# sudo apt-get install -y ninja-build # Ubuntu/Debian
78-
```
66+
[`docs/contributing/setup.md`](./docs/contributing/setup.md) is the statement of
67+
record — Rust toolchain and `ninja` for the base, the pinned emsdk for a WASM
68+
build. Do not restate it here.
7969

8070
## Commands
8171

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,7 @@ yet: any layout engine, any editor host, any WebAssembly target.
109109

110110
**Nothing here is published.** There are no releases, and the only shipped
111111
artifact in the tree is the frozen v1 wasm package. Run it from a clone —
112-
[setup](./AGENTS.md#setup).
112+
[setup](./docs/contributing/setup.md).
113113

114114
## One pipeline
115115

‎crates/grida-canvas-wasm/AGENTS.md‎

Lines changed: 4 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -206,54 +206,8 @@ For production deployment:
206206
4. **Consistent Output**: Standardized success messages and error handling
207207
5. **Extensibility**: Easy to add new build configurations or commands
208208

209-
## Troubleshooting / Building WASM locally (vanilla way)
209+
## Building WASM locally (vanilla way)
210210

211-
> follow this if you can't use justfile or os-specific trouble shooting.
212-
213-
The WASM build targets `wasm32-unknown-emscripten` and requires the Emscripten SDK.
214-
The steps below were tested on a fresh Ubuntu container and produced
215-
`lib/bin/grida_canvas_wasm.wasm` and `lib/bin/grida-canvas-wasm.js`.
216-
217-
1. **Fetch submodules and install build tools**
218-
219-
```bash
220-
git submodule update --init --recursive
221-
rustup target add wasm32-unknown-emscripten
222-
pnpm install
223-
```
224-
225-
2. **Install and activate Emscripten**
226-
227-
Use the activator rather than `emsdk install latest` — it holds the pinned
228-
SDK version, and an unpinned `latest` drifts away from what CI builds. It
229-
needs python >= 3.10.
230-
231-
```bash
232-
python3 bin/activate-emsdk # from the repo root
233-
```
234-
235-
3. **(Ubuntu only) provide missing locale headers**
236-
Some Ubuntu images lack `xlocale.h` which breaks the Skia build. A simple symbolic link fixes it:
237-
238-
```bash
239-
sudo ln -s /usr/include/locale.h /usr/include/xlocale.h
240-
```
241-
242-
4. **Build the crate**
243-
244-
```bash
245-
cd crates/grida-canvas-wasm
246-
source ../../third_party/externals/emsdk/emsdk_env.sh
247-
export CC=emcc CXX=em++ AR=emar
248-
cargo build --release --target wasm32-unknown-emscripten
249-
```
250-
251-
5. **Copy artifacts and package**
252-
```bash
253-
mkdir -p lib/bin
254-
cp ../../target/wasm32-unknown-emscripten/release/*.js lib/bin/
255-
cp ../../target/wasm32-unknown-emscripten/release/*.wasm lib/bin/
256-
pnpm --filter @grida/canvas-wasm build
257-
```
258-
259-
After these steps the compiled module is ready in `lib/bin/` for consumption or publishing.
211+
Toolchain prerequisites and the step-by-step build without the justfile live in
212+
[`docs/contributing/setup.md`](../../docs/contributing/setup.md). Do not restate
213+
them here.

‎docs/contributing/setup.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Contributing to nothing | Setup
2+
3+
What a fresh clone needs before the workspace builds. Everything here is
4+
per-machine — none of it is checked in.
5+
6+
## Base
7+
8+
```sh
9+
# 1. Rust toolchain — auto-pins via rust-toolchain.toml (rustfmt + clippy included)
10+
cargo --version
11+
12+
# 2. ninja — required by skia-bindings
13+
brew install ninja # macOS
14+
# sudo apt-get install -y ninja-build # Ubuntu/Debian
15+
```
16+
17+
That covers `cargo test` and the `n0` binary. `skia-bindings` downloads a
18+
prebuilt Skia for target/feature combinations that rust-skia publishes and
19+
builds from source otherwise, which is what ninja is for — so the first
20+
build on a combination without a prebuilt is long, and later ones are not.
21+
22+
## WebAssembly
23+
24+
Only needed to build `@grida/canvas-wasm`. Nothing else in the workspace
25+
targets WASM — see the caveats in [AGENTS.md](../../AGENTS.md#current-state-and-caveats).
26+
27+
### Emscripten
28+
29+
The SDK is a submodule, installed at a pinned version by `bin/activate-emsdk`:
30+
31+
```sh
32+
git submodule update --init third_party/externals/emsdk
33+
python3 bin/activate-emsdk
34+
```
35+
36+
Two things to know:
37+
38+
- **`bin/activate-emsdk` is the source of truth for the SDK version.** Do not
39+
run `emsdk install latest` instead — an unpinned SDK drifts away from the one
40+
CI builds with, and Emscripten is not ABI-stable across major versions.
41+
- **The activator needs python >= 3.10**, an emsdk 6.0.4+ requirement. macOS
42+
ships 3.9, so `brew install python` first; Linux CI images are already past
43+
that floor.
44+
45+
### Build
46+
47+
The crate's [justfile](../../crates/grida-canvas-wasm/justfile) is the supported
48+
path — it activates emsdk, builds, copies the artifacts into `lib/bin/`, and
49+
packages:
50+
51+
```sh
52+
brew install just # or: cargo install just
53+
cd crates/grida-canvas-wasm && just build
54+
```
55+
56+
`just dev` is the same thing in debug mode (~100MB output rather than ~10MB).
57+
Publishing is separate — see
58+
[PUBLISHING.md](../../crates/grida-canvas-wasm/PUBLISHING.md).
59+
60+
### Building without the justfile
61+
62+
Follow this if `just` is unavailable, or when isolating an OS-specific failure.
63+
These steps were tested on a fresh Ubuntu container and produce the same
64+
`lib/bin/grida_canvas_wasm.wasm` and `lib/bin/grida-canvas-wasm.js`.
65+
66+
1. **Fetch submodules and install build tools**
67+
68+
```sh
69+
git submodule update --init --recursive
70+
rustup target add wasm32-unknown-emscripten
71+
pnpm install
72+
```
73+
74+
2. **Install and activate Emscripten** — as above, from the repo root:
75+
76+
```sh
77+
python3 bin/activate-emsdk
78+
```
79+
80+
3. **(Ubuntu only) provide missing locale headers.** Some Ubuntu images lack
81+
`xlocale.h`, which breaks the Skia build. A symlink fixes it:
82+
83+
```sh
84+
sudo ln -s /usr/include/locale.h /usr/include/xlocale.h
85+
```
86+
87+
4. **Build the crate**
88+
89+
```sh
90+
cd crates/grida-canvas-wasm
91+
source ../../third_party/externals/emsdk/emsdk_env.sh
92+
export CC=emcc CXX=em++ AR=emar
93+
cargo build --release --target wasm32-unknown-emscripten
94+
```
95+
96+
If this fails inside the `skia-bindings` build script with
97+
`failed to prepare emscripten archive for linking: … lib<x>.wasm.a … No such
98+
file or directory`, you have hit a known defect in the published prebuilts
99+
(<https://github.com/rust-skia/rust-skia/issues/1310>). Seed the expected
100+
names and re-run the build — this is what the justfile does automatically:
101+
102+
```sh
103+
for f in ../../target/wasm32-unknown-emscripten/*/build/skia-bindings-*/out/skia/lib*.a; do
104+
[ -e "${f%.a}.wasm.a" ] || cp "$f" "${f%.a}.wasm.a"
105+
done
106+
```
107+
108+
5. **Copy artifacts and package**
109+
110+
```sh
111+
mkdir -p lib/bin
112+
cp ../../target/wasm32-unknown-emscripten/release/*.js lib/bin/
113+
cp ../../target/wasm32-unknown-emscripten/release/*.wasm lib/bin/
114+
pnpm --filter @grida/canvas-wasm build
115+
```
116+
117+
After these steps the compiled module is in `lib/bin/`, ready for consumption
118+
or publishing.
119+
120+
## See also
121+
122+
- [`crates/grida-canvas-wasm/AGENTS.md`](../../crates/grida-canvas-wasm/AGENTS.md)
123+
— build system internals, bundler compatibility, output layout.
124+
- [`crates/grida-canvas-wasm/PUBLISHING.md`](../../crates/grida-canvas-wasm/PUBLISHING.md)
125+
— cutting an npm release.
126+
- [Web Platform Tests](./wpt.md) — the separate sibling-checkout setup that
127+
suite needs.

0 commit comments

Comments
 (0)