# 帳票設計書 1-version

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータの `version` コマンドが出力するバージョン情報レポートの設計書です。

### 本帳票の処理概要

`version` コマンドは、Ghosttyのビルド情報とランタイム環境の詳細を標準出力に表示するCLIレポートです。

**業務上の目的・背景**：ユーザーやサポート担当者がGhosttyのバージョン、ビルド設定、依存ライブラリの状態を確認し、問題の切り分けや互換性の確認を行うために必要です。特にバグ報告時やアップデート確認時に不可欠な情報を提供します。

**帳票の利用シーン**：
- ユーザーが現在インストールされているGhosttyのバージョンを確認したい場合
- サポートチームがユーザー環境の詳細情報を収集する場合
- ビルド設定の違いによる動作差異を調査する場合
- アップデート前後のバージョン比較を行う場合

**主要な出力内容**：
1. Ghosttyのバージョン番号（セマンティックバージョン形式）
2. リリースチャンネル（stable/beta/tip等）
3. Zigコンパイラのバージョン
4. ビルドモード（Debug/ReleaseFast等）
5. アプリケーションランタイム種別
6. フォントエンジン種別
7. レンダラー種別
8. libxevバックエンド
9. GTKランタイム時：カーネルバージョン、デスクトップ環境、GTK/libadwaitaバージョン、X11/Wayland有効状態

**帳票の出力タイミング**：`ghostty +version` または `ghostty --version` コマンド実行時

**帳票の利用者**：エンドユーザー、システム管理者、サポートチーム、開発者

## 帳票種別

CLIレポート（テキスト形式）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | CLI | `ghostty +version` | コマンド実行 |
| - | CLI | `ghostty --version` | コマンド実行 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | テキスト（stdout） |
| 用紙サイズ | N/A |
| 向き | N/A |
| ファイル名 | N/A（標準出力） |
| 出力方法 | 標準出力への表示 |
| 文字コード | UTF-8 |

### 端末出力固有設定

| 項目 | 内容 |
|-----|------|
| ハイパーリンク | 有（TTY時、GitHubコミットへのOSCリンク） |
| カラー出力 | 無 |
| インタラクティブ | 無 |

## 帳票レイアウト

### レイアウト概要

バージョン情報は階層的なテキスト形式で出力されます。

```
┌─────────────────────────────────────┐
│      タイトル（Ghostty バージョン）    │
├─────────────────────────────────────┤
│      Version セクション              │
├─────────────────────────────────────┤
│      Build Config セクション         │
├─────────────────────────────────────┤
│      GTK固有情報（条件付き）          │
└─────────────────────────────────────┘
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | タイトル | Ghosttyバージョン文字列 | build_config.version_string | "Ghostty {version}\n\n" |

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 備考 |
|----|-------|------|-------------|---------|------|
| 1 | version | バージョン番号 | build_config.version_string | "  - version: {s}" | |
| 2 | channel | リリースチャンネル | build_config.release_channel | "  - channel: {t}" | |
| 3 | Zig version | Zigコンパイラバージョン | builtin.zig_version_string | "  - Zig version   : {s}" | |
| 4 | build mode | ビルドモード | builtin.mode | "  - build mode    : {}" | |
| 5 | app runtime | アプリランタイム | build_config.app_runtime | "  - app runtime   : {}" | |
| 6 | font engine | フォントエンジン | build_config.font_backend | "  - font engine   : {}" | |
| 7 | renderer | レンダラー | renderer.Renderer | "  - renderer      : {}" | |
| 8 | libxev | イベントループバックエンド | xev.backend | "  - libxev        : {t}" | |
| 9 | kernel version | カーネルバージョン | internal_os.getKernelInfo | "  - kernel version: {s}" | GTK+Linux時のみ |
| 10 | desktop env | デスクトップ環境 | internal_os.desktopEnvironment | "  - desktop env   : {t}" | GTK時のみ |
| 11 | GTK version build | GTKビルドバージョン | gtk_version.comptime_version | "    build         : {f}" | GTK時のみ |
| 12 | GTK version runtime | GTKランタイムバージョン | gtk_version.getRuntimeVersion | "    runtime       : {f}" | GTK時のみ |
| 13 | libadwaita build | libadwaitaビルドバージョン | adw_version.comptime_version | "    build         : {f}" | GTK時のみ |
| 14 | libadwaita runtime | libadwaitaランタイムバージョン | adw_version.getRuntimeVersion | "    runtime       : {f}" | GTK時のみ |
| 15 | libX11 | X11有効状態 | build_options.x11 | "  - libX11        : enabled/disabled" | GTK時のみ |
| 16 | libwayland | Wayland有効状態 | build_options.wayland | "  - libwayland    : enabled/disabled" | GTK時のみ |

### フッター部

フッターはありません。

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| なし | 条件なしで全情報を出力 | - |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| - | 固定順序 | - |

### 改ページ条件

改ページなし（単一ページ出力）

## データベース参照仕様

### 参照テーブル一覧

データベース参照はありません。コンパイル時定数とランタイム情報を使用します。

### データ取得元詳細

| 取得元 | 用途 | 取得方法 |
|-------|------|---------|
| build_config | ビルド時設定 | コンパイル時定数 |
| builtin | Zigコンパイラ情報 | コンパイル時定数 |
| build_options | ビルドオプション | コンパイル時定数 |
| internal_os | OS情報 | ランタイム関数呼び出し |
| gtk_version | GTKバージョン | ランタイム関数呼び出し |
| adw_version | libadwaitaバージョン | ランタイム関数呼び出し |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| なし | - | - | 計算処理なし |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[コマンド実行] --> B[stdoutバッファ初期化]
    B --> C[TTY判定]
    C --> D{TTYか?}
    D -->|Yes| E[GitHubリンク付きタイトル出力]
    D -->|No| F[プレーンタイトル出力]
    E --> G[Versionセクション出力]
    F --> G
    G --> H[Build Configセクション出力]
    H --> I{GTKランタイム?}
    I -->|Yes| J[GTK固有情報出力]
    I -->|No| K[バッファフラッシュ]
    J --> K
    K --> L[終了コード0を返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 出力失敗 | stdoutへの書き込みエラー | なし（エラー返却） | プロセス終了 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 1件（単一レポート） |
| 目標出力時間 | 即時（1秒未満） |
| 同時出力数上限 | N/A |

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

- 機密情報は含まれない
- ビルド情報はバイナリに埋め込まれた公開情報
- カーネル情報等はOS標準APIから取得

## 備考

- TTY出力時はOSC 8ハイパーリンクでGitHubコミットへリンク
- `--version`は他の引数に関わらず常にバージョンを出力

---

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

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

### 推奨読解順序

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

バージョン情報の元となるビルド設定定数を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | build_config.zig | `src/build_config.zig` | version, version_string, release_channel等のコンパイル時定数 |
| 1-2 | build_options | ビルド時生成 | x11, wayland, flatpak等のビルドオプション |

**読解のコツ**: build_configはビルド時に決定される定数を集約しています。`pub const`で始まる定義がすべて出力対象です。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ghostty.zig | `src/cli/ghostty.zig` | Action enumのversion定義とrun関数のディスパッチ（134行目） |
| 2-2 | version.zig | `src/cli/version.zig` | run関数がエントリーポイント（17行目） |

**主要処理フロー**:
1. **17行目**: `pub fn run(alloc: Allocator) !u8` - メイン処理開始
2. **18-23行目**: stdoutバッファとwriter初期化
3. **25-32行目**: TTY判定とハイパーリンク出力
4. **34-44行目**: Version/Build Configセクション出力
5. **45-71行目**: GTK固有情報の条件付き出力
6. **74行目**: バッファフラッシュ

#### Step 3: GTK固有情報の取得を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | gtk_version.zig | `src/apprt/gtk/gtk_version.zig` | GTKバージョン取得ロジック |
| 3-2 | adw_version.zig | `src/apprt/gtk/adw_version.zig` | libadwaitaバージョン取得ロジック |

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

```
ghostty (main)
    │
    └─ Action.run (ghostty.zig:99)
           │
           └─ version.run (version.zig:17)
                  │
                  ├─ build_config.version_string (コンパイル時定数)
                  ├─ build_config.release_channel (コンパイル時定数)
                  ├─ builtin.zig_version_string (コンパイル時定数)
                  ├─ builtin.mode (コンパイル時定数)
                  ├─ internal_os.getKernelInfo (ランタイム呼び出し)
                  ├─ internal_os.desktopEnvironment (ランタイム呼び出し)
                  ├─ gtk_version.getRuntimeVersion (ランタイム呼び出し)
                  └─ adw_version.getRuntimeVersion (ランタイム呼び出し)
```

### データフロー図

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

コマンド引数 ───▶ Action検出 ───▶ stdout
                      │
                      ▼
              version.run()
                      │
    ┌─────────────────┼─────────────────┐
    ▼                 ▼                 ▼
build_config    internal_os      gtk_version
(コンパイル時)   (ランタイム)      (ランタイム)
    │                 │                 │
    └─────────────────┼─────────────────┘
                      │
                      ▼
                  stdout出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| version.zig | `src/cli/version.zig` | ソース | メイン処理 |
| ghostty.zig | `src/cli/ghostty.zig` | ソース | Actionディスパッチャー |
| build_config.zig | `src/build_config.zig` | ソース | ビルド時設定定数 |
| gtk_version.zig | `src/apprt/gtk/gtk_version.zig` | ソース | GTKバージョン取得 |
| adw_version.zig | `src/apprt/gtk/adw_version.zig` | ソース | libadwaitaバージョン取得 |
| main.zig | `src/os/main.zig` | ソース | OS情報取得 |
