[READ-ONLY] Mirror of https://github.com/bombshell-dev/tty. Platform independent 2D layout engine for terminal applications based on Clay
Merge PR #28 build docs
+299
-7
+296
BUILD.md
+296
BUILD.md
···
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
+3
-7
README.md
+3
-7
README.md
···
212
212
213
213
## Development
214
214
215
-
Requires `clang` with wasm32 target support.
215
+
For local source builds, toolchain setup, and `clay` submodule instructions, see
216
+
[BUILD.md](BUILD.md).
216
217
217
-
First build the `.wasm`
218
+
Quick local validation:
218
219
219
220
```sh
220
221
make
221
-
```
222
-
223
-
run tests
224
-
225
-
```sh
226
222
deno task test
227
223
```