glassjar 0.1.0 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +83 -0
- package/assets/cpp-exceptions/runtime.tar.gz +0 -0
- package/dist/assets/worker-BPJOu1S6.js +1112 -0
- package/dist/compiler-module-cache.d.ts +54 -0
- package/dist/compiler-module-cache.d.ts.map +1 -0
- package/dist/cpp-object-cache.d.ts +55 -0
- package/dist/cpp-object-cache.d.ts.map +1 -0
- package/dist/debugger.d.ts +6 -1
- package/dist/debugger.d.ts.map +1 -1
- package/dist/engine-worker.d.ts +3 -0
- package/dist/engine-worker.d.ts.map +1 -0
- package/dist/engine_bg.wasm +0 -0
- package/dist/glassjar.js +1268 -1375
- package/dist/glassjar.umd.cjs +2 -912
- package/dist/host-device.d.ts +35 -0
- package/dist/host-device.d.ts.map +1 -0
- package/dist/index.d.ts +177 -40
- package/dist/index.d.ts.map +1 -1
- package/dist/stock-cache-certificates.json.d.ts +4 -0
- package/dist/toolchain-manifest.d.ts +13 -0
- package/dist/toolchain-manifest.d.ts.map +1 -0
- package/dist/util.d.ts +1 -1
- package/dist/util.d.ts.map +1 -1
- package/dist/verified-toolchain.d.ts +31 -0
- package/dist/verified-toolchain.d.ts.map +1 -0
- package/dist/wasm-source.d.ts +11 -0
- package/dist/wasm-source.d.ts.map +1 -0
- package/package.json +6 -3
package/README.md
CHANGED
|
@@ -15,6 +15,22 @@ npm install glassjar
|
|
|
15
15
|
> Cross-Origin-Opener-Policy: same-origin
|
|
16
16
|
> ```
|
|
17
17
|
|
|
18
|
+
### Hosting the engine Wasm
|
|
19
|
+
|
|
20
|
+
By default the engine loads its own `engine_bg.wasm` (about 9 MB) from jsDelivr, at
|
|
21
|
+
the exact version you installed, and its worker script from `dist/assets/` next to the
|
|
22
|
+
package, which bundlers pick up automatically. To serve the Wasm from your own site
|
|
23
|
+
instead, copy `node_modules/glassjar/dist/engine_bg.wasm` into your static files and
|
|
24
|
+
pass its URL:
|
|
25
|
+
|
|
26
|
+
```ts
|
|
27
|
+
const engine = await Engine.create('c', { wasmUrl: '/engine_bg.wasm' });
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Relative URLs resolve against the page, and only `http:`/`https:` are accepted. The
|
|
31
|
+
file must come from the same package version. A page loads the engine Wasm once, so
|
|
32
|
+
every `Engine.create` on a page must pass the same `wasmUrl`.
|
|
33
|
+
|
|
18
34
|
---
|
|
19
35
|
|
|
20
36
|
## Quick start
|
|
@@ -46,6 +62,12 @@ await engine.run();
|
|
|
46
62
|
|
|
47
63
|
> Programs compile in **debug mode** by default, so a [DAP](https://microsoft.github.io/debug-adapter-protocol/) handshake is required before `run()` will proceed — see the [integration guide](./docs/integration.md#debugger-dap). To skip it, set `engine.debugger.enabled = false`.
|
|
48
64
|
|
|
65
|
+
C++ source `throw`/`catch` and RAII work in Run and Debug. Prebuilt libc++ error
|
|
66
|
+
helpers can still abort instead of throwing. The worker embeds a small LLVM
|
|
67
|
+
exception supplement; compiler/sysroot URLs stay unchanged. Exact upstream
|
|
68
|
+
notices and payload provenance are in `share/licenses/cpp-exceptions/` inside
|
|
69
|
+
[runtime.tar.gz](./assets/cpp-exceptions/runtime.tar.gz).
|
|
70
|
+
|
|
49
71
|
---
|
|
50
72
|
|
|
51
73
|
## Full API
|
|
@@ -54,9 +76,12 @@ await engine.run();
|
|
|
54
76
|
const engine = await Engine.create('c'); // 'c' | 'python'
|
|
55
77
|
|
|
56
78
|
engine.fs; // DirNode — virtual filesystem, set before run()
|
|
79
|
+
engine.binaryFiles; // Record<string, Uint8Array> — optional C/C++ binary files
|
|
80
|
+
engine.cppArtifacts; // Optional selected sources, archives, and precompiled header
|
|
57
81
|
engine.stdout; // Stdout — .on('data', (chunk: Uint8Array) => …) / .off(...)
|
|
58
82
|
engine.stderr; // Stdout
|
|
59
83
|
engine.stdin; // Stdin — .write(string | Uint8Array): Promise<void>
|
|
84
|
+
engine.hostDevice; // Optional C/C++ and Python duplex byte device — see below
|
|
60
85
|
engine.debugger; // Debugger — DAP interface; set .enabled = false to skip the handshake
|
|
61
86
|
engine.lang; // Lang
|
|
62
87
|
|
|
@@ -75,6 +100,39 @@ See [Presentation filtering (Python)](./docs/integration.md#presentation-filteri
|
|
|
75
100
|
|
|
76
101
|
---
|
|
77
102
|
|
|
103
|
+
## Precompiled C++ inputs
|
|
104
|
+
|
|
105
|
+
Set `binaryFiles` to bytes keyed by absolute virtual paths. Set `cppArtifacts`
|
|
106
|
+
to select source files, link archives, or use a precompiled header:
|
|
107
|
+
|
|
108
|
+
```ts
|
|
109
|
+
engine.binaryFiles = { '/support.a': archiveBytes, '/headers.pch': headerBytes };
|
|
110
|
+
engine.cppArtifacts = {
|
|
111
|
+
sources: ['/main.cpp'],
|
|
112
|
+
archives: ['/support.a'],
|
|
113
|
+
precompiledHeader: '/headers.pch'
|
|
114
|
+
};
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
All fields are optional. Without `sources`, the engine compiles every source in
|
|
118
|
+
`engine.fs`. Selected sources must exist and cannot be empty; archive and PCH
|
|
119
|
+
paths must have matching bytes in `binaryFiles`. Binary paths must be absolute,
|
|
120
|
+
cannot contain empty, `.` or `..` components, and cannot replace existing files.
|
|
121
|
+
The engine snapshots the binary bytes and artifact options when a run starts.
|
|
122
|
+
Clear them before reusing an engine for an ordinary source-only run.
|
|
123
|
+
|
|
124
|
+
Build artifacts with the same compiler, sysroot, and flags as the engine. A PCH
|
|
125
|
+
also needs its original header files at their original virtual paths. These
|
|
126
|
+
inputs work in Run and Debug for C/C++ only; Python and Rust reject them.
|
|
127
|
+
|
|
128
|
+
After building, run the browser regression with an existing Playwright installation:
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
PLAYWRIGHT_MODULE=/absolute/path/to/playwright/index.mjs node tools/cpp-artifacts/run.mjs --exceptions
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
---
|
|
135
|
+
|
|
78
136
|
## Wiring stdin
|
|
79
137
|
|
|
80
138
|
`engine.stdin.write()` accepts a UTF-8 string or `Uint8Array`. Programs read via `cin`, `scanf`, `read()`, etc.
|
|
@@ -86,6 +144,20 @@ await engine.stdin.write(new TextEncoder().encode('42\n'));
|
|
|
86
144
|
|
|
87
145
|
---
|
|
88
146
|
|
|
147
|
+
For C/C++ or Python host I/O, set `engine.hostDevice` to a synchronous opener receiving
|
|
148
|
+
`{ signal, onData, write }`; return an optional synchronous cleanup function. The guest opens
|
|
149
|
+
`HOST_DEVICE_PATH` with `O_RDWR` for blocking reads/writes; polling is unsupported.
|
|
150
|
+
`write` snapshots bytes; await each write. Stop/exit aborts the per-run signal,
|
|
151
|
+
rejects pending writes and calls cleanup once. Terminal I/O stays separate.
|
|
152
|
+
|
|
153
|
+
Python uses the same device through `os.open("/dev/debugger-sh-host", os.O_RDWR)`,
|
|
154
|
+
`os.read(fd, size)`, and `os.write(fd, data)`. Reads and writes may be partial;
|
|
155
|
+
loop until a complete application-defined message has transferred. The device
|
|
156
|
+
is a byte stream: framing, request/response matching, and graphics or AI behavior
|
|
157
|
+
belong to the application. It is absent when no opener is supplied.
|
|
158
|
+
|
|
159
|
+
Test after building: `npx -y bun tools/host-device/run.ts`.
|
|
160
|
+
|
|
89
161
|
## Example project
|
|
90
162
|
|
|
91
163
|
For a full reference integration, see the [debugger.sh IDE](https://github.com/debugger-sh/debugger.sh) — a Next.js + MUI app wiring up CodeMirror 6, xterm.js, and `debugger-sh` into a working in-browser IDE.
|
|
@@ -103,6 +175,17 @@ npm run build # wasm-pack build --target web && vite build
|
|
|
103
175
|
npm run dev # local development
|
|
104
176
|
```
|
|
105
177
|
|
|
178
|
+
After building, run the stdin browser regression checks with an installed Playwright
|
|
179
|
+
module and Chromium browser:
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
PLAYWRIGHT_MODULE=/absolute/path/to/playwright/index.mjs node tools/stdin/run.mjs
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
The checks cover an empty read without input, sequential Python input across reruns,
|
|
186
|
+
stopping blocked input, and C++ input. Pass a built or unpacked release's
|
|
187
|
+
`dist/glassjar.js` as the first argument to test that artifact.
|
|
188
|
+
|
|
106
189
|
To test against the reference IDE, clone [debugger-sh/debugger.sh](https://github.com/debugger-sh/debugger.sh) alongside this repo and link:
|
|
107
190
|
|
|
108
191
|
```bash
|
|
Binary file
|