# バッチ設計書 21-rake install

## 概要

本ドキュメントは、mrubyプロジェクトにおける `rake install` タスクのバッチ設計書である。ホストビルドターゲット向けにコンパイル済みプロダクト（バイナリ、ヘッダーファイル、ライブラリ）をシステムのインストール先ディレクトリにインストールする処理を定義する。

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

`rake install` は、mrubyのホストビルドターゲットに対して、ビルド済みの全プロダクト（実行可能バイナリ、ヘッダーファイル、静的ライブラリ）を指定されたインストール先ディレクトリにコピーするRakeタスクである。

**業務上の目的・背景**：mrubyをシステム全体で利用可能にするために、ビルドディレクトリからシステムの標準パス（`/usr/local` 等）へプロダクトを配置する必要がある。開発者やパッケージメンテナがmrubyをシステムにインストールする際の標準的な手段を提供する。

**バッチの実行タイミング**：手動実行。ビルド完了後、ユーザーがmrubyをシステムにインストールしたい場合に随時実行する。

**主要な処理内容**：
1. `install:full:host` タスクを呼び出し、ホストビルドターゲットのフルインストールを実行する
2. 内部的には `install:bin:host`（バイナリインストール）を先に実行した後、ヘッダーファイルとライブラリをコピーする
3. `DESTDIR` と `install_prefix` を組み合わせたインストール先パスにファイルを配置する

**前後の処理との関連**：本タスクは `rake all`（ビルド完了）に依存する。`install:bin:host` タスクが前提として実行され、バイナリインストール後にヘッダーとライブラリがインストールされる。後続バッチは特になし。

**影響範囲**：ファイルシステム上のインストール先ディレクトリ（デフォルト: `/usr/local`）配下の `bin/`、`include/`、`lib/` ディレクトリに影響を与える。

## バッチ種別

ファイル配置（インストール）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | 任意 |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | 手動（`rake install` コマンド実行） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| ビルド完了 | `rake all` が正常に完了し、ビルド成果物が `build/host/` 配下に存在すること |
| 書き込み権限 | インストール先ディレクトリへの書き込み権限があること（必要に応じて `sudo` を使用） |
| Ruby環境 | Rakeが実行可能なRuby環境がセットアップされていること |

### 実行可否判定

ビルドディレクトリにホストターゲットのプロダクトが存在する場合に実行可能。`install:bin:host` タスク内で `all` タスクへの依存が定義されているため、未ビルドの場合はビルドから自動的に実行される。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| DESTDIR | 環境変数（文字列） | No | `""`（空文字列） | インストール先のルートプレフィックス。パッケージング時に使用 |
| PREFIX | 環境変数（文字列） | No | `/usr/local` | インストール先のプレフィックスディレクトリ |
| INSTALL_PREFIX | 環境変数（文字列） | No | `/usr/local` | PREFIXの代替。PREFIXが優先 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| build/host/bin/ | バイナリファイル | コンパイル済み実行可能ファイル（mrbc, mruby, mirb等） |
| build/host/host-bin/ | バイナリファイル | ホスト向け追加バイナリ |
| build/host/include/ | ヘッダーファイル | mrubyヘッダーファイル群 |
| build/host/lib/ | ライブラリファイル | 静的ライブラリ（libmruby.a等） |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| {DESTDIR}{PREFIX}/bin/ | バイナリファイル | 実行可能ファイル群 |
| {DESTDIR}{PREFIX}/include/ | ヘッダーファイル | mrubyヘッダーファイル群 |
| {DESTDIR}{PREFIX}/lib/ | ライブラリファイル | 静的ライブラリ群 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | ビルド成果物と同名 |
| 出力先 | `{DESTDIR}{PREFIX}/` 配下の対応ディレクトリ |
| 文字コード | バイナリ |
| 区切り文字 | N/A |

## 処理フロー

### 処理シーケンス

```
1. rake install タスク開始
   └─ install:full:host タスクに委譲
2. install:bin:host タスク実行
   └─ all タスクに依存（未ビルドならビルドを実行）
   └─ build/host/{bin,host-bin}/ 配下のファイルをインストール先にコピー
   └─ install_excludes フィルタで除外対象を除外
3. install:full:host タスク実行
   └─ build/host/{include,lib}/ 配下のファイルをインストール先にコピー
   └─ install_excludes フィルタで除外対象を除外（libmruby_core.a を除外）
4. 各ファイルについて install_D 関数でコピー
   └─ 既存ファイルの削除 → ディレクトリ作成 → ファイルコピー
```

### フローチャート

```mermaid
flowchart TD
    A[rake install 開始] --> B[install:full:host に委譲]
    B --> C[install:bin:host 実行]
    C --> D{all タスク完了?}
    D -->|No| E[rake all 実行]
    E --> F[bin/ host-bin/ のファイル列挙]
    D -->|Yes| F
    F --> G{除外フィルタに該当?}
    G -->|Yes| H[スキップ]
    G -->|No| I[install_D でコピー]
    H --> J{次のファイル?}
    I --> J
    J -->|Yes| G
    J -->|No| K[include/ lib/ のファイル列挙]
    K --> L{除外フィルタに該当?}
    L -->|Yes| M[スキップ]
    L -->|No| N[install_D でコピー]
    M --> O{次のファイル?}
    N --> O
    O -->|Yes| L
    O -->|No| P[rake install 完了]
```

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

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

本バッチはデータベース操作を行わない。ファイルシステム上のコピー操作のみ。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | 権限エラー | インストール先ディレクトリへの書き込み権限がない | `sudo rake install` で実行するか、DESTDIR/PREFIXを変更 |
| N/A | ビルドエラー | all タスクが失敗した場合 | ビルドエラーを解消してから再実行 |
| N/A | ディスク容量不足 | インストール先のディスク容量が不足 | ディスク容量を確保してから再実行 |

### リトライ仕様

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

### 障害時対応

インストールが途中で失敗した場合、既にコピーされたファイルはそのまま残る。`install_D` 関数は各ファイルのコピー前に既存ファイルを削除するため、再実行すれば上書きされる。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし（ファイル単位のコピー操作） |
| コミットタイミング | 各ファイルコピー完了時 |
| ロールバック条件 | なし（途中失敗時は部分インストール状態） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 数十〜数百ファイル |
| 目標処理時間 | 数秒以内 |
| メモリ使用量上限 | Ruby プロセスの標準的なメモリ使用量 |

## 排他制御

同一インストール先への同時実行は想定されていない。複数のユーザーが同時に同じインストール先に対してインストールを実行した場合、ファイルの競合が発生する可能性がある。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 進捗ログ | 各ファイルコピー時 | `INSTALL {src} -> {dst}` 形式でソースパスとインストール先パスを表示 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| N/A | N/A | N/A（手動実行タスクのため監視対象外） |

## 備考

- `rake install` は `install:full:host` のエイリアスであり、ホストビルドターゲットのみを対象とする
- 全ビルドターゲット（クロスビルド含む）をインストールする場合は `rake install:full` を使用する
- `libmruby_core.a` はデフォルトで `install_excludes` フィルタにより除外される
- `install_D` 関数は既存ファイルを削除してからコピーするため、冪等性がある
