# バッチ設計書 37-Makefile.emscripten (example_glfw_wgpu)

## 概要

本ドキュメントは、ImGuiプロジェクトにおけるGLFW + WebGPUサンプル「example_glfw_wgpu」のEmscriptenビルドシステムの設計仕様を記述するものである。

### 本バッチの処理概要

このMakefile.emscriptenは、GLFW + WebGPUサンプルアプリケーションをWebAssembly（WASM）にコンパイルするためのEmscripten専用ビルドスクリプトである。WebGPUは次世代のWebグラフィックスAPIであり、VulkanやMetal、DirectX12に相当する低レベルAPIをWebブラウザで利用可能にする。レガシーのUSE_WEBGPUと新しいDawn-based emdawnwebgpuポートの両方に対応している。

**業務上の目的・背景**：WebGPUは従来のWebGLよりも高性能で効率的なグラフィックス処理をWebブラウザ上で実現する。次世代Webアプリケーションの開発において、ImGuiをWebGPUベースのアプリケーションに統合するための標準的なリファレンス実装として、このサンプルは重要である。Emscripten 4.0.10以降ではDawn-basedのemdawnwebgpuポートが推奨される。

**バッチの実行タイミング**：開発者による手動実行、またはCI/CDパイプラインでのWebビルド実行時。

**主要な処理内容**：
1. Emscriptenコンパイラ環境の使用
2. contrib.glfw3ポートの設定（高DPIサポート）
3. WebGPUポートの設定（レガシーまたはDawn-based）
4. ImGuiコアおよびバックエンドソースのコンパイル
5. web/ディレクトリへのHTML/JS/WASMファイル生成

**前後の処理との関連**：Emscripten SDKの事前インストールと環境設定が必要。WebGPU対応ブラウザが実行に必要。

**影響範囲**：web/ディレクトリにindex.html、index.js、index.wasmを生成する。

## バッチ種別

ビルドスクリプト / Makefile（Emscripten）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | 手動 / CI/CD |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Emscripten SDK | emsdkがインストールされ環境が有効化されていること |
| emcc/em++ | Emscriptenコンパイラが利用可能であること |
| Emscripten 4.0.10+ | emdawnwebgpuポート使用時は4.0.10以上が必要 |

### 実行可否判定

Emscripten環境がロードされており、emcc/em++コマンドが実行可能であれば実行可能。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| USE_FILE_SYSTEM | 整数 | No | 0 | ファイルシステムを有効化しフォントを埋め込む |
| IMGUI_IMPL_WEBGPU_BACKEND_WGPU | 定義 | No | 未定義 | レガシーWebGPU実装を使用（4.0.10未満） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| main.cpp | C++ソース | サンプルアプリケーションのメインファイル |
| imgui.cpp | C++ソース | ImGuiコアライブラリ |
| imgui_demo.cpp | C++ソース | ImGuiデモ機能 |
| imgui_draw.cpp | C++ソース | ImGui描画機能 |
| imgui_tables.cpp | C++ソース | ImGuiテーブル機能 |
| imgui_widgets.cpp | C++ソース | ImGuiウィジェット機能 |
| imgui_impl_glfw.cpp | C++ソース | GLFWバックエンド実装 |
| imgui_impl_wgpu.cpp | C++ソース | WebGPUバックエンド実装 |
| shell_minimal.html | HTMLテンプレート | 出力HTMLのシェルテンプレート |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| web/index.html | HTML | WebアプリケーションのHTML |
| web/index.js | JavaScript | WebAssemblyローダー |
| web/index.wasm | WASM | WebAssemblyバイナリ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | index.html, index.js, index.wasm |
| 出力先 | web/ |
| 文字コード | UTF-8（HTML/JS）、バイナリ（WASM） |
| 区切り文字 | - |

## 処理フロー

### 処理シーケンス

```
1. Emscripten環境確認
   └─ emcc/em++コマンドの利用可能性確認
2. WebGPUポート選択
   └─ emdawnwebgpu（4.0.10+）またはUSE_WEBGPU（レガシー）
3. Emscriptenオプション設定
   └─ DISABLE_EXCEPTION_CATCHING、contrib.glfw3ポート
4. リンカーオプション設定
   └─ WASM、ALLOW_MEMORY_GROWTH、ASYNCIFY等
5. ファイルシステムオプション確認
   └─ USE_FILE_SYSTEM=0: ファイル無効、=1: フォント埋め込み
6. webディレクトリ作成
   └─ mkdir web
7. ソースコンパイル
   └─ em++で各.cppを.oにコンパイル
8. リンク処理
   └─ shell_minimal.htmlをテンプレートに出力生成
9. 完了メッセージ出力
   └─ "Build complete for web/index.html"
```

### フローチャート

```mermaid
flowchart TD
    A[make -f Makefile.emscripten] --> B[Emscripten環境確認]
    B --> C{Emscripten バージョン}
    C -->|4.0.10+| D[emdawnwebgpuポート使用]
    C -->|4.0.10未満| E[USE_WEBGPU レガシー]
    D --> F{USE_FILE_SYSTEM?}
    E --> F
    F -->|0| G[ファイルシステム無効化]
    F -->|1| H[フォント埋め込み有効化]
    G --> I[webディレクトリ作成]
    H --> I
    I --> J[ソースコンパイル em++]
    J --> K[リンク処理]
    K --> L[index.html/js/wasm生成]
    L --> M[完了]
```

## データベース操作仕様

該当なし（データベース操作を行わないビルドスクリプト）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | コンパイルエラー | ソースコードエラー | エラーメッセージを確認し修正 |
| 127 | コマンド未発見 | Emscripten環境未設定 | emsdk_envを実行 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（手動再実行） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

Emscripten SDKのバージョンを確認し、WebGPUポートの互換性を確認する。

## トランザクション仕様

該当なし

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 8ファイルのコンパイル |
| 目標処理時間 | 数十秒〜数分 |
| メモリ使用量上限 | Emscriptenコンパイルに依存 |

## 排他制御

同一ディレクトリでの並列make実行は非推奨。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 完了ログ | ビルド完了時 | "Build complete for web/index.html" |
| エラーログ | エラー発生時 | コンパイラのエラーメッセージ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ビルド失敗 | 1回 | CI/CD通知 |

## 備考

- WebGPUは次世代Web グラフィックスAPIでWebGLより高性能
- ASYNCIFY=1が必要（WebGPU非同期操作のため）
- Emscripten 4.0.10以上ではemdawnwebgpuポートを推奨
- 4.0.10未満ではレガシーUSE_WEBGPU=1とIMGUI_IMPL_WEBGPU_BACKEND_WGPUを使用
- contrib.glfw3ポートで高DPIディスプレイをサポート
- `make serve`でPython HTTPサーバーを起動してテスト可能
- cleanターゲットで.wasm.preファイルも削除
