jebc-install 2.0.0 → 4.0.0

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.
Files changed (9) hide show
  1. package/LICENSE +33 -33
  2. package/README.md +7 -7
  3. package/docs/JEBC_Technical_Manual_EN.txt +302 -302
  4. package/docs/JEBC_Technical_Manual_JP.txt +298 -298
  5. package/examples/demo.jebc +22 -22
  6. package/jebc.exe +0 -0
  7. package/package.json +12 -12
  8. package/scripts/postinstall.js +80 -7
  9. package/setup.bat +12 -12
package/docs/JEBC_Technical_Manual_EN.txt CHANGED
@@ -1,302 +1,302 @@
1
- # JEBC V2 Technical Manual
2
-
3
- > JEBC — JavaScript/TypeScript + Emscripten Bundled Compiler
4
- > Version 2.0 | Platform: Windows
5
-
6
- ---
7
-
8
- ## Table of Contents
9
-
10
- 1. Overview
11
- 2. Requirements
12
- 3. Installation
13
- 4. Input File Format (.jebc)
14
- 5. Language Blocks
15
- 6. File Inclusion (call directive)
16
- 7. @jebc-sync (Struct Synchronization)
17
- 8. Build Pipeline
18
- 9. Output Structure
19
- 10. WASM Runtime API
20
- 11. Error Reference
21
- 12. Examples
22
-
23
- ---
24
-
25
- ## 1. Overview
26
-
27
- JEBC is a single-command build tool that compiles C/C++ and JS/TS/TSX from
28
- a unified `.jebc` source file into a deployable web application with WebAssembly.
29
-
30
- V2 adds: unified `.jebc` extension, mixed JS/TS/TSX blocks, `call` directive
31
- for file splitting, `lang.css`/`lang.html` blocks, and `@jebc-sync` for
32
- automatic C struct <-> TS class synchronization.
33
-
34
- ---
35
-
36
- ## 2. Requirements
37
-
38
- | Tool | Purpose | Install |
39
- |---------------------|---------------------------|----------------------------------|
40
- | Node.js + npm | Install JEBC & esbuild | https://nodejs.org/ |
41
- | Emscripten (emcc) | C/C++ -> WASM | https://emscripten.org/ |
42
- | esbuild | JS/TS bundling | Auto-installed via npm |
43
-
44
- ---
45
-
46
- ## 3. Installation
47
-
48
- ### Via npm (recommended)
49
-
50
- npm install -g jebc
51
-
52
- This installs `jebc` globally and auto-installs esbuild.
53
- For Emscripten, run `setup.bat` or install manually.
54
-
55
- ### Manual
56
-
57
- Download `jebc.exe` from GitHub and add to PATH.
58
-
59
- ---
60
-
61
- ## 4. Input File Format (.jebc)
62
-
63
- JEBC source files use `lang.X { ... }` blocks to embed multiple languages.
64
-
65
- Supported extensions: `.jebc` (V2, recommended), `.jsbc`, `.tsbc`, `.tsxbc` (legacy)
66
-
67
- ### Syntax
68
-
69
- lang.c {
70
- // C/C++ code -> compiled to WASM
71
- }
72
-
73
- lang.js {
74
- // JavaScript code
75
- }
76
-
77
- lang.ts {
78
- // TypeScript code
79
- }
80
-
81
- lang.tsx {
82
- // TSX code
83
- }
84
-
85
- lang.css {
86
- // CSS -> injected into <style> in index.html
87
- }
88
-
89
- lang.html {
90
- // HTML -> injected into <body> in index.html
91
- }
92
-
93
- ### Rules
94
-
95
- - Multiple blocks of the same type are concatenated in order
96
- - `.jebc` files allow JS/TS/TSX blocks to coexist (auto-detect mode)
97
- - Compile mode is determined by highest-priority block: TSX > TS > JS
98
- - Comments and strings inside code are correctly ignored by the parser
99
- - Every file must have at least one `lang.c` block and one script block
100
-
101
- ---
102
-
103
- ## 5. Language Blocks
104
-
105
- | Block | Language | Output |
106
- |------------|-------------|-------------------------------|
107
- | `lang.c` | C/C++ | dist/native.wasm (via emcc) |
108
- | `lang.js` | JavaScript | dist/bundle.js (via esbuild) |
109
- | `lang.ts` | TypeScript | dist/bundle.js (via esbuild) |
110
- | `lang.tsx` | TSX | dist/bundle.js (via esbuild) |
111
- | `lang.css` | CSS | dist/index.html <style> |
112
- | `lang.html`| HTML | dist/index.html <body> |
113
-
114
- ### Mixed Blocks (.jebc)
115
-
116
- In `.jebc` files, all script blocks (js/ts/tsx) are concatenated in source
117
- order and compiled together. This allows:
118
-
119
- lang.js {
120
- const data = [1, 2, 3];
121
- }
122
-
123
- lang.ts {
124
- // Can reference 'data' from the js block above
125
- console.log(data.length);
126
- }
127
-
128
- ---
129
-
130
- ## 6. File Inclusion (call directive)
131
-
132
- Split large projects into multiple files using `call`:
133
-
134
- // main.jebc
135
- call "components/math.jebc"
136
- call "components/ui.jebc"
137
-
138
- lang.c { ... }
139
- lang.ts { ... }
140
-
141
- ### Behavior
142
- - `call "path"` inlines the target file's contents before parsing
143
- - Paths are relative to the calling file's directory
144
- - Recursive: called files can also use `call`
145
- - Circular reference detection prevents infinite loops
146
-
147
- ---
148
-
149
- ## 7. @jebc-sync (Struct Synchronization)
150
-
151
- Annotate C structs with `// @jebc-sync` to auto-generate:
152
- - C accessor functions (getter/setter for each field)
153
- - TS wrapper class with properties mapped to C memory
154
-
155
- ### C Side
156
-
157
- // @jebc-sync
158
- struct Vector2 {
159
- float x;
160
- float y;
161
- };
162
-
163
- extern "C" {
164
- float Vector2_length(Vector2* self) {
165
- return sqrtf(self->x * self->x + self->y * self->y);
166
- }
167
- }
168
-
169
- ### Auto-generated TS (available in all script blocks)
170
-
171
- const v = new Vector2();
172
- v.x = 3.0;
173
- v.y = 4.0;
174
- console.log(v.length()); // Calls C function via WASM
175
-
176
- ### Method Convention
177
- - Define methods as: `ReturnType StructName_methodName(StructName* self, ...)`
178
- - JEBC auto-detects and wraps them in the TS class
179
-
180
- ---
181
-
182
- ## 8. Build Pipeline
183
-
184
- jebc app.jebc
185
-
186
- 1. **Preprocess** — Expand `call` directives (recursive file inclusion)
187
- 2. **Parse** — Extract all `lang.X { ... }` blocks
188
- 3. **Mode Detection** — Determine JS/TS/TSX from blocks present
189
- 4. **@jebc-sync** — Parse annotated structs, generate accessors + classes
190
- 5. **Write Intermediates** — `.bc_build/core.cpp` + `.bc_build/entry.X`
191
- 6. **WASM Compile** — `emcc core.cpp -O3 -s SIDE_MODULE=1 --no-entry`
192
- 7. **JS Bundle** — `esbuild entry.X --bundle --minify --format=esm`
193
- 8. **HTML Generate** — Create `index.html` with CSS/HTML injection
194
-
195
- ---
196
-
197
- ## 9. Output Structure
198
-
199
- project/
200
- ├── app.jebc # Source file
201
- ├── .bc_build/ # Intermediate build files
202
- │ ├── core.cpp # Extracted C code + sync accessors
203
- │ ├── entry.tsx # Glue code + sync classes + script blocks
204
- │ ├── emcc.stderr.log
205
- │ └── esbuild.stderr.log
206
- └── dist/ # Deploy this directory
207
- ├── native.wasm # C -> WASM
208
- ├── bundle.js # Bundled JS/TS (ESM)
209
- └── index.html # HTML with CSS + markup
210
-
211
- ---
212
-
213
- ## 10. WASM Runtime API
214
-
215
- | Global | Type | Description |
216
- |----------------|--------------------|------------------------------------|
217
- | `native` | Object | All extern "C" functions from WASM |
218
- | `sharedBuffer` | SharedArrayBuffer | 16 MB shared buffer for data |
219
- | `sharedMemory` | WebAssembly.Memory | Shared linear memory (256 pages) |
220
-
221
- const result = native.add(21, 21); // Call C function
222
- const view = new Uint8Array(sharedBuffer); // Direct memory access
223
-
224
- ---
225
-
226
- ## 11. Error Reference
227
-
228
- | Error | Solution |
229
- |---------------------------------|---------------------------------------|
230
- | Unsupported file extension | Use .jebc, .jsbc, .tsbc, or .tsxbc |
231
- | No lang.c section found | Add a lang.c { } block |
232
- | No script section found | Add lang.js/ts/tsx { } block |
233
- | emcc not found in PATH | Run setup.bat or install Emscripten |
234
- | esbuild not found in PATH | Run: npm i -g esbuild |
235
- | Circular call detected | Check call directives for loops |
236
- | Failed to read call target | Verify the file path in call "..." |
237
- | emcc build failed | Check C code; see .bc_build/*.log |
238
- | esbuild bundle failed | Check script code; see .bc_build/*.log|
239
-
240
- ---
241
-
242
- ## 12. Examples
243
-
244
- ### Minimal Example
245
-
246
- lang.c {
247
- extern "C" { int add(int a, int b) { return a + b; } }
248
- }
249
-
250
- lang.js {
251
- document.body.textContent = 'add(2,3) = ' + native.add(2, 3);
252
- }
253
-
254
- ### Full V2 Example (CSS + HTML + mixed scripts + call)
255
-
256
- call "math.jebc"
257
-
258
- lang.c {
259
- extern "C" { int square(int x) { return x * x; } }
260
- }
261
-
262
- lang.css {
263
- body { background: #0f0f23; color: #eee; font-family: monospace; }
264
- }
265
-
266
- lang.html {
267
- <div id="app"></div>
268
- }
269
-
270
- lang.js {
271
- const el = document.getElementById('app');
272
- el.textContent = 'square(7) = ' + native.square(7);
273
- }
274
-
275
- ### @jebc-sync Example
276
-
277
- lang.c {
278
- #include <math.h>
279
-
280
- // @jebc-sync
281
- struct Circle {
282
- float x;
283
- float y;
284
- float radius;
285
- };
286
-
287
- extern "C" {
288
- float Circle_area(Circle* self) {
289
- return 3.14159f * self->radius * self->radius;
290
- }
291
- }
292
- }
293
-
294
- lang.ts {
295
- const c = new Circle();
296
- c.x = 100; c.y = 200; c.radius = 50;
297
- console.log('Area:', c.area());
298
- }
299
-
300
- ---
301
-
302
- > JEBC V2 — C and JS in one file. Ship to the web.
1
+ # JEBC V2 Technical Manual
2
+
3
+ > JEBC — JavaScript/TypeScript + Emscripten Bundled Compiler
4
+ > Version 2.0 | Platform: Windows
5
+
6
+ ---
7
+
8
+ ## Table of Contents
9
+
10
+ 1. Overview
11
+ 2. Requirements
12
+ 3. Installation
13
+ 4. Input File Format (.jebc)
14
+ 5. Language Blocks
15
+ 6. File Inclusion (call directive)
16
+ 7. @jebc-sync (Struct Synchronization)
17
+ 8. Build Pipeline
18
+ 9. Output Structure
19
+ 10. WASM Runtime API
20
+ 11. Error Reference
21
+ 12. Examples
22
+
23
+ ---
24
+
25
+ ## 1. Overview
26
+
27
+ JEBC is a single-command build tool that compiles C/C++ and JS/TS/TSX from
28
+ a unified `.jebc` source file into a deployable web application with WebAssembly.
29
+
30
+ V2 adds: unified `.jebc` extension, mixed JS/TS/TSX blocks, `call` directive
31
+ for file splitting, `lang.css`/`lang.html` blocks, and `@jebc-sync` for
32
+ automatic C struct <-> TS class synchronization.
33
+
34
+ ---
35
+
36
+ ## 2. Requirements
37
+
38
+ | Tool | Purpose | Install |
39
+ |---------------------|---------------------------|----------------------------------|
40
+ | Node.js + npm | Install JEBC & esbuild | https://nodejs.org/ |
41
+ | Emscripten (emcc) | C/C++ -> WASM | https://emscripten.org/ |
42
+ | esbuild | JS/TS bundling | Auto-installed via npm |
43
+
44
+ ---
45
+
46
+ ## 3. Installation
47
+
48
+ ### Via npm (recommended)
49
+
50
+ npm install -g jebc
51
+
52
+ This installs `jebc` globally and auto-installs esbuild.
53
+ For Emscripten, run `setup.bat` or install manually.
54
+
55
+ ### Manual
56
+
57
+ Download `jebc.exe` from GitHub and add to PATH.
58
+
59
+ ---
60
+
61
+ ## 4. Input File Format (.jebc)
62
+
63
+ JEBC source files use `lang.X { ... }` blocks to embed multiple languages.
64
+
65
+ Supported extensions: `.jebc` (V2, recommended), `.jsbc`, `.tsbc`, `.tsxbc` (legacy)
66
+
67
+ ### Syntax
68
+
69
+ lang.c {
70
+ // C/C++ code -> compiled to WASM
71
+ }
72
+
73
+ lang.js {
74
+ // JavaScript code
75
+ }
76
+
77
+ lang.ts {
78
+ // TypeScript code
79
+ }
80
+
81
+ lang.tsx {
82
+ // TSX code
83
+ }
84
+
85
+ lang.css {
86
+ // CSS -> injected into <style> in index.html
87
+ }
88
+
89
+ lang.html {
90
+ // HTML -> injected into <body> in index.html
91
+ }
92
+
93
+ ### Rules
94
+
95
+ - Multiple blocks of the same type are concatenated in order
96
+ - `.jebc` files allow JS/TS/TSX blocks to coexist (auto-detect mode)
97
+ - Compile mode is determined by highest-priority block: TSX > TS > JS
98
+ - Comments and strings inside code are correctly ignored by the parser
99
+ - Every file must have at least one `lang.c` block and one script block
100
+
101
+ ---
102
+
103
+ ## 5. Language Blocks
104
+
105
+ | Block | Language | Output |
106
+ |------------|-------------|-------------------------------|
107
+ | `lang.c` | C/C++ | dist/native.wasm (via emcc) |
108
+ | `lang.js` | JavaScript | dist/bundle.js (via esbuild) |
109
+ | `lang.ts` | TypeScript | dist/bundle.js (via esbuild) |
110
+ | `lang.tsx` | TSX | dist/bundle.js (via esbuild) |
111
+ | `lang.css` | CSS | dist/index.html <style> |
112
+ | `lang.html`| HTML | dist/index.html <body> |
113
+
114
+ ### Mixed Blocks (.jebc)
115
+
116
+ In `.jebc` files, all script blocks (js/ts/tsx) are concatenated in source
117
+ order and compiled together. This allows:
118
+
119
+ lang.js {
120
+ const data = [1, 2, 3];
121
+ }
122
+
123
+ lang.ts {
124
+ // Can reference 'data' from the js block above
125
+ console.log(data.length);
126
+ }
127
+
128
+ ---
129
+
130
+ ## 6. File Inclusion (call directive)
131
+
132
+ Split large projects into multiple files using `call`:
133
+
134
+ // main.jebc
135
+ call "components/math.jebc"
136
+ call "components/ui.jebc"
137
+
138
+ lang.c { ... }
139
+ lang.ts { ... }
140
+
141
+ ### Behavior
142
+ - `call "path"` inlines the target file's contents before parsing
143
+ - Paths are relative to the calling file's directory
144
+ - Recursive: called files can also use `call`
145
+ - Circular reference detection prevents infinite loops
146
+
147
+ ---
148
+
149
+ ## 7. @jebc-sync (Struct Synchronization)
150
+
151
+ Annotate C structs with `// @jebc-sync` to auto-generate:
152
+ - C accessor functions (getter/setter for each field)
153
+ - TS wrapper class with properties mapped to C memory
154
+
155
+ ### C Side
156
+
157
+ // @jebc-sync
158
+ struct Vector2 {
159
+ float x;
160
+ float y;
161
+ };
162
+
163
+ extern "C" {
164
+ float Vector2_length(Vector2* self) {
165
+ return sqrtf(self->x * self->x + self->y * self->y);
166
+ }
167
+ }
168
+
169
+ ### Auto-generated TS (available in all script blocks)
170
+
171
+ const v = new Vector2();
172
+ v.x = 3.0;
173
+ v.y = 4.0;
174
+ console.log(v.length()); // Calls C function via WASM
175
+
176
+ ### Method Convention
177
+ - Define methods as: `ReturnType StructName_methodName(StructName* self, ...)`
178
+ - JEBC auto-detects and wraps them in the TS class
179
+
180
+ ---
181
+
182
+ ## 8. Build Pipeline
183
+
184
+ jebc app.jebc
185
+
186
+ 1. **Preprocess** — Expand `call` directives (recursive file inclusion)
187
+ 2. **Parse** — Extract all `lang.X { ... }` blocks
188
+ 3. **Mode Detection** — Determine JS/TS/TSX from blocks present
189
+ 4. **@jebc-sync** — Parse annotated structs, generate accessors + classes
190
+ 5. **Write Intermediates** — `.bc_build/core.cpp` + `.bc_build/entry.X`
191
+ 6. **WASM Compile** — `emcc core.cpp -O3 -s SIDE_MODULE=1 --no-entry`
192
+ 7. **JS Bundle** — `esbuild entry.X --bundle --minify --format=esm`
193
+ 8. **HTML Generate** — Create `index.html` with CSS/HTML injection
194
+
195
+ ---
196
+
197
+ ## 9. Output Structure
198
+
199
+ project/
200
+ ├── app.jebc # Source file
201
+ ├── .bc_build/ # Intermediate build files
202
+ │ ├── core.cpp # Extracted C code + sync accessors
203
+ │ ├── entry.tsx # Glue code + sync classes + script blocks
204
+ │ ├── emcc.stderr.log
205
+ │ └── esbuild.stderr.log
206
+ └── dist/ # Deploy this directory
207
+ ├── native.wasm # C -> WASM
208
+ ├── bundle.js # Bundled JS/TS (ESM)
209
+ └── index.html # HTML with CSS + markup
210
+
211
+ ---
212
+
213
+ ## 10. WASM Runtime API
214
+
215
+ | Global | Type | Description |
216
+ |----------------|--------------------|------------------------------------|
217
+ | `native` | Object | All extern "C" functions from WASM |
218
+ | `sharedBuffer` | SharedArrayBuffer | 16 MB shared buffer for data |
219
+ | `sharedMemory` | WebAssembly.Memory | Shared linear memory (256 pages) |
220
+
221
+ const result = native.add(21, 21); // Call C function
222
+ const view = new Uint8Array(sharedBuffer); // Direct memory access
223
+
224
+ ---
225
+
226
+ ## 11. Error Reference
227
+
228
+ | Error | Solution |
229
+ |---------------------------------|---------------------------------------|
230
+ | Unsupported file extension | Use .jebc, .jsbc, .tsbc, or .tsxbc |
231
+ | No lang.c section found | Add a lang.c { } block |
232
+ | No script section found | Add lang.js/ts/tsx { } block |
233
+ | emcc not found in PATH | Run setup.bat or install Emscripten |
234
+ | esbuild not found in PATH | Run: npm i -g esbuild |
235
+ | Circular call detected | Check call directives for loops |
236
+ | Failed to read call target | Verify the file path in call "..." |
237
+ | emcc build failed | Check C code; see .bc_build/*.log |
238
+ | esbuild bundle failed | Check script code; see .bc_build/*.log|
239
+
240
+ ---
241
+
242
+ ## 12. Examples
243
+
244
+ ### Minimal Example
245
+
246
+ lang.c {
247
+ extern "C" { int add(int a, int b) { return a + b; } }
248
+ }
249
+
250
+ lang.js {
251
+ document.body.textContent = 'add(2,3) = ' + native.add(2, 3);
252
+ }
253
+
254
+ ### Full V2 Example (CSS + HTML + mixed scripts + call)
255
+
256
+ call "math.jebc"
257
+
258
+ lang.c {
259
+ extern "C" { int square(int x) { return x * x; } }
260
+ }
261
+
262
+ lang.css {
263
+ body { background: #0f0f23; color: #eee; font-family: monospace; }
264
+ }
265
+
266
+ lang.html {
267
+ <div id="app"></div>
268
+ }
269
+
270
+ lang.js {
271
+ const el = document.getElementById('app');
272
+ el.textContent = 'square(7) = ' + native.square(7);
273
+ }
274
+
275
+ ### @jebc-sync Example
276
+
277
+ lang.c {
278
+ #include <math.h>
279
+
280
+ // @jebc-sync
281
+ struct Circle {
282
+ float x;
283
+ float y;
284
+ float radius;
285
+ };
286
+
287
+ extern "C" {
288
+ float Circle_area(Circle* self) {
289
+ return 3.14159f * self->radius * self->radius;
290
+ }
291
+ }
292
+ }
293
+
294
+ lang.ts {
295
+ const c = new Circle();
296
+ c.x = 100; c.y = 200; c.radius = 50;
297
+ console.log('Area:', c.area());
298
+ }
299
+
300
+ ---
301
+
302
+ > JEBC V2 — C and JS in one file. Ship to the web.