# 機能設計書 85-require_tool.sh

## 概要

本ドキュメントは、指定されたツールのバージョンが要件を満たしているか確認する`require_tool.sh`ユーティリティの機能設計について記述する。

### 本機能の処理概要

指定されたプログラムが存在し、そのバージョンが最小要件バージョン以上であるかを検証するユーティリティスクリプトである。バージョン比較にはstrverscmpアルゴリズムを使用する。

**業務上の目的・背景**：ビルドシステムやスクリプトにおいて、特定のツールの特定バージョン以上が必要な場合がある。手動でのバージョン確認は煩雑であり、自動化された検証機能が必要となる。このユーティリティにより、依存ツールのバージョン要件を簡潔にチェックできる。

**機能の利用シーン**：Makefileやシェルスクリプト内で、特定のコンパイラ（gcc、clang等）やツール（emacs、zsh等）のバージョン要件を確認する際に使用する。環境変数でツールパスを上書きすることも可能。

**主要な処理内容**：
1. 環境変数による代替パスの確認
2. ツールの--versionオプション実行
3. 出力からバージョン番号の抽出
4. strverscmpアルゴリズムによるバージョン比較
5. 結果に応じた終了ステータスの返却

**関連システム・外部連携**：検査対象のツール（gcc、zsh、emacs等）のコマンドを実行する。

**権限による制御**：検査対象ツールの実行権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 23 | require_tool.sh | 主画面 | 必要なツールがインストールされているか確認するユーティリティ |

## 機能種別

バリデーション / ユーティリティ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| TOOL | 文字列 | Yes | 確認するツール名またはパス | - |
| MIN_VERSION | 文字列 | Yes | 最小要件バージョン | - |
| -h, --help | フラグ | No | ヘルプメッセージを表示 | - |

### 入力データソース

- コマンドライン引数
- 環境変数（ツール名を大文字にした変数、例: GCC、ZSH）
- ツールの--version出力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 標準エラー出力 | 文字列 | エラーメッセージ（バージョン不足時） |
| 終了ステータス | 整数 | 0: 要件を満たす、1: 要件を満たさない |

### 出力先

- 標準エラー出力：エラーメッセージ
- 終了ステータス：検証結果

## 処理フロー

### 処理シーケンス

```
1. ヘルプオプションの確認
   └─ -h/--helpの場合はヘルプを表示して終了
2. 引数数の確認
   └─ 2引数でない場合はエラー
3. 環境変数の確認
   └─ ツール名大文字の環境変数があればそれを使用
4. バージョン取得
   └─ ツール --version を実行
5. バージョン抽出
   └─ sedでバージョン番号を抽出
6. バージョン比較
   └─ strverscmpアルゴリズムで比較
7. 結果返却
   └─ 比較結果に応じた終了ステータス
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{-h/--help?}
    B -->|Yes| C[ヘルプ表示]
    C --> D[終了 0]
    B -->|No| E{引数2個?}
    E -->|No| F[エラーメッセージ]
    F --> G[終了 1]
    E -->|Yes| H[require_tool関数呼び出し]
    H --> I[環境変数確認]
    I --> J[TOOL --version実行]
    J --> K{バージョン取得成功?}
    K -->|No| L[ツール必要メッセージ]
    L --> G
    K -->|Yes| M[バージョン比較]
    M --> N{要件以上?}
    N -->|Yes| D
    N -->|No| O[バージョン不足メッセージ]
    O --> G
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-85-001 | 環境変数優先 | 大文字のツール名環境変数があればそちらを使用 | CC=g++等が設定されている場合 |
| BR-85-002 | strverscmp比較 | バージョン比較はstrverscmpアルゴリズムを使用 | 常時 |
| BR-85-003 | 7th edition Unix互換 | awkは1978年版Unixのawkと互換性のある機能のみ使用 | 常時 |

### 計算ロジック

バージョン比較（strverscmp）:
- 数字部分は数値として比較
- 先頭0がある数字は小数として扱う
- 文字部分は辞書順比較

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | ツール不在 | ツールが見つからない | エラーメッセージを標準エラーに出力 |
| 1 | バージョン不足 | バージョンが要件未満 | エラーメッセージを標準エラーに出力 |
| 1 | 引数エラー | 引数が2個でない | エラーメッセージを表示 |

### リトライ仕様

リトライは行わない。

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

トランザクション管理なし。

## パフォーマンス要件

特になし。検証ツールとして瞬時に実行されることを想定。

## セキュリティ考慮事項

- 任意のコマンドを--versionオプション付きで実行する
- 入力パラメータの検証は行わないため、信頼できる入力のみを渡すこと

## 備考

- awk_strverscmpはSolaris等の古いawkとも互換性を持つよう設計されている
- バージョン番号はX.Y.Z形式を想定（例: 4.6, 5.0.3）

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: メイン処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | require_tool.sh | `tools/require_tool.sh` | 148-162行目: メイン処理（引数解析と関数呼び出し） |

**読解のコツ**: POSIX sh互換のスクリプト。

**主要処理フロー**:
1. **148-155行目**: -h/--helpオプションの処理
2. **156-159行目**: 引数数の検証
3. **161行目**: require_tool関数の呼び出し

#### Step 2: require_tool関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | require_tool.sh | `tools/require_tool.sh` | 87-103行目: require_tool関数 |

**主要処理フロー**:
- **89行目**: ツール名を大文字に変換（環境変数参照用）
- **90行目**: 環境変数からツールパスを取得、なければツール名をそのまま使用
- **91-92行目**: --versionを実行してバージョンを抽出
- **93-96行目**: バージョン取得失敗時のエラー処理
- **97-102行目**: バージョン比較と結果処理

#### Step 3: バージョン比較アルゴリズムを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | require_tool.sh | `tools/require_tool.sh` | 1-71行目: __require_tool_version_compare関数 |

**主要処理フロー**:
- **8-63行目**: awkによるstrverscmpアルゴリズムの実装
- **16-53行目**: 数字部分の比較ロジック
- **23-39行目**: 小数（先頭0）の特別処理
- **54-58行目**: 文字部分の比較
- **64行目**: awkスクリプトの実行
- **65-69行目**: 終了ステータスに基づく結果出力

### プログラム呼び出し階層図

```
require_tool.sh
    │
    ├─ usage()
    │
    └─ require_tool()
           │
           ├─ $tool --version (外部コマンド)
           │
           └─ __require_tool_version_compare()
                  │
                  └─ awk (strverscmpアルゴリズム)
```

### データフロー図

```
[入力]                    [処理]                        [出力]

TOOL引数 ────────────┐
                     │
MIN_VERSION引数 ─────┼─▶ require_tool.sh ─────────────▶ 終了ステータス
                     │         │                        (0: OK, 1: NG)
環境変数 ────────────┘         │
                               ├─▶ 標準エラー出力
$tool --version出力 ──────────▶│   (エラーメッセージ)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| require_tool.sh | `tools/require_tool.sh` | ソース | ツールバージョン検証のメインスクリプト |
