# 機能設計書 180-バージョン情報取得

## 概要

本ドキュメントは、libuv の `uv_version()` / `uv_version_string()` 関数によるlibuvのバージョン情報取得機能について、その設計仕様を記載する。

### 本機能の処理概要

`uv_version()` はlibuvのバージョンを16進数エンコードされた整数値として返し、`uv_version_string()` はバージョン文字列（例: "1.52.1"）を返す関数である。

**業務上の目的・背景**：アプリケーションが使用しているlibuvのバージョンを実行時に確認することは、互換性チェック、デバッグ情報の出力、機能の有無判定などに重要である。ヘッダーファイルのマクロ（コンパイル時バージョン）とは別に、リンクされている実際のライブラリのバージョンを実行時に取得できることにより、バージョンミスマッチの検出が可能になる。

**機能の利用シーン**：アプリケーション起動時のバージョンログ出力、動的リンクされたlibuvのバージョン確認、API互換性チェック、バグレポートへのバージョン情報付与、Webページでのバージョン表記などに利用される。

**主要な処理内容**：
1. `uv_version()`: UV_VERSION_HEX マクロの値をそのまま返す
2. `uv_version_string()`: コンパイル時に生成されたバージョン文字列リテラルを返す

**関連システム・外部連携**：なし。コンパイル時定数のみ使用。

**権限による制御**：特別な権限は不要である。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | トップページ | 補助機能 | トップページでのlibuvバージョン表記に関連 |
| 5 | バージョン情報 | 主機能 | uv_version()/uv_version_string()によるバージョン番号・文字列取得のAPI定義 |

## 機能種別

データ取得処理（コンパイル時定数の返却）

## 入力仕様

### 入力パラメータ

#### uv_version()

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| (なし) | void | - | パラメータなし | - |

#### uv_version_string()

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| (なし) | void | - | パラメータなし | - |

### 入力データソース

コンパイル時のマクロ定数（include/uv/version.h で定義）。

## 出力仕様

### 出力データ

#### uv_version()

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | unsigned int | バージョンの16進数エンコード値。(MAJOR << 16) \| (MINOR << 8) \| PATCH |

#### uv_version_string()

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | const char* | バージョン文字列。リリース版: "MAJOR.MINOR.PATCH"、開発版: "MAJOR.MINOR.PATCH-SUFFIX" |

### 出力先

呼び出し元に戻り値として返却。

## 処理フロー

### 処理シーケンス

```
1. [uv_version]
   └─ UV_VERSION_HEX マクロ値を返す

2. [uv_version_string]
   └─ UV_VERSION_STRING マクロ値（文字列リテラル）を返す
```

### フローチャート

```mermaid
flowchart TD
    A[uv_version 呼出] --> B[UV_VERSION_HEX を返す]
    C[uv_version_string 呼出] --> D[UV_VERSION_STRING を返す]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-180-01 | HEXエンコード形式 | バージョンは (MAJOR << 16) \| (MINOR << 8) \| PATCH 形式でエンコード | uv_version() |
| BR-180-02 | リリース版文字列 | UV_VERSION_IS_RELEASE が 1 の場合、"MAJOR.MINOR.PATCH" 形式 | リリースビルド |
| BR-180-03 | 開発版文字列 | UV_VERSION_IS_RELEASE が 0 の場合、"MAJOR.MINOR.PATCH-SUFFIX" 形式（例: "1.52.1-dev"） | 開発ビルド |

### 計算ロジック

バージョンHEX計算（include/uv/version.h L39-41）:
```c
#define UV_VERSION_HEX  ((UV_VERSION_MAJOR << 16) | \
                         (UV_VERSION_MINOR <<  8) | \
                         (UV_VERSION_PATCH))
```

現在のバージョン値（include/uv/version.h L33-37）:
- UV_VERSION_MAJOR = 1
- UV_VERSION_MINOR = 52
- UV_VERSION_PATCH = 1
- UV_VERSION_IS_RELEASE = 0
- UV_VERSION_SUFFIX = "dev"

バージョン文字列の構成（src/version.c L27-35）:
```c
#define UV_VERSION_STRING_BASE  "1" "." "52" "." "1"
// UV_VERSION_IS_RELEASE == 0 の場合:
#define UV_VERSION_STRING  UV_VERSION_STRING_BASE "-" UV_VERSION_SUFFIX
// 結果: "1.52.1-dev"
```

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

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

該当なし。

### テーブル別操作詳細

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| (なし) | - | 本関数はエラーを返さない | - |

### リトライ仕様

不要。

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

該当なし。

## パフォーマンス要件

コンパイル時定数をそのまま返すため、極めて軽量。ナノ秒オーダーで完了する。

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

特別なセキュリティ要件はない。

## 備考

- バージョン定数はヘッダーファイル `include/uv/version.h` で一元管理されている。
- ヘッダーのバージョンマクロ（コンパイル時）とライブラリのバージョン関数（実行時）を比較することで、ヘッダーとライブラリのバージョンミスマッチを検出できる。
- ABI互換性はメジャーバージョンが同じ間は保証される。APIはマイナーバージョン間で後方互換性を保って進化する（version.h のコメントに記載）。
- configure.ac の `-soname` ディレクティブは MAJOR / MINOR の変更時に更新する必要がある（PATCH は不要）。

---

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

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

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | version.h | `include/uv/version.h` | バージョン定数マクロの定義（33-41行目）。MAJOR, MINOR, PATCH, IS_RELEASE, SUFFIX, VERSION_HEX |

**読解のコツ**: `UV_VERSION_HEX` はビットシフトで3つのバージョン番号を1つの整数に詰め込む。MAJOR が上位16ビット、MINOR が中位8ビット、PATCH が下位8ビットに配置される。例: v1.52.1 = 0x013401。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv.h | `include/uv.h` | API宣言（275-276行目）: `uv_version()` と `uv_version_string()` |

**主要処理フロー**:
1. **275行目**: `unsigned int uv_version(void)` - 整数版バージョン
2. **276行目**: `const char* uv_version_string(void)` - 文字列版バージョン

#### Step 3: 実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | version.c | `src/version.c` | uv_version() と uv_version_string() の実装（全46行） |

**主要処理フロー**:
- **24-25行目**: `UV_STRINGIFY` ヘルパーマクロ。数値マクロを文字列リテラルに変換
- **27-29行目**: `UV_VERSION_STRING_BASE` マクロ。"MAJOR.MINOR.PATCH" 形式の文字列を生成
- **31-35行目**: `UV_VERSION_STRING` マクロ。リリース版/開発版で文字列を分岐
- **38-40行目**: `uv_version()` 関数。`UV_VERSION_HEX` を返す1行実装
- **43-45行目**: `uv_version_string()` 関数。`UV_VERSION_STRING` を返す1行実装

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

```
uv_version()
    +-- return UV_VERSION_HEX
        +-- (UV_VERSION_MAJOR << 16) | (UV_VERSION_MINOR << 8) | UV_VERSION_PATCH

uv_version_string()
    +-- return UV_VERSION_STRING
        +-- [IS_RELEASE=1] "MAJOR.MINOR.PATCH"
        +-- [IS_RELEASE=0] "MAJOR.MINOR.PATCH-SUFFIX"
```

### データフロー図

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

(なし) ──▶ uv_version() ──────────────▶ unsigned int
               +-- UV_VERSION_HEX マクロ展開       (例: 0x013401)

(なし) ──▶ uv_version_string() ───────▶ const char*
               +-- UV_VERSION_STRING マクロ展開     (例: "1.52.1-dev")
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダー | API宣言 |
| version.h | `include/uv/version.h` | ヘッダー | バージョン定数マクロの定義 |
| version.c | `src/version.c` | ソース | uv_version()、uv_version_string() の実装 |
