hakorune/docs/guides/cranelift_aot_egui_hello.md

Cranelift AOT で Egui Hello を実行する手順（Windows）

本ガイドは、Cranelift AOT 経路で Egui の hello サンプル（プラグイン版）をネイティブ EXE として実行する最短手順です。

前提

• 対象: Windows（PowerShell 推奨）
• プラグイン Egui を使用（with-egui 機能を有効化）
• JIT ランタイムは封印（デフォルト無効）。対象バックエンドは Interpreter / VM / Cranelift AOT / LLVM AOT の4つ。

用語

• ユーザーBox: Nyash で実装した通常のクラス
• プラグインBox: DLL/so 経由の TypeBox（v2 PluginBoxV2）
• コア埋め込みBox: ランタイム同梱の最小セット（旧: ビルトイン）

手順

1. プラグイン（Egui）を GUI 対応でビルド

   • cd plugins/nyash-egui-plugin
   • cargo build --release --features with-egui

2. Nyash 本体をビルド（Cranelift AOT ツール込み）

   • リポジトリ直下へ戻る: cd ../../
   • cargo build --release --features cranelift-jit

3. AOT EXE を生成（ワンショット推奨）

   • Windows ワンショット: pwsh -File tools/windows/build_egui_aot.ps1 -Input apps/egui-hello-plugin/main.hako -Out app_egui
     • このスクリプトは他スクリプトをネスト呼び出しせず、引数を確実に伝播します（従来の「スクリプト→スクリプト」連鎖で引数が落ちる問題を解消）。
   • 共通版（PowerShell）: powershell -ExecutionPolicy Bypass -File tools/build_aot.ps1 -Input apps/egui-hello-plugin/main.hako -Out app_egui
   • 代替（Bash 版）: bash tools/build_aot.sh apps/egui-hello-plugin/main.hako -o app_egui

4. 実行（画面が表示されれば成功）

備考

• .o 生成時（Nyash 実行）にもウィンドウが開きます。リンクを継続するため、いったんウィンドウを閉じてください。

WSL で表示されない場合（Wayland→X11 切り替え）

• 症状: WaylandError(Connection(NoCompositor)) などで即終了しウィンドウが出ない。
• 対処 1（推奨）: X11 に強制
  • WAYLAND_DISPLAY= を空にして Wayland を無効化し、X11 を選択させます。
  • 実行例: WAYLAND_DISPLAY= WINIT_UNIX_BACKEND=x11 ./app_egui
  • 必要に応じて: LIBGL_ALWAYS_INDIRECT=1 WAYLAND_DISPLAY= WINIT_UNIX_BACKEND=x11 ./app_egui
• 対処 2: Wayland を正しく通す（WSLg）
  • export XDG_RUNTIME_DIR=/mnt/wslg/runtime-dir
  • 実行例: WINIT_UNIX_BACKEND=wayland ./app_egui
• チェック: echo $XDG_RUNTIME_DIR $WAYLAND_DISPLAY $DISPLAY が … wayland-0 :0 のように設定されているか、ls -ld /mnt/wslg/runtime-dir でパスが存在するか確認。
  • 実行はリポジトリ直下（nyash.toml と plugins の相対解決に必要）
  • 任意ログ: set NYASH_CLI_VERBOSE=1（PowerShell: $env:NYASH_CLI_VERBOSE='1'）
  • 実行: ./app_egui.exe

トラブルシュート

• プラグインが見つからない
  • nyash.toml の [plugin_paths].search_paths に plugins/*/target/release が含まれているか確認
  • それでも解決しない場合は nyash_egui_plugin.dll を EXE と同フォルダへコピーして暫定回避
• ログで確認（任意）
  • NYASH_DEBUG_PLUGIN=1 でプラグイン登録/ロードの詳細を出力
  • NYASH_CLI_VERBOSE=1 で補助的な実行ログを有効化

補足

• 旧ビルトイン Egui（apps/egui-hello/main.hako）は gui-builtin-legacy 機能に隔離されました。 AOT での GUI はプラグイン版（apps/egui-hello-plugin/main.hako）を使用してください。
• JIT ランタイム（Cranelift JIT 直実行）は封印中です。必要時のみ --features "cranelift-jit,jit-runtime" で有効化してください。