# 画面設計書 19-koch atlas

## 概要

本ドキュメントは、Nimコンパイラプロジェクトにおける`koch atlas`サブコマンドの画面設計書です。Atlas依存関係管理ツールをビルドする処理について説明します。

### 本画面の処理概要

`koch atlas`は、Nimプロジェクトの依存関係管理ツールであるAtlasをビルドするCLIサブコマンドです。GitHubからAtlasのソースコードをクローンし、コンパイルして`bin/atlas`を生成します。

**業務上の目的・背景**：AtlasはNimbleの代替/補完として開発された依存関係管理ツールです。Nimbleがパッケージマネージャとしての機能を提供するのに対し、Atlasは依存関係のロックファイル管理やモノレポ対応など、より詳細な依存関係制御を提供します。`koch atlas`は、Atlasを最新のコンパイラでビルドし、開発環境に統合するために使用されます。

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

**主要な操作・処理内容**：
1. GitHubからAtlasリポジトリをクローン
2. 依存関係（sat）のクローン
3. Atlasソースコードのコンパイル
4. bin/atlasへの出力

**画面遷移**：
- 遷移元: kochメイン画面（No.10）からサブコマンドとして呼び出し
- 遷移先: なし（Atlasビルド完了後は自動的に終了）
- 関連: koch tools（No.12）からも呼び出される

**権限による表示制御**：特別な権限制御はありません。ネットワーク接続と書き込み権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 20 | Koch | 主機能 | Atlasツールのビルド処理 |

## 画面種別

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

## URL/ルーティング

```
koch atlas [options]
```

コマンドラインオプション:
- `--latest`: 最新版（HEAD）のAtlasを使用
- `--stable`: 安定版（AtlasStableCommit）を使用（デフォルト）
- 標準のNimコンパイラオプションがそのまま渡される

## 入出力項目

### 入力項目

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

### 出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| bin/atlas | executable | 生成されたAtlas依存関係管理ツール |
| dist/atlas/ | directory | Atlasソースコード |
| dist/atlas/dist/sat/ | directory | sat依存関係 |

## 表示項目

| 項目名 | 説明 |
|--------|------|
| クローンコマンド | git cloneコマンド |
| コンパイルコマンド | Atlasのコンパイルコマンド |

## イベント仕様

### 1-Atlasビルド開始

```
koch atlas
```

1. `bundleAtlasExe()`関数が呼び出される
2. AtlasStableCommitでリポジトリをクローン
3. sat依存関係をクローン
4. Atlasをコンパイル

### 2-最新版Atlasビルド

```
koch atlas --latest
```

1. latestフラグがtrueで関数呼び出し
2. HEADコミットでリポジトリをクローン
3. 他は同様の処理

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

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

### ファイル操作詳細

| 操作 | 対象ファイル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| クローン | dist/atlas | CREATE | Atlasリポジトリ |
| クローン | dist/atlas/dist/sat | CREATE | sat依存関係 |
| ビルド | bin/atlas | CREATE/UPDATE | Atlas実行ファイル |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| MSG001 | 情報 | git clone ... atlas.git | リポジトリクローン開始 |
| MSG002 | 情報 | git clone ... sat.git | sat依存関係クローン開始 |
| MSG003 | 情報 | nim c -d:release ... atlas.nim | Atlasコンパイル開始 |
| MSG004 | 成功 | (コマンド正常終了) | ビルド完了 |

## 例外処理

| 例外 | 発生条件 | 対処 |
|------|---------|------|
| ネットワークエラー | GitHubへの接続失敗 | ネットワーク設定を確認 |
| コンパイルエラー | Atlasソースにエラーがある | Atlasリポジトリの問題を報告 |
| 権限エラー | dist/またはbin/への書き込み権限がない | 権限を設定 |

## 備考

- AtlasStableCommit（L15）でバージョンが固定されている（0.9.4）
- sat（SATソルバー）はAtlasの依存関係として必要
- `-d:nimAtlasBootstrap`オプションでブートストラップモードを有効化
- `--noNimblePath`オプションでシステムのNimbleパスを無視

---

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

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

### 推奨読解順序

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

Atlasビルドで使用される定数を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | koch.nim | `koch.nim` | L15: AtlasStableCommit定数（固定バージョン0.9.4） |
| 1-2 | koch.nim | `koch.nim` | L17: SatStableCommit定数（sat依存関係のバージョン） |
| 1-3 | koch.nim | `koch.nim` | L151: distDir定数（クローン先ディレクトリ） |

**読解のコツ**: AtlasはNimをGitサブモジュールとして持っていますが、kochはNim自体であるため、そのサブモジュールはインストールしません。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | koch.nim | `koch.nim` | L767: "atlas"コマンドの処理 |
| 2-2 | koch.nim | `koch.nim` | bundleAtlasExe関数（L174-182）: Atlasビルドのメインロジック |

**主要処理フロー**:
1. **L175**: コミットを決定（latestならHEAD、そうでなければAtlasStableCommit）
2. **L176-177**: `cloneDependency()`でAtlasをクローン
3. **L178-179**: `cloneDependency()`でsat依存関係をクローン
4. **L181-182**: `nimCompile()`でAtlasをコンパイル

#### Step 3: 依存関係クローンを理解する

cloneDependency関数を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | tools/deps.nim | `tools/deps.nim` | cloneDependency関数（L23-48）: Gitリポジトリのクローン処理 |

**主要処理フロー**:
- **L31-34**: ディレクトリが存在しない場合、git cloneを実行
- **L35-44**: Gitリポジトリの場合、指定コミットをチェックアウト

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

```
koch atlas [--latest]
    │
    └─ bundleAtlasExe(latest, args)
           │
           ├─ commit = if latest: "HEAD" else: AtlasStableCommit
           │
           ├─ cloneDependency(distDir, "https://github.com/nim-lang/atlas.git", commit)
           │      │
           │      ├─ git clone -q <url> dist/atlas
           │      │
           │      └─ git checkout -q <commit>
           │
           ├─ cloneDependency(distDir / "atlas" / distDir, "https://github.com/nim-lang/sat.git", SatStableCommit)
           │      │
           │      ├─ git clone -q <url> dist/atlas/dist/sat
           │      │
           │      └─ git checkout -q <SatStableCommit>
           │
           └─ nimCompile("dist/atlas/src/atlas.nim", options = "-d:release --noNimblePath -d:nimAtlasBootstrap")
                  │
                  └─ nim c -o:bin/atlas -d:release dist/atlas/src/atlas.nim
```

### データフロー図

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

--latest/--stable ────────▶ コミット選択 ───────────────▶ commitハッシュ

GitHub/atlas ─────────────▶ cloneDependency() ──────────▶ dist/atlas/

GitHub/sat ───────────────▶ cloneDependency() ──────────▶ dist/atlas/dist/sat/

dist/atlas/src/atlas.nim ─▶ nimCompile() ───────────────▶ bin/atlas
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| koch.nim | `koch.nim` | ソース | atlasコマンドの実装 |
| deps.nim | `tools/deps.nim` | ソース | 依存関係のクローン処理 |
| kochdocs.nim | `tools/kochdocs.nim` | ソース | nimCompile関数の定義 |
| atlas.nim | `dist/atlas/src/atlas.nim` | ソース | Atlas本体（クローン後） |
