# バッチ設計書 44-build-rootfs.sh

## 概要

本ドキュメントは、クロスコンパイル用rootfs構築スクリプト（build-rootfs.sh）の設計仕様を記載したものです。このスクリプトは、.NETランタイムを様々なプラットフォーム向けにクロスコンパイルするために必要なルートファイルシステム（rootfs）を構築する汎用的なツールです。

### 本バッチの処理概要

このバッチは、指定されたターゲットアーキテクチャとディストリビューションに応じて、適切なrootfsを自動的に構築します。Ubuntu/Debian系、Alpine Linux、FreeBSD、illumos、Haiku、Tizenなど、多様なプラットフォームをサポートしています。

**業務上の目的・背景**：.NETはマルチプラットフォーム対応のランタイムであり、ARM、ARM64、RISC-V、PowerPC、S390X、x86/x64など多様なアーキテクチャをサポートしています。これらのプラットフォーム向けにネイティブコードをビルドするには、ターゲットシステムのヘッダーファイルやライブラリを含むsysroot（rootfs）が必要です。このスクリプトにより、開発者やCI/CDシステムは一貫した方法でrootfsを構築できます。

**バッチの実行タイミング**：クロスコンパイルビルドの前準備として実行されます。CI/CDパイプラインの初期段階、またはローカル開発環境の構築時に手動で実行されます。

**主要な処理内容**：
1. コマンドライン引数の解析（アーキテクチャ、ディストリビューション、LLDBバージョン等）
2. ターゲットプラットフォームに応じた設定（パッケージリスト、リポジトリURL等）
3. rootfsディレクトリの準備（既存の場合はクリーンアップ）
4. プラットフォーム別の構築処理：
   - Alpine: apk.staticを使用してパッケージインストール
   - FreeBSD: base.txz展開とpkgによるパッケージインストール
   - illumos: sysroot展開とbinutils/gccビルド
   - Haiku: HPKGパッケージ展開
   - Ubuntu/Debian: debootstrapまたはinstall-debs.pyによる構築
   - Tizen: tizen-build-rootfs.shを呼び出し

**前後の処理との関連**：tizen-build-rootfs.sh、install-debs.pyなどの補助スクリプトを呼び出します。構築されたrootfsは.NETのビルドスクリプト（build.sh）でROOTFS_DIRとして使用されます。

**影響範囲**：--rootfsdirで指定されたディレクトリ、またはデフォルトの.tools/rootfs/{arch}ディレクトリにrootfsが構築されます。大量のディスク容量とネットワーク帯域を使用します。

## バッチ種別

クロスコンパイル環境構築 / rootfs構築 / マルチプラットフォーム対応

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（rootfs構築が必要な場合） |
| 実行時刻 | 手動実行またはCI/CDパイプライン内 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動実行 / CI/CDパイプライン |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| root権限 | debootstrap使用時に必要（--skipemulationで回避可能） |
| wget または curl | パッケージダウンロード用 |
| debootstrap | Ubuntu/Debian系rootfs構築用（--skipemulation時は不要） |
| qemu-user-static | エミュレーション実行時に必要（--skipemulation時は不要） |
| Python3 | --skipemulation時のinstall-debs.py実行用 |

### 実行可否判定

- サポートされていないアーキテクチャやディストリビューションの組み合わせはエラー
- --rootfsdirが指定されていない場合はデフォルトパスを使用

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| BuildArch | string | No | arm | ターゲットアーキテクチャ |
| CodeName | string | No | xenial | ディストリビューション名 |
| lldbx.y | string | No | lldb3.9 | LLDBバージョン |
| llvmx[.y] | string | No | なし | LLVMバージョン |
| --skipunmount | flag | No | false | rootfsのアンマウントをスキップ |
| --skipsigcheck | flag | No | false | パッケージ署名検証をスキップ |
| --skipemulation | flag | No | false | QEMU/debootstrap不要モード |
| --use-mirror | flag | No | false | ミラーURLを使用 |
| --jobs N | string | No | 自動 | 並列ジョブ数を制限 |
| --rootfsdir | string | No | .tools/rootfs/{arch} | rootfs出力先 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| Ubuntu/Debianリポジトリ | HTTP | http://ports.ubuntu.com/ 等 |
| Alpineリポジトリ | HTTP | http://dl-cdn.alpinelinux.org/alpine/ |
| FreeBSDリリース | HTTP | https://download.freebsd.org/ |
| illumosリポジトリ | HTTP | GitHub/pkgsrc.smartos.org |
| Haikuリポジトリ | HTTP | https://eu.hpkg.haiku-os.org/ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| $ROOTFS_DIR | ディレクトリ | 構築されたrootfs |
| 標準出力 | テキスト | 進捗メッセージ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | rootfs（ディレクトリ全体） |
| 出力先 | --rootfsdirで指定、またはデフォルトパス |
| 文字コード | バイナリ/テキスト混在 |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. コマンドライン引数の解析
   └─ アーキテクチャ、ディストリビューション、オプション等を解析
2. プラットフォーム固有の設定
   └─ パッケージリスト、リポジトリURL、アーキテクチャマッピング
3. rootfsディレクトリの準備
   └─ 既存ディレクトリの削除・アンマウント
4. ダウンロードツールの確認
   └─ wgetまたはcurlの存在確認
5. プラットフォーム別処理:
   5a. Alpine:
       └─ apk.staticダウンロード、パッケージインストール
   5b. FreeBSD:
       └─ base.txz展開、pkgビルド、パッケージインストール
   5c. illumos:
       └─ sysroot展開、binutils/gccビルド、パッケージインストール
   5d. Haiku:
       └─ package toolダウンロード、HPKGパッケージ展開
   5e. Ubuntu/Debian:
       └─ debootstrap実行、apt-getでパッケージインストール
       └─ --skipemulationの場合はinstall-debs.pyを使用
   5f. Tizen:
       └─ tizen-build-rootfs.shを呼び出し
6. クリーンアップ
   └─ 一時ファイル削除、アンマウント
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[引数解析]
    B --> C[プラットフォーム設定]
    C --> D[rootfsディレクトリ準備]
    D --> E{プラットフォーム判定}
    E -->|Alpine| F[apkでパッケージインストール]
    E -->|FreeBSD| G[base.txz展開+pkg]
    E -->|illumos| H[sysroot+ビルドツール構築]
    E -->|Haiku| I[HPKGパッケージ展開]
    E -->|Ubuntu/Debian| J{skipemulation?}
    E -->|Tizen| K[tizen-build-rootfs.sh呼出]
    J -->|Yes| L[install-debs.py実行]
    J -->|No| M[debootstrap実行]
    L --> N[クリーンアップ]
    M --> N
    F --> N
    G --> N
    H --> N
    I --> N
    K --> N
    N --> O[正常終了]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 該当なし | - | - | このバッチはデータベース操作を行いません |

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

このバッチはデータベース操作を行いません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | Unsupported platform | サポートされていないプラットフォーム | サポート対象のアーキテクチャ/ディストリビューションを指定 |
| 1 | debootstrap失敗 | debootstrapの実行エラー | エラーログを確認し、root権限や依存関係を確認 |
| 1 | ダウンロード失敗 | パッケージのダウンロードエラー | ネットワーク接続とリポジトリURLを確認 |
| 1 | ツール未インストール | wget/curlが未インストール | 必要なツールをインストール |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

1. debootstrap.logを確認してエラー原因を特定
2. rootfsディレクトリを削除して再実行
3. --skipsigcheckオプションで署名検証問題を回避
4. --skipemulationオプションでQEMU依存を回避

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 数十〜数百パッケージ |
| 目標処理時間 | 数分〜数十分（プラットフォームとネットワーク依存） |
| メモリ使用量上限 | コンパイル時は数GB必要（illumos/Haikuの場合） |

## 排他制御

同一のrootfsディレクトリに対して同時実行しないでください。ファイルの競合や不完全なrootfsが生成される可能性があります。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 情報ログ | debootstrap実行時 | debootstrapコマンドの出力 |
| 情報ログ | パッケージインストール時 | インストールされるパッケージ一覧 |
| エラーログ | 失敗時 | debootstrap.logの内容 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 終了コード | 0以外 | CI/CDパイプラインの失敗通知 |
| ディスク使用量 | 環境依存 | 手動確認が必要 |

## 備考

- サポートされるアーキテクチャ：arm, arm64, armel, armv6, loongarch64, ppc64le, riscv64, s390x, x64, x86
- サポートされるディストリビューション（Ubuntu）：xenial, bionic, focal, jammy, noble
- サポートされるディストリビューション（Debian）：stretch, buster, bullseye, bookworm, sid
- サポートされるディストリビューション（その他）：alpine, freebsd13, freebsd14, illumos, haiku, tizen
- Alpineパッケージには署名検証用の公開鍵がスクリプト内にハードコードされています
- --skipemulationオプションは、QEMUなしでrootfsを構築する場合に使用します（Pythonベースのinstall-debs.pyを使用）
