# 画面設計書 17-koch xz

## 概要

本ドキュメントは、Nimコンパイラプロジェクトにおける`koch xz`サブコマンドの画面設計書です。インストール用tar.xzパッケージを作成する処理について説明します。

### 本画面の処理概要

`koch xz`は、Nimコンパイラとツール群を含むインストール用tar.xzパッケージを作成するCLIサブコマンドです。主にUnix系システム（Linux、macOS、BSD等）向けの配布パッケージを生成します。

**業務上の目的・背景**：Unix系システムでは、tar.xz形式のアーカイブが標準的な配布形式です。`koch xz`は、ソースコード、標準ライブラリ、ビルドスクリプトを含むパッケージを作成します。生成されたパッケージは、解凍後に`build.sh`を実行することでNimコンパイラをビルドできます。また、Gitリポジトリがクリーンな状態であることを確認してからパッケージを生成することで、不要なファイルが含まれることを防ぎます。

**画面へのアクセス方法**：ターミナルから以下のコマンドを実行します。
```
koch xz
```

**主要な操作・処理内容**：
1. Gitリポジトリのクリーン状態チェック
2. niminstを使用したインストールスクリプト生成
3. niminstを使用したtar.xzパッケージ生成
4. バージョン情報の埋め込み

**画面遷移**：
- 遷移元: kochメイン画面（No.10）からサブコマンドとして呼び出し
- 遷移先: なし（tar.xzパッケージ生成完了後は自動的に終了）
- 関連: niminst（No.34）が内部で使用される

**権限による表示制御**：特別な権限制御はありません。Gitリポジトリと書き込み権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 24 | 配布パッケージ作成 | 主機能 | tar.xz形式のインストールパッケージ作成 |
| 30 | Niminst | 補助機能 | niminstツールを使用したパッケージ生成 |

## 画面種別

CLIコマンド実行画面（バッチ処理型）

## URL/ルーティング

```
koch xz [options]
```

コマンドラインオプション:
- `--latest`: 最新版の外部コンポーネントを使用（現在は未使用）
- `--stable`: 安定版の外部コンポーネントを使用（デフォルト、現在は未使用）
- 標準のNimコンパイラオプションがそのまま渡される

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| args | string | いいえ | Nimコンパイラに渡す追加オプション |

### 出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| build/nim-{version}.tar.xz | file | 生成されたtar.xzパッケージ |

## 表示項目

| 項目名 | 説明 |
|--------|------|
| コンパイルコマンド | niminstのコンパイルコマンド |
| 生成進捗 | パッケージ生成の進捗 |
| エラーメッセージ | Gitリポジトリがクリーンでない場合のエラー |

## イベント仕様

### 1-tar.xzパッケージ生成開始

```
koch xz
```

1. `xz()`関数が呼び出される
2. `ensureCleanGit()`でGitリポジトリのクリーン状態を確認
3. niminstでインストールスクリプト生成
4. niminstでtar.xzパッケージ生成

### 2-Gitリポジトリがクリーンでない場合

```
koch xz
# エラー: Not a clean git repository
```

1. `git diff`が空でない場合、エラー終了
2. パッケージは生成されない

## データベース更新仕様

本コマンドはデータベースを使用しません。

### ファイル操作詳細

| 操作 | 対象ファイル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ビルド | tools/niminst/niminst | CREATE/UPDATE | niminstのコンパイル |
| 生成 | build/nim-{ver}.tar.xz | CREATE | tar.xzパッケージ |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| MSG001 | エラー | Not a clean git repository; 'git diff' not empty! | git diffが空でない |
| MSG002 | エラー | Not a clean git repository; 'git diff' returned non-zero! | git diffがエラー |
| MSG003 | 情報 | nim cc -r niminst ... scripts | スクリプト生成開始 |
| MSG004 | 情報 | niminst ... xz | tar.xzパッケージ生成開始 |

## 例外処理

| 例外 | 発生条件 | 対処 |
|------|---------|------|
| Gitリポジトリ未クリーン | 未コミットの変更がある | `git commit`または`git stash`で変更を処理 |
| コンパイルエラー | niminstのコンパイル失敗 | エラーを修正して再実行 |
| ディスク容量不足 | パッケージ出力先の容量不足 | ディスク空き容量を確保 |

## 備考

- tar.xzパッケージは主にUnix系システム向けの配布に使用
- Gitリポジトリがクリーンな状態でのみ実行可能
- `koch zip`と異なり、ビルド済みバイナリではなくソースとビルドスクリプトを含む

---

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

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

### 推奨読解順序

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

tar.xzパッケージ生成で使用される定数を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | koch.nim | `koch.nim` | L53: VersionAsString定数 |
| 1-2 | koch.nim | `koch.nim` | L150-151: compileNimInst定数 |

**読解のコツ**: xzコマンドはzipコマンドと異なり、ビルド済みバイナリではなくソースを含むため、処理がシンプルです。

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

xzコマンドの呼び出し処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | koch.nim | `koch.nim` | L754: "xz"コマンドの処理 |
| 2-2 | koch.nim | `koch.nim` | xz関数（L245-250）: tar.xzパッケージ生成のメインロジック |

**主要処理フロー**:
1. **L246**: `ensureCleanGit()`でGitリポジトリのクリーン状態を確認
2. **L247-248**: niminstでスクリプト生成（scripts）
3. **L249-250**: niminstでtar.xzパッケージ生成（xz）

#### Step 3: Gitクリーンチェックを理解する

ensureCleanGit関数を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | koch.nim | `koch.nim` | ensureCleanGit関数（L238-243）: Gitリポジトリのクリーン状態チェック |

**主要処理フロー**:
- **L239**: `osproc.execCmdEx("git diff")`でdiffを取得
- **L240-241**: 出力が空でない場合、エラー終了
- **L242-243**: 終了コードが0でない場合、エラー終了

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

```
koch xz
    │
    └─ xz(latest, args)
           │
           ├─ ensureCleanGit()                    # Gitクリーンチェック
           │      │
           │      └─ osproc.execCmdEx("git diff")
           │             │
           │             ├─ [成功] 続行
           │             └─ [失敗] quit("Not a clean git repository")
           │
           ├─ nimexec("cc -r niminst ... scripts ...")
           │      │
           │      ├─ nim cc tools/niminst/niminst
           │      │      └─ niminst.exe をビルド
           │      │
           │      └─ niminst scripts compiler/installer.ini
           │             └─ インストールスクリプト生成
           │
           └─ exec("niminst ... xz ...")
                  │
                  └─ build/nim-{version}.tar.xz 生成
```

### データフロー図

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

git diff ─────────────────▶ ensureCleanGit() ───────────▶ クリーン状態確認

tools/niminst/niminst.nim ─▶ nim cc -r ─────────────────▶ niminst.exe

compiler/installer.ini ───▶ niminst scripts ────────────▶ install.sh, build.sh

VersionAsString ──────────▶ --var:version ──────────────▶ バージョン埋め込み

ソースファイル群 ─────────▶ niminst xz ─────────────────▶ build/nim-{version}.tar.xz
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| koch.nim | `koch.nim` | ソース | xzコマンドの実装 |
| niminst.nim | `tools/niminst/niminst.nim` | ソース | パッケージ生成ツール |
| installer.ini | `compiler/installer.ini` | 設定 | パッケージ構成設定 |
| kochdocs.nim | `tools/kochdocs.nim` | ソース | nimexec、exec関数の定義 |
