# 画面設計書 16-koch zip

## 概要

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

### 本画面の処理概要

`koch zip`は、Nimコンパイラとツール群を含むインストール用ZIPパッケージを作成するCLIサブコマンドです。コンパイラ、標準ライブラリ、各種ツール（nimsuggest、nimpretty、nimble、atlas等）を一つのZIPアーカイブにまとめます。

**業務上の目的・背景**：Nimをユーザーに配布するためには、コンパイラと必要なファイルをパッケージ化する必要があります。`koch zip`は、Windows向けの配布パッケージを作成します。ZIPファイルは解凍するだけで使用開始でき、レジストリ変更などが不要なポータブルなインストール方法を提供します。

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

**主要な操作・処理内容**：
1. checksumsパッケージのバンドル
2. Nimbleのビルドとバンドル
3. Atlasのビルドとバンドル
4. nimsuggestのビルドとバンドル
5. nimprettyのビルドとバンドル
6. Windowsツール群のビルド（finish、vccexe、nimgrab、nimgrep、testament）
7. niminstを使用したスクリプト生成
8. niminstを使用したZIPパッケージ生成

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

**権限による表示制御**：特別な権限制御はありません。ファイルシステムへの書き込み権限が必要です。

## 関連機能

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

## 画面種別

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

## URL/ルーティング

```
koch zip [options]
```

コマンドラインオプション:
- `-d:release`: リリースビルド（推奨）
- `--latest`: 最新版の外部コンポーネント（Nimble、Atlas）を使用
- `--stable`: 安定版の外部コンポーネントを使用（デフォルト）
- 標準のNimコンパイラオプションがそのまま渡される

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| args | string | いいえ | Nimコンパイラに渡す追加オプション |
| --latest | flag | いいえ | 最新版コンポーネント使用フラグ |

### 出力項目

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

## 表示項目

| 項目名 | 説明 |
|--------|------|
| コンパイルコマンド | 各ツールのコンパイルコマンド |
| 生成進捗 | パッケージ生成の進捗 |

## イベント仕様

### 1-ZIPパッケージ生成開始

```
koch zip -d:release
```

1. `zip()`関数が呼び出される
2. 各種ツールのビルドとバンドル
3. niminstでインストールスクリプト生成
4. niminstでZIPパッケージ生成

### 2-最新版コンポーネント使用

```
koch zip -d:release --latest
```

1. NimbleとAtlasのHEAD版を使用
2. 他は同様の処理

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

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

### ファイル操作詳細

| 操作 | 対象ファイル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| クローン | dist/nimble | CREATE | Nimbleリポジトリ |
| クローン | dist/atlas | CREATE | Atlasリポジトリ |
| クローン | dist/checksums | CREATE | checksumsリポジトリ |
| ビルド | bin/* | CREATE/UPDATE | 各種ツールのビルド |
| 生成 | build/nim-{ver}.zip | CREATE | ZIPパッケージ |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| MSG001 | 情報 | Compile nimsuggest | nimsuggestのビルド開始 |
| MSG002 | 情報 | Compile nimble | Nimbleのビルド開始 |
| MSG003 | 情報 | niminst ... zip | ZIPパッケージ生成開始 |
| MSG004 | 成功 | (コマンド正常終了) | 生成完了 |

## 例外処理

| 例外 | 発生条件 | 対処 |
|------|---------|------|
| ネットワークエラー | 外部リポジトリへの接続失敗 | ネットワーク設定を確認 |
| コンパイルエラー | ツールのコンパイル失敗 | エラーを修正して再実行 |
| ディスク容量不足 | パッケージ出力先の容量不足 | ディスク空き容量を確保 |

## 備考

- ZIPパッケージは主にWindows向けの配布に使用
- Unix系では`koch xz`（tar.xz形式）を推奨
- `--latest`と`--stable`で外部コンポーネントのバージョンを切り替え可能

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | koch.nim | `koch.nim` | L53: VersionAsString定数 |
| 1-2 | koch.nim | `koch.nim` | L150-151: compileNimInst、distDir定数 |
| 1-3 | koch.nim | `koch.nim` | L14-17: NimbleStableCommit、AtlasStableCommit等 |

**読解のコツ**: 外部コンポーネントのバージョンはコミットハッシュで管理され、`--latest`でHEADを使用可能。

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

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

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

**主要処理フロー**:
1. **L227**: `bundleChecksums(latest)`でchecksumsをバンドル
2. **L228**: `bundleNimbleExe(latest, args)`でNimbleをビルド
3. **L229**: `bundleAtlasExe(latest, args)`でAtlasをビルド
4. **L230**: `bundleNimsuggest(args)`でnimsuggestをビルド
5. **L231**: `bundleNimpretty(args)`でnimprettyをビルド
6. **L232**: `bundleWinTools(args)`でWindowsツールをビルド
7. **L233-234**: niminstでスクリプト生成
8. **L235-236**: niminstでZIPパッケージ生成

#### Step 3: ツールバンドル処理を理解する

各ツールのビルド処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | koch.nim | `koch.nim` | bundleWinTools関数（L214-224）: Windowsツール群のビルド |
| 3-2 | koch.nim | `koch.nim` | bundleNimbleExe関数（L163-172）: Nimbleのビルド |
| 3-3 | koch.nim | `koch.nim` | bundleAtlasExe関数（L174-182）: Atlasのビルド |

**主要処理フロー**:
- **L215**: `nimCompile("tools/finish.nim")`でfinishツールをビルド
- **L217**: `buildVccTool(args)`でvccexeをビルド
- **L218**: `nimCompile("tools/nimgrab.nim")`でnimgrabをビルド
- **L219**: `nimCompile("tools/nimgrep.nim")`でnimgrepをビルド
- **L220**: `nimCompile("testament/testament.nim")`でtestamentをビルド

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

```
koch zip -d:release
    │
    └─ zip(latest, args)
           │
           ├─ bundleChecksums(latest)      # checksumsバンドル
           │
           ├─ bundleNimbleExe(latest, args) # Nimbleビルド
           │      ├─ cloneDependency()
           │      └─ nimCompile()
           │
           ├─ bundleAtlasExe(latest, args)  # Atlasビルド
           │      ├─ cloneDependency()
           │      └─ nimCompile()
           │
           ├─ bundleNimsuggest(args)        # nimsuggestビルド
           │
           ├─ bundleNimpretty(args)         # nimprettyビルド
           │
           ├─ bundleWinTools(args)          # Windowsツールビルド
           │      ├─ nimCompile("finish")
           │      ├─ buildVccTool()
           │      ├─ nimCompile("nimgrab")
           │      ├─ nimCompile("nimgrep")
           │      └─ nimCompile("testament")
           │
           ├─ nimexec("cc -r niminst ... scripts ...")
           │      └─ インストールスクリプト生成
           │
           └─ exec("niminst ... zip ...")
                  └─ build/nim-{version}.zip 生成
```

### データフロー図

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

--latest/--stable ────────▶ latestフラグ設定 ───────────▶ コミットハッシュ選択

GitHub/nimble ────────────▶ bundleNimbleExe() ──────────▶ bin/nimble

GitHub/atlas ─────────────▶ bundleAtlasExe() ───────────▶ bin/atlas

nimsuggest/nimsuggest.nim ─▶ bundleNimsuggest() ────────▶ bin/nimsuggest

tools/finish.nim ─────────▶ bundleWinTools() ───────────▶ bin/finish, bin/nimgrep, ...

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

bin/* + lib/* ────────────▶ niminst zip ────────────────▶ build/nim-{version}.zip
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| koch.nim | `koch.nim` | ソース | zipコマンドの実装 |
| niminst.nim | `tools/niminst/niminst.nim` | ソース | パッケージ生成ツール |
| installer.ini | `compiler/installer.ini` | 設定 | パッケージ構成設定 |
| finish.nim | `tools/finish.nim` | ソース | インストール完了処理ツール |
| nimgrab.nim | `tools/nimgrab.nim` | ソース | ファイルダウンロードツール |
| nimgrep.nim | `tools/nimgrep.nim` | ソース | 検索・置換ツール |
| deps.nim | `tools/deps.nim` | ソース | 外部依存関係のクローン処理 |
