jellix

v1.1.0

Published

a month ago

Single-file Multi-language WebAssembly Compiler for C/C++, Rust, Zig, and TypeScript.

0High
0Medium
0Low

ys-tech

webassembly wasm compiler c cpp rust zig typescript

English

Table of Contents (EN)

1. Overview (EN)

JELLIX is a single-command build system and compiler pipeline that merges low-level native languages (C/C++, Rust, Zig) and modern web technologies (TypeScript, TSX, CSS, HTML) into a single .jel file, producing an optimized WebAssembly application without complex configurations.

Key Highlights

Pure POSIX / Linux Native Core: Built with modern C++20 for seamless execution on Linux and container environments.
Cross-Language Native Linking: Compiles and statically links C, Rust, and Zig source units into a single native.wasm module via Emscripten.
Unified @jelll-sync: Annotate C/Rust/Zig structs to automatically generate synchronized TypeScript wrapper classes with native method bindings.
Zero-Copy Linear Memory Sharing: Direct memory referencing via Float32Array / Uint8Array for 60+ FPS physics simulation and procedural Web Audio synthesis.
Robust Standalone WASM: Complete support for Rust global static tables, allocation pools, and standard library components without Position-Independent Code (PIC) restrictions.
Integrated Dev Server with Cross-Origin Isolation: Built-in HTTP server injecting Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy headers to support high-resolution timers and SharedArrayBuffer.

2. Requirements (EN)

| Toolchain | Role | Setup | |:---|:---|:---| | Node.js + npm (>= 18) | CLI execution & esbuild runtime | https://nodejs.org/ | | Emscripten (emcc) | C/C++ compilation & WebAssembly linker | Automated via jellix --setup | | Rust (rustc / cargo) | Rust to wasm32-unknown-unknown compilation | Automated via jellix --setup | | Zig (zig) | Zig to wasm32-freestanding compilation | Automated via jellix --setup | | esbuild | TypeScript / TSX bundling and minification | Automated via jellix --setup |

3. Installation & Setup (EN)

Global Installation via npm

npm install -g jellix

Automated Interactive Toolchain Setup

Initialize your compiler toolchains with a single command:

jellix --setup

Use Arrow keys to navigate, Space to toggle [x], and Enter to confirm. Selected compilers are downloaded, unpacked, and exported to your ~/.bashrc automatically.

4. Input File Format (.jel) (EN)

JELLIX structures code using explicit language blocks: lang.<language> { ... }.

Recommended extension: .jel (Backward-compatible with .jelll, .jellix, .jsbc, .tsbc, .tsxbc).

lang.c {
    // C/C++ code -> compiled and linked into native.wasm
}

lang.rs {
    // Rust code -> compiled via cargo to wasm32-unknown-unknown
}

lang.zig {
    // Zig code -> compiled via zig to wasm32-freestanding
}

lang.ts {
    // TypeScript code -> bundled via esbuild
}

lang.tsx {
    // TSX / React UI components -> bundled via esbuild
}

lang.css {
    // CSS stylesheet -> injected into <style> in dist/index.html
}

lang.html {
    // HTML markup -> injected into <body> in dist/index.html
}

5. Language Blocks (EN)

| Block | Source Language | Compiler / Bundler | Output Destination | |:---|:---|:---|:---| | lang.c | C / C++ | Emscripten (emcc) | dist/native.wasm | | lang.rs | Rust | Cargo (rustc) | dist/native.wasm | | lang.zig | Zig | Zig (zig) | dist/native.wasm | | lang.js | JavaScript | esbuild | dist/bundle.js | | lang.ts | TypeScript | esbuild | dist/bundle.js | | lang.tsx | TSX / React | esbuild | dist/bundle.js | | lang.css | CSS | Inliner | dist/index.html (<style>) | | lang.html | HTML | Inliner | dist/index.html (<body>) |

6. File Inclusion (call Directive) (EN)

Modularize complex projects across multiple files and directories using call:

// main.jel
call "components/math.jel"
call "components/ui.jel"

lang.ts {
    // Logic from included files is merged and accessible seamlessly
}

call "path" inlines target file contents in place before parsing.
Paths are resolved relative to the calling file.
Recursive calls are supported with automatic circular dependency detection.

7. @jelll-sync (Struct & Method Synchronization) (EN)

Annotating structs with // @jelll-sync instructs JELLIX to generate memory accessors on the native side and emit high-level TypeScript classes mapped to WASM linear memory:

C Definition

lang.c {
#include <math.h>

// @jelll-sync
struct Vector2 {
    float x;
    float y;
};

// Method convention: ReturnType StructName_methodName(StructName* self, ...)
extern "C" {
    float Vector2_length(Vector2* self) {
        return sqrtf(self->x * self->x + self->y * self->y);
    }
}
}

TypeScript Usage

lang.ts {
const v = new Vector2();
v.x = 3.0;
v.y = 4.0;
console.log(v.length()); // 5.0 (Executed directly inside WebAssembly)
}

8. Development Mode (jellix dev) (EN)

jellix dev app.jel

Launches an integrated development environment with live reloading:

Performs initial compilation of all native and script blocks.
Starts local HTTP server at http://127.0.0.1:8000.
Injects COOP / COEP headers to unlock SharedArrayBuffer.
Watches .jel files for changes every 500ms and triggers instant rebuilds on save (Ctrl + S).

9. Build Pipeline (EN)

When running jellix app.jel:

app.jel
  │
  ├─► [Preprocess] ── Recursively inlines `call` file paths
  ├─► [Parse] ─────── Extracts lang.c / lang.rs / lang.zig / lang.ts blocks
  ├─► [Sync] ──────── Parses @jelll-sync structs & generates TS wrapper classes
  ├─► [C Compile] ─── emcc -O3 -c (.bc_build/core.cpp)
  ├─► [Rust Build] ── cargo build --target wasm32-unknown-unknown (.bc_build/cargo_build)
  ├─► [Zig Build] ─── zig build-obj -target wasm32-freestanding (.bc_build/core.zig)
  ├─► [WASM Link] ─── emcc -s STANDALONE_WASM=1 -Wl,--export-all (dist/native.wasm)
  ├─► [JS Bundle] ─── esbuild --bundle --minify --format=esm (dist/bundle.js)
  └─► [HTML Emit] ─── Injects styles & scripts into (dist/index.html)

10. Output Structure (EN)

project/
├── app.jel               # Source file
├── .bc_build/            # Intermediate build artifacts
│   ├── core.cpp          # Extracted C++ code + sync accessors
│   ├── core.zig          # Extracted Zig code
│   ├── cargo_build/      # Generated Cargo package
│   ├── wasm_init.tsx     # WebAssembly dynamic loader
│   ├── entry.tsx         # Host TypeScript script
│   ├── emcc.stderr.log
│   └── esbuild.stderr.log
└── dist/                 # Deployment target (Deploy this directory)
    ├── native.wasm       # Statically linked WebAssembly binary
    ├── bundle.js         # Minified JavaScript bundle (ESM)
    └── index.html        # Production entrypoint

11. WASM Runtime API (EN)

| Global | Type | Description | |:---|:---|:---| | native | Object | All exported extern "C" functions from WASM | | sharedBuffer | ArrayBuffer | Direct linear memory buffer for zero-copy views | | sharedMemory | WebAssembly.Memory | Shared WebAssembly linear memory instance |

Zero-Copy Array Access Example

const ptr = native.get_buffer_ptr();
const count = native.get_count();
const view = new Float32Array(sharedBuffer, ptr, count * 4);

12. CLI Reference (EN)

| Command | Description | |:---|:---| | jellix <file.jel> | Compile .jel into deployment-ready dist/ | | jellix dev <file.jel> | Start dev server on port 8000 with 500ms live-reload | | jellix --watch <file.jel> | Alias for jellix dev | | jellix --setup | Launch interactive multi-select toolchain installer | | jellix setup | Alias for jellix --setup |

13. Troubleshooting & Error Reference (EN)

| Diagnostic Output | Root Cause & Resolution | |:---|:---| | Unsupported extension | Ensure the input uses .jel (or .jelll, .jellix, .tsbc). | | At least one native block is required | Add at least one lang.c, lang.rs, or lang.zig block. | | emcc not found | Run jellix --setup or verify Emscripten is sourced in your terminal. | | cargo not found | Run jellix --setup or install Rust via rustup. | | zig not found | Run jellix --setup or add Zig 0.12.0 to your PATH. | | esbuild not found | Run npm install -g esbuild. | | Circular call detected | Check call "..." directives for infinite recursion loops. | | [BUILD ERROR] | Check detailed compiler diagnostics printed directly in the terminal. |

14. Full Showcase Example (EN)

lang.c {
// @jelll-sync
struct Particle {
    float x;
    float y;
};

extern "C" {
    int c_calc(int a, int b) { return a + b; }
}
}

lang.rs {
#[no_mangle]
pub extern "C" fn rust_calc(val: i32) -> i32 {
    val * 10
}
}

lang.zig {
export fn zig_calc(val: i32) i32 {
    return val + 500;
}
}

lang.css {
body {
    background: #030712;
    color: #f9fafb;
    font-family: ui-monospace, monospace;
    padding: 2rem;
}
}

lang.html {
<div id="output">Loading JELLIX...</div>
}

lang.ts {
const p = new (globalThis as any).Particle();
p.x = 12.5;
p.y = 25.0;

const c = native.c_calc(20, 22);
const rs = native.rust_calc(4);
const zg = native.zig_calc(20);

document.getElementById('output')!.innerHTML = `
    <h2>JELLIX Multi-Language Engine</h2>
    <div>C++: ${c}</div>
    <div>Rust: ${rs}</div>
    <div>Zig: ${zg}</div>
    <div>Struct Position: (${p.x}, ${p.y})</div>
`;
}

日本語

目次 (JA)

1. 概要 (JA)

JELLIX は、C/C++・Rust・Zig のネイティブコードと、TypeScript/TSX/JavaScript、CSS、HTML を単一の .jel ファイルに記述し、コマンド一発で WebAssembly アプリケーションをビルド・配信する次世代コンパイラです。

主な特徴

完全 Linux ネイティブ対応: Win32 依存を全廃し、モダン C++20 標準と POSIX 準拠で構築。
多言語同時リンク: C、Rust、Zig のオブジェクトファイルを Emscripten 経由で 1 つの native.wasm に完全統合。
次世代 @jelll-sync: C言語だけでなく、Rust および Zig の構造体・メソッドを TypeScript クラスへ自動バインド。
ゼロコピー共有メモリ: Float32Array によるポインタ直接参照で、数千〜数万のエンティティを 60FPS で描画可能。
スタンドアロン WASM 形式: Rust の静的配列やグローバルメモリを制限なくそのままリンク可能。
エラーログ表示の強化: TSX や各言語のビルドエラーを色付きでわかりやすくコンソールに出力。

2. 必要環境 (JA)

| ツール | 用途 | インストール方法 | |:---|:---|:---| | Node.js + npm (>= 18) | JELLIX CLI と esbuild の実行環境 | https://nodejs.org/ | | Emscripten (emcc) | C/C++ コンパイルおよび WASM リンク | jellix --setup で自動導入 | | Rust (rustc / cargo) | Rust → WASM コンパイル（任意） | jellix --setup で自動導入 | | Zig (zig) | Zig → WASM コンパイル（任意） | jellix --setup で自動導入 | | esbuild | TypeScript / TSX / JS バンドル | npm で自動導入 |

3. インストール＆セットアップ (JA)

npm 経由（推奨）

npm install -g jellix

ツールチェーンの対話型セットアップ

jellix --setup

矢印キーで移動、スペースで [x] を選択、Enter で確定します。選択されたコンパイラが自動でダウンロード・解凍され、~/.bashrc に PATH が登録されます。

4. 入力ファイル形式 (.jel) (JA)

lang.<言語名> { ... } ブロックを用いて複数言語のコードを記述します。

推奨拡張子: .jel（互換拡張子: .jelll, .jellix, .jsbc, .tsbc, .tsxbc）

lang.c {
    // C/C++ コード -> WASM にコンパイル
}

lang.rs {
    // Rust コード -> WASM にコンパイル
}

lang.zig {
    // Zig コード -> WASM にコンパイル
}

lang.ts {
    // TypeScript コード -> esbuild でバンドル
}

lang.tsx {
    // React / TSX コード -> esbuild でバンドル
}

lang.css {
    // CSS -> dist/index.html の <style> に注入
}

lang.html {
    // HTML -> dist/index.html の <body> に注入
}

5. 言語ブロック (JA)

| ブロック | 言語 | 出力先 | |:---|:---|:---| | lang.c | C / C++ | dist/native.wasm (emcc 経由) | | lang.rs | Rust | dist/native.wasm (cargo 経由) | | lang.zig | Zig | dist/native.wasm (zig 経由) | | lang.js | JavaScript | dist/bundle.js (esbuild 経由) | | lang.ts | TypeScript | dist/bundle.js (esbuild 経由) | | lang.tsx | TSX (React等) | dist/bundle.js (esbuild 経由) | | lang.css | CSS | dist/index.html の <style> | | lang.html | HTML | dist/index.html の <body> |

6. ファイル分割 (call ディレクティブ) (JA)

大規模なプロジェクトを複数ファイルに分割できます：

// main.jel
call "components/math.jel"
call "components/ui.jel"

lang.ts {
    // 外部ファイルの内容がインライン展開され、そのまま使用可能
}

7. @jelll-sync (構造体・メソッド同期) (JA)

C構造体に // @jelll-sync を付けると、TypeScript 側のラッパークラスが自動生成されます：

C 側の記述

lang.c {
#include <math.h>

// @jelll-sync
struct Vector2 {
    float x;
    float y;
};

extern "C" {
    float Vector2_length(Vector2* self) {
        return sqrtf(self->x * self->x + self->y * self->y);
    }
}
}

TypeScript 側での利用

lang.ts {
const v = new Vector2();
v.x = 3.0;
v.y = 4.0;
console.log(v.length()); // 5.0 (WASM経由で自動呼び出し)
}

8. 開発モード (jellix dev) (JA)

jellix dev app.jel

初回ビルドを実行。
ローカル開発サーバーが http://127.0.0.1:8000 で起動。
SharedArrayBuffer を有効化する COOP / COEP ヘッダーを自動付与。
500ms ごとにファイル変更を検知し、保存時に自動リビルド。

9. ビルドパイプライン (JA)

app.jel
  │
  ├─► [プリプロセス] ── call ディレクティブを再帰展開
  ├─► [パース] ──────── lang.c / lang.rs / lang.zig / lang.ts を抽出
  ├─► [@jelll-sync] ── 構造体を解析し TS ラッパークラスを自動生成
  ├─► [C コンパイル] ── emcc でオブジェクト化 (.bc_build/core.cpp)
  ├─► [Rust ビルド] ── cargo で静的ライブラリ化 (.bc_build/cargo_build)
  ├─► [Zig ビルド] ──── zig build-obj でオブジェクト化 (.bc_build/core.zig)
  ├─► [WASM リンク] ── emcc -s STANDALONE_WASM=1 でリンク (dist/native.wasm)
  ├─► [JS バンドル] ── esbuild でバンドル (dist/bundle.js)
  └─► [HTML 出力] ──── CSS と HTML を注入 (dist/index.html)

10. 出力構成 (JA)

project/
├── app.jel               # ソースファイル
├── .bc_build/            # 中間ビルドディレクトリ
│   ├── core.cpp          # Cコード + 同期アクセサ
│   ├── core.zig          # Zigコード
│   ├── cargo_build/      # Rust中間プロジェクト
│   ├── wasm_init.tsx     # WASMローダーコード
│   ├── entry.tsx         # TSエントリーポイント
│   ├── emcc.stderr.log
│   └── esbuild.stderr.log
└── dist/                 # デプロイ対象ディレクトリ
    ├── native.wasm       # コンパイル済み WASM
    ├── bundle.js         # バンドル済み JS (ESM)
    └── index.html        # エントリー HTML

11. WASM ランタイム API (JA)

| グローバル変数 | 型 | 説明 | |:---|:---|:---| | native | Object | 全ての extern "C" 関数がプロパティとして利用可能 | | sharedBuffer | ArrayBuffer | リニアメモリのバイト配列バッファ (ゼロコピー参照用) | | sharedMemory | WebAssembly.Memory | 共有リニアメモリインスタンス |

12. CLI リファレンス (JA)

| コマンド | 説明 | |:---|:---| | jellix <file.jel> | 指定ファイルをビルドし dist/ に出力 | | jellix dev <file.jel> | ライブリロード開発サーバーを起動 (ポート 8000) | | jellix --watch <file.jel> | jellix dev のエイリアス | | jellix --setup | 対話型ツールチェーンインストーラーを起動 | | jellix setup | jellix --setup のエイリアス |

13. エラーリファレンス (JA)

| エラーメッセージ | 原因と対処法 | |:---|:---| | Unsupported extension | .jel, .jelll, .jellix, .jsbc, .tsbc, .tsxbc を使用してください | | At least one native block is required | lang.c, lang.rs, lang.zig のいずれかを追加してください | | emcc not found | jellix --setup を実行するか、Emscripten を導入してください | | cargo not found | jellix --setup を実行するか、Rust を導入してください | | zig not found | jellix --setup を実行するか、Zig を導入してください | | esbuild not found | npm i -g esbuild を実行してください | | Circular call detected | call ディレクティブの循環参照を確認してください | | [BUILD ERROR] | コンパイルエラーの詳細がターミナルに出力されます。中間コードを確認してください |

14. サンプルコード集 (JA)

最小構成サンプル

lang.c {
extern "C" {
    int add(int a, int b) { return a + b; }
}
}

lang.ts {
document.body.textContent = "2 + 3 = " + native.add(2, 3);
}

多言語トリニティ構成 (C + Rust + Zig + TS)

lang.c {
extern "C" { int calc_c() { return 10; } }
}

lang.rs {
#[no_mangle]
pub extern "C" fn calc_rs() -> i32 { 20 }
}

lang.zig {
export fn calc_zig() i32 { return 30; }
}

lang.ts {
const total = native.calc_c() + native.calc_rs() + native.calc_zig();
console.log("Total:", total); // 60
}

License

Distributed under the MIT License. See LICENSE for more information.