# バッチ設計書 8-libmruby.rake

## 概要

本ドキュメントは、静的ライブラリ（`libmruby.a` / `libmruby_core.a`）を生成し、ヘッダーファイルをコピーするRakeタスク定義ファイル `tasks/libmruby.rake` の設計仕様を記述する。

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

`libmruby.rake` は、mrubyのビルド成果物の中核となる静的ライブラリの生成、ヘッダーファイルの集約コピー、およびビルドフラグ情報ファイル（`flags.mak`）の生成を行うタスクを定義する。

**業務上の目的・背景**：mrubyを組み込みアプリケーションに統合するためには、静的ライブラリ（libmruby.a）とヘッダーファイル、およびコンパイル・リンクフラグの情報が必要である。本タスクはこれらを一つのパッケージとして提供するために、オブジェクトファイルのアーカイブ、分散するヘッダーファイルの集約、およびGNU Make形式のフラグファイルの生成を行う。`libmruby_core.a` はコアランタイムのみの最小ライブラリ、`libmruby.a` はmrblib・mrbgemsを含む完全なライブラリである。

**バッチの実行タイミング**：`rake build` の依存関係解決時に、productsの一部として自動実行される。`libmruby_core.a` は全ターゲットで生成され、`libmruby.a` は `libmruby_enabled?` が true のターゲットでのみ生成される。

**主要な処理内容**：
1. `libmruby_core_objs` の全オブジェクトファイルをアーカイブして `libmruby_core.a`（`libmruby_core_static`）を生成する
2. `libmruby_objs` の全オブジェクトファイルをアーカイブして `libmruby.a`（`libmruby_static`）を生成する
3. ヘッダーファイルを `build/{target}/include/` にコピーする（`expose_header_files` タスク）
4. 各gemのヘッダーも `include/mruby/gems/{gem_name}/` にコピーする
5. `libmruby.flags.mak` を生成し、CC/CXX/LD/LDFLAGSなどのビルドフラグを出力する

**前後の処理との関連**：core.rake（No.4）、mrblib.rake（No.5）、mrbgems.rake（No.6）で生成されたオブジェクトファイルが入力となる。生成されたライブラリは bin.rake（No.9）でバイナリのリンクに使用される。`products` に追加されるため `:build` タスク（No.2）の依存関係として処理される。

**影響範囲**：`build/{target}/lib/` に静的ライブラリ、`build/{target}/include/` にヘッダーファイル、`build/{target}/{libdir_name}/` にフラグファイルが生成される。

## バッチ種別

ビルド処理（ライブラリアーカイブ + ヘッダー集約 + フラグファイル生成）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（ビルド時に自動実行） |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | Rakeの依存関係解決により自動実行 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| libmruby_core_objs | コアオブジェクトファイルが生成済みであること |
| libmruby_objs | libmruby用オブジェクトファイルが生成済みであること（libmruby_enabled?の場合） |
| archiver | arコマンド等のアーカイバが利用可能であること |

### 実行可否判定

`libmruby_core_static` は全ターゲットで生成される。`libmruby_static` は `libmruby_enabled?` が true のターゲットでのみ生成される。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | ビルド設定から自動決定 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| libmruby_core_objs | オブジェクトファイル配列 | コアランタイムのオブジェクトファイル |
| libmruby_objs | オブジェクトファイル配列 | mrblib・mrbgemsを含む全オブジェクトファイル |
| include/*.h | ヘッダーファイル | mrubyのパブリックヘッダー |
| gems の export_include_paths | ヘッダーファイル | 各gemのエクスポートヘッダー |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| build/{target}/lib/libmruby_core.a | 静的ライブラリ | コアランタイムのみのライブラリ |
| build/{target}/lib/libmruby.a | 静的ライブラリ | 完全なmrubyライブラリ |
| build/{target}/include/ | ヘッダーファイル | 集約されたヘッダーファイル |
| build/{target}/include/mruby/gems/ | ヘッダーファイル | 各gemのヘッダーファイル |
| build/{target}/{libdir_name}/libmruby.flags.mak | Makefile | ビルドフラグ情報 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | libmruby_core.a / libmruby.a / libmruby.flags.mak |
| 出力先 | `build/{target}/lib/` および `build/{target}/{libdir_name}/` |
| 文字コード | バイナリ（ライブラリ）/ ASCII（flags.mak） |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. libmruby_core.a 生成
   └─ archiver.run で libmruby_core_objs を静的ライブラリにアーカイブ
   └─ products に libmruby_core_static を追加
2. libmruby_enabled? チェック
   └─ false の場合は以降をスキップ
3. ヘッダーファイルコピー（expose_header_files）
   └─ MRUBY_ROOT と各gem のヘッダーを build/{target}/include/ にコピー
   └─ タイムスタンプ比較で更新されたファイルのみコピー
4. libmruby.a 生成
   └─ expose_header_files タスクを invoke
   └─ archiver.run で libmruby_objs を静的ライブラリにアーカイブ
5. libmruby.flags.mak 生成
   └─ CC, CXX, AS, OBJC のコマンドとフラグを出力
   └─ LD, LDFLAGS, LIBS のリンカ情報を出力
   └─ MRUBY_LIBMRUBY_PATH を出力
6. products に libmruby_static を追加
```

### フローチャート

```mermaid
flowchart TD
    A[libmruby.rake 処理開始] --> B[libmruby_core.a 生成]
    B --> C[products に libmruby_core_static 追加]
    C --> D{libmruby_enabled?}
    D -->|いいえ| E[終了]
    D -->|はい| F[ヘッダーファイルコピー]
    F --> G[libmruby.a 生成]
    G --> H[libmruby.flags.mak 生成]
    H --> I[products に libmruby_static 追加]
    I --> E
```

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

### 操作別データベース影響一覧

本バッチではデータベース操作は発生しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | アーカイブエラー | arコマンドの実行失敗 | アーカイバの可用性を確認 |
| - | ファイルコピーエラー | ヘッダーファイルのコピー失敗 | ファイルシステムの権限を確認 |
| - | ファイル書き込みエラー | flags.makの書き込み失敗 | ディスク容量と権限を確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

`rake clean` を実行して再ビルドする。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 全オブジェクトファイル数 + ヘッダーファイル数 |
| 目標処理時間 | 数秒以内 |
| メモリ使用量上限 | アーカイバ依存 |

## 排他制御

同一ビルドターゲットに対する同時実行は想定されていない。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 進捗ログ | アーカイブ時 | アーカイブ対象ファイル |
| 進捗ログ | ヘッダーコピー時 | コピー対象ファイル |
| エラーログ | エラー発生時 | アーカイバのエラーメッセージ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 終了コード | 0以外 | CI/CDパイプラインの通知設定に依存 |

## 備考

- `expose_header_files` タスクはタイムスタンプ比較を行い、更新されたヘッダーファイルのみをコピーする。これにより不要なコピー操作を最小化している。
- `flags.mak` は GNU Make 形式で出力され、外部プロジェクトからmrubyを利用する際のビルドフラグ取得に使用される。
- `flags.mak` 内のパスは `$(MRUBY_PACKAGE_DIR)` 変数で抽象化されており、インストール先に依存しない形式となっている。
- Visual C++ ツールチェーンの場合、ライブラリ名は `libmruby`（`lib` プレフィックス付き）となる。それ以外は `mruby` となる。
- `libmruby_core.a` は全ターゲットで必ず生成されるが、`libmruby.a` と `flags.mak` は `libmruby_enabled?` が true の場合のみ生成される。
