Skip to content

Commit a44b553

Browse files
rauhryanrauhryan
committed
docs: add maintainer build guide
1 parent 9470772 commit a44b553

2 files changed

Lines changed: 281 additions & 7 deletions

File tree

‎BUILD.md‎

Lines changed: 279 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,279 @@
1+
# Building clayterm from source
2+
3+
This guide is for maintainers and builders working on clayterm itself.
4+
5+
It covers:
6+
- cloning the repo correctly,
7+
- initializing the `clay` git submodule,
8+
- installing the toolchain needed to compile the C sources to WebAssembly,
9+
- building the local development artifacts, and
10+
- verifying that the repo is ready for development.
11+
12+
It does **not** cover npm/JSR packaging or publishing.
13+
14+
## What the local build produces
15+
16+
The local source build is driven by `make`.
17+
18+
It generates:
19+
- `clayterm.wasm` — the compiled WebAssembly module built from the C sources
20+
- `wasm.ts` — a generated TypeScript file derived from `clayterm.wasm`
21+
22+
`wasm.ts` is generated output, not hand-maintained source.
23+
24+
## Clone the repo with submodules
25+
26+
The build depends on the `clay` git submodule.
27+
28+
Preferred fresh clone:
29+
30+
```sh
31+
git clone --recurse-submodules https://github.com/thefrontside/clayterm.git
32+
cd clayterm
33+
```
34+
35+
If you already cloned without submodules:
36+
37+
```sh
38+
git submodule update --init --recursive
39+
```
40+
41+
Quick check:
42+
43+
```sh
44+
git submodule status --recursive
45+
```
46+
47+
You should also see a populated `clay/` directory. If `clay/` is missing or empty, fix the submodule state before building.
48+
49+
## Required tools
50+
51+
You need:
52+
- `git`
53+
- `make`
54+
- `clang` with wasm32-capable support
55+
- `deno`
56+
57+
Equivalent packages are fine if your package manager uses different names.
58+
59+
## Install the toolchain
60+
61+
### macOS
62+
63+
Install Apple's command line tools first. They provide the base developer tools, including `git` and `make`.
64+
65+
```sh
66+
xcode-select --install
67+
```
68+
69+
Then install LLVM and Deno with Homebrew:
70+
71+
```sh
72+
brew install llvm deno
73+
```
74+
75+
Use Homebrew LLVM before Apple's system `clang` when building clayterm:
76+
77+
```sh
78+
echo 'export PATH="$(brew --prefix llvm)/bin:$PATH"' >> ~/.zshrc
79+
source ~/.zshrc
80+
```
81+
82+
If you do not already have `git` available after installing the command line tools, install it with Homebrew:
83+
84+
```sh
85+
brew install git
86+
```
87+
88+
### Debian / Ubuntu
89+
90+
Install the build toolchain and Git:
91+
92+
```sh
93+
sudo apt-get update
94+
sudo apt-get install -y build-essential clang lld git curl
95+
```
96+
97+
Install Deno with the official installer:
98+
99+
```sh
100+
curl -fsSL https://deno.land/install.sh | sh
101+
```
102+
103+
Add Deno to your shell path:
104+
105+
```sh
106+
echo 'export PATH="$HOME/.deno/bin:$PATH"' >> ~/.bashrc
107+
source ~/.bashrc
108+
```
109+
110+
### Fedora / RHEL
111+
112+
Install the build toolchain and Git:
113+
114+
```sh
115+
sudo dnf install -y clang lld make git curl
116+
```
117+
118+
Install Deno with the official installer:
119+
120+
```sh
121+
curl -fsSL https://deno.land/install.sh | sh
122+
```
123+
124+
Add Deno to your shell path:
125+
126+
```sh
127+
echo 'export PATH="$HOME/.deno/bin:$PATH"' >> ~/.bashrc
128+
source ~/.bashrc
129+
```
130+
131+
### Windows
132+
133+
The recommended Windows build-host path is **WSL2 with Ubuntu**.
134+
135+
From an elevated PowerShell prompt:
136+
137+
```powershell
138+
wsl --install -d Ubuntu
139+
```
140+
141+
Then open the Ubuntu environment and follow the **Debian / Ubuntu** instructions above.
142+
143+
The build host runs inside WSL2, but the resulting WebAssembly artifacts are intended to run on **native Windows** at runtime.
144+
145+
## Verify the toolchain
146+
147+
Before building, confirm the required tools are available:
148+
149+
```sh
150+
git --version
151+
make --version
152+
clang --version
153+
deno --version
154+
```
155+
156+
For a quick wasm-target smoke test, make sure `clang` can compile for `wasm32`:
157+
158+
```sh
159+
clang --target=wasm32 -c -x c /dev/null -o /tmp/clayterm-wasm-test.o
160+
rm -f /tmp/clayterm-wasm-test.o
161+
```
162+
163+
On macOS, if `which clang` still points to `/usr/bin/clang` and the wasm test fails, make sure the Homebrew LLVM `bin/` directory is at the front of your `PATH`.
164+
165+
## Build from source
166+
167+
Run the local source build from the repository root:
168+
169+
```sh
170+
make
171+
```
172+
173+
This should produce:
174+
- `clayterm.wasm`
175+
- `wasm.ts`
176+
177+
For a clean rebuild:
178+
179+
```sh
180+
make clean && make
181+
```
182+
183+
## When to rebuild
184+
185+
Re-run `make` when:
186+
- you change files under `src/`
187+
- you update the `clay` submodule
188+
- `clayterm.wasm` or `wasm.ts` is missing
189+
- generated outputs look stale after switching branches or pulling changes
190+
191+
When in doubt, use a clean rebuild:
192+
193+
```sh
194+
make clean && make
195+
```
196+
197+
## Verify the build
198+
199+
After `make` succeeds, run the test suite:
200+
201+
```sh
202+
deno task test
203+
```
204+
205+
Before opening a PR, it is also a good idea to run the same checks CI runs:
206+
207+
```sh
208+
deno task fmt:check
209+
deno lint
210+
```
211+
212+
## Troubleshooting
213+
214+
### `clay/` is missing or empty
215+
216+
Symptoms may include build failures such as:
217+
- `fatal error: '../clay/clay.h' file not found`
218+
219+
Recovery:
220+
221+
```sh
222+
git submodule update --init --recursive
223+
```
224+
225+
Then verify the submodule state and rebuild:
226+
227+
```sh
228+
git submodule status --recursive
229+
make clean && make
230+
```
231+
232+
### `clang` cannot target `wasm32`
233+
234+
Symptoms may include:
235+
- target-related `clang` errors mentioning `wasm32`
236+
- linker failures while producing `clayterm.wasm`
237+
238+
Recovery:
239+
- make sure you are using an LLVM/Clang build with wasm support
240+
- on macOS, prefer the Homebrew `llvm` toolchain over `/usr/bin/clang`
241+
- on Linux/WSL2, make sure both `clang` and `lld` are installed
242+
- rerun the wasm smoke test:
243+
244+
```sh
245+
clang --target=wasm32 -c -x c /dev/null -o /tmp/clayterm-wasm-test.o
246+
rm -f /tmp/clayterm-wasm-test.o
247+
```
248+
249+
If the smoke test fails, fix the toolchain first and only then rerun `make`.
250+
251+
### Generated artifacts are missing or stale
252+
253+
Symptoms may include:
254+
- `clayterm.wasm` is missing
255+
- `wasm.ts` is missing
256+
- you changed `src/` or updated `clay/`, but the generated outputs do not match
257+
258+
Recovery:
259+
260+
```sh
261+
make clean && make
262+
```
263+
264+
Then verify the repo is in a good state:
265+
266+
```sh
267+
deno task test
268+
```
269+
270+
## Scope note
271+
272+
This document is intentionally limited to local source builds for development.
273+
274+
Out of scope:
275+
- `deno task build:npm`
276+
- `deno task build:jsr`
277+
- `npm publish`
278+
- `deno publish`
279+
- release tagging and package publishing workflows

‎README.md‎

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -212,16 +212,11 @@ process.stdin.on("data", (buf) => {
212212

213213
## Development
214214

215-
Requires `clang` with wasm32 target support.
215+
For local source builds, toolchain setup, and `clay` submodule instructions, see [BUILD.md](BUILD.md).
216216

217-
First build the `.wasm`
217+
Quick local validation:
218218

219219
```sh
220220
make
221-
```
222-
223-
run tests
224-
225-
```sh
226221
deno task test
227222
```

0 commit comments

Comments
 (0)