Skip to content

Commit fe6026b

Browse files
rauhryanrauhryan
committed
Merge PR #28 build docs
2 parents da915f5 + 264616b commit fe6026b

2 files changed

Lines changed: 299 additions & 7 deletions

File tree

‎BUILD.md‎

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

‎README.md‎

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -212,16 +212,12 @@ 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
216+
[BUILD.md](BUILD.md).
216217

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

219220
```sh
220221
make
221-
```
222-
223-
run tests
224-
225-
```sh
226222
deno task test
227223
```

0 commit comments

Comments
 (0)