# バッチ設計書 22-zig-cc-wrapper.sh

## 概要

本ドキュメントは、lua-language-serverプロジェクトにおけるZigコンパイララッパースクリプト（zig-cc-wrapper.sh）の設計仕様を定義する。

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

このバッチは、LinuxビルドにおいてZigコンパイラを使用する際に、互換性のないリンカフラグ（-lstdc++fs）をフィルタリングするラッパースクリプトである。luamakeビルドシステムから呼び出され、C++コンパイラとして機能する。

**業務上の目的・背景**：lua-language-serverはLinux環境での古いglibc（2.17）との互換性を確保するため、Zigコンパイラを使用している。しかし、依存ライブラリ（bee.lua）がC++17のファイルシステム機能を使用しており、GCCでは-lstdc++fsフラグが必要となる。一方、Zigのlibc++には既にファイルシステムサポートが組み込まれているため、このフラグを渡すとリンクエラーが発生する。本バッチは、この互換性問題を解決するためのラッパーとして機能し、Zigコンパイラへ渡される引数から-lstdc++fsを除外することで、ビルドを成功させる。

**バッチの実行タイミング**：CI/CDパイプライン（GitHub Actions）でのLinuxビルド時、またはローカル開発環境でUSE_ZIG環境変数が設定されている場合にluamakeから呼び出される。コンパイル対象ファイルごとに複数回実行される。

**主要な処理内容**：
1. コマンドライン引数をループで処理
2. 各引数が-lstdc++fsでないかチェック
3. -lstdc++fs以外の引数を新しい配列に追加
4. フィルタリングされた引数でzig c++コマンドを実行

**前後の処理との関連**：本バッチはmake/detect_platform.luaから参照され、lm.cc（C++コンパイラ）として設定される。luamakeがソースファイルをコンパイルする際に、各コンパイル単位に対して本スクリプトが呼び出される。コンパイル後のオブジェクトファイルは、別途zigリンカによってリンクされる。

**影響範囲**：本バッチはLinuxプラットフォームでのビルドプロセスにのみ影響する。ビルド成果物（lua-language-server実行ファイル）の生成に直接関与するため、ビルドの成否に重要な影響を与える。

## バッチ種別

ビルドユーティリティ（コンパイララッパー）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | ビルド時（ソースファイルごと） |
| 実行時刻 | ビルド実行時 |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | luamakeビルドシステム |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Linuxプラットフォーム | Linuxでのビルド時のみ使用される |
| USE_ZIG環境変数 | "1"または"true"に設定されている |
| Zigコンパイラ | システムにzigがインストールされている |
| 実行権限 | スクリプトに実行権限が付与されている |

### 実行可否判定

- make/detect_platform.luaでUSE_ZIG環境変数がチェックされ、有効な場合のみ本スクリプトがlm.ccに設定される
- スクリプトに実行権限がない場合はビルドが失敗する（GitHub Actionsでは事前にchmod +xで付与）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| $@ | コマンドライン引数 | Yes | - | コンパイラに渡す全引数 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| コマンドライン引数 | シェル引数 | luamakeから渡されるコンパイラフラグとソースファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| オブジェクトファイル | .o | zigコンパイラが生成するオブジェクトファイル |
| 標準出力/エラー | テキスト | zigコンパイラの出力 |
| 終了コード | 数値 | zigコンパイラの終了コード |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | zigコンパイラによる（通常ソースファイル名.o） |
| 出力先 | luamakeのビルドディレクトリ |
| 文字コード | N/A（バイナリ） |
| 区切り文字 | N/A |

## 処理フロー

### 処理シーケンス

```
1. 引数配列の初期化
   └─ args=() で空の配列を作成
2. 引数のループ処理
   └─ for arg in "$@" で全引数を順に処理
3. フィルタリング判定
   └─ 各引数が"-lstdc++fs"でないかチェック
4. 引数の追加
   └─ -lstdc++fs以外の引数をargs配列に追加
5. zigコンパイラ実行
   └─ exec zig c++ "${args[@]}" でフィルタ済み引数を渡して実行
```

### フローチャート

```mermaid
flowchart TD
    A[スクリプト開始] --> B[args配列初期化]
    B --> C[引数ループ開始]
    C --> D{引数が残っている?}
    D -->|Yes| E{引数 == -lstdc++fs?}
    E -->|Yes| F[スキップ]
    E -->|No| G[argsに追加]
    F --> C
    G --> C
    D -->|No| H[exec zig c++ args]
    H --> I[スクリプト終了]
```

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

本バッチはデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 非0 | コンパイルエラー | zigコンパイラがエラーを返した場合 | ソースコードを修正する |
| 127 | コマンド未発見 | zigがインストールされていない | zigをインストールする |
| 126 | 実行権限なし | スクリプトに実行権限がない | chmod +xで権限を付与 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

- コンパイルエラーの場合はzigコンパイラのエラーメッセージを確認
- zigコマンドが見つからない場合はPATH環境変数を確認
- フィルタリングが原因の場合はスクリプトのロジックを確認

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A（データベース操作なし） |
| コミットタイミング | N/A |
| ロールバック条件 | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | ソースファイル数（数十〜数百回/ビルド） |
| 目標処理時間 | ファイルあたり数秒（zigコンパイラ依存） |
| メモリ使用量上限 | zigコンパイラ依存 |

## 排他制御

luamakeが並列ビルドを行う場合、本スクリプトの複数インスタンスが同時に実行される可能性がある。各インスタンスは独立したソースファイルを処理するため、排他制御は不要。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 標準出力 | コンパイル中 | zigコンパイラの出力 |
| 標準エラー | エラー発生時 | zigコンパイラのエラーメッセージ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ビルド失敗 | 1回 | GitHub Actions / 開発者 |

## 備考

- 本スクリプトはLinuxビルドでglibc 2.17互換性を確保するために必要
- make/detect_platform.luaで以下のターゲットが設定される：
  - linux-x64: x86_64-linux-gnu.2.17
  - linux-arm64: aarch64-linux-gnu.2.17
- Zigのlibc++にはC++17ファイルシステムサポートが組み込まれているため、-lstdc++fsは不要
- bee.luaライブラリがstdc++fsを要求するが、Zigビルドでは本ラッパーでフィルタリング
- GitHub Actionsでは`.github/workflows/build.yml`で実行権限が付与される（chmod +x）
