# 機能設計書 48-MSBuildタスク（Fsc）

## 概要

本ドキュメントは、F#ビルドシステムにおけるMSBuild用F#コンパイラタスク（Fsc）の機能設計を記述する。

### 本機能の処理概要

Fscタスクは、MSBuildからF#コンパイラ（fsc.exe）を呼び出すためのタスク実装である。コンパイラオプションをMSBuildプロパティとして受け取り、コマンドラインを生成してコンパイルを実行する。

**業務上の目的・背景**：.NETプロジェクトシステムはMSBuildを基盤としており、F#プロジェクトもMSBuildを通じてビルドされる。FscタスクはMSBuildとF#コンパイラを接続するブリッジとして機能し、Visual Studioやdotnetコマンドからのビルドをサポートする。

**機能の利用シーン**：
- Visual StudioでのF#プロジェクトビルド
- dotnet buildコマンドの実行
- CI/CDパイプラインでのビルド
- コマンドラインからのMSBuildビルド

**主要な処理内容**：
1. MSBuildプロパティからコンパイラオプションの受け取り
2. コマンドラインの生成
3. fsc.exeの実行またはホストオブジェクト経由のコンパイル
4. コンパイル結果のMSBuildへの報告

**関連システム・外部連携**：MSBuild、fsc.exe、Visual Studioホストオブジェクト

**権限による制御**：特になし

## 関連画面

本機能はビルドシステム機能のため、直接関連する画面はない。

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | - |

## 機能種別

ビルドタスク / コンパイラ連携

## 入力仕様

### 入力パラメータ

主要なプロパティ（一部）:

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Sources | ITaskItem[] | Yes | ソースファイル一覧 | - |
| OutputAssembly | string | Yes | 出力アセンブリパス | - |
| References | ITaskItem[] | No | 参照アセンブリ一覧 | - |
| TargetType | string | No | 出力種別（library/exe/winexe/module） | - |
| DebugSymbols | bool | No | デバッグシンボル生成 | - |
| DebugType | string | No | デバッグ情報種別 | - |
| Optimize | bool | No | 最適化有効化 | - |
| DefineConstants | ITaskItem[] | No | 条件付きコンパイルシンボル | - |
| DocumentationFile | string | No | XMLドキュメント出力先 | - |
| KeyFile | string | No | 署名キーファイル | - |
| LangVersion | string | No | 言語バージョン | - |
| Platform | string | No | ターゲットプラットフォーム | - |

### 入力データソース

MSBuildプロジェクトファイル（.fsproj）からのプロパティ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | 終了コード（0: 成功、非0: 失敗） |
| CommandLineArgs | ITaskItem[] | 生成されたコマンドライン引数 |

### 出力先

コンパイル済みアセンブリ、PDB、XMLドキュメント

## 処理フロー

### 処理シーケンス

```
1. MSBuildからタスク呼び出し
   └─ Execute()メソッドが呼ばれる
2. コマンドライン生成
   └─ GenerateResponseFileCommands()でオプションを生成
3. コンパイル実行
   └─ ExecuteTool()またはHostObject経由でコンパイル
4. 結果の返却
   └─ 終了コードをMSBuildに返す
```

### フローチャート

```mermaid
flowchart TD
    A[MSBuildからの呼び出し] --> B[Execute]
    B --> C[GenerateCommandLineCommands]
    C --> D[GenerateResponseFileCommands]
    D --> E{SkipCompilerExecution?}
    E -->|Yes| F[コマンドライン引数を出力のみ]
    E -->|No| G{HostObjectあり?}
    G -->|Yes| H[HostObject.Compile呼び出し]
    G -->|No| I[fsc.exe実行]
    F --> J[完了]
    H --> J
    I --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | ホストオブジェクト優先 | Visual Studio内ではHostObjectを使用 | HostObject存在時 |
| BR-02 | レスポンスファイル | 長いコマンドラインはレスポンスファイル経由 | 常時 |
| BR-03 | 並列コンパイル | YieldDuringToolExecution有効 | 常時 |

### 計算ロジック

コマンドラインオプションの対応:
| プロパティ | コマンドラインオプション |
|-----------|------------------------|
| OutputAssembly | -o: |
| DebugSymbols=true | -g |
| DebugType | --debug: |
| Optimize=true | --optimize+ |
| Tailcalls=false | --tailcalls- |
| DefineConstants | --define: |
| DocumentationFile | --doc: |
| KeyFile | --keyfile: |
| References | -r: |
| TargetType | --target: |
| Platform | --platform: |
| NoFramework=true | --noframework |
| LangVersion | --langversion: |

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| InvalidOperationException | 実行時エラー | ToolPathが未設定 | FSharpコンパイラをインストール |
| TargetInvocationException | 実行時エラー | ビルドキャンセル | 再ビルド |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- YieldDuringToolExecution=trueで並列ビルドを最適化
- HostObjectによるインプロセスコンパイルで高速化

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

- KeyFileは安全に管理すること
- コマンドライン引数にはセンシティブな情報を含めない

## 備考

FscタスクはMicrosoft.Build.Utilities.ToolTaskを継承しており、ツール実行の基本的な機能を活用している。

---

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

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

### 推奨読解順序

#### Step 1: クラス構造を理解する

Fscタスククラスの全体構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Fsc.fs | `src/FSharp.Build/Fsc.fs` | **19-21行目**: Fscクラス定義とToolTask継承 |
| 1-2 | Fsc.fs | `src/FSharp.Build/Fsc.fs` | **23-99行目**: プライベートフィールド定義 |

**読解のコツ**: mutable letで定義されたフィールドがコンパイラオプションに対応する。null許容型（string | null）の使用に注意。

#### Step 2: プロパティを理解する

公開プロパティがMSBuildプロパティと対応する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Fsc.fs | `src/FSharp.Build/Fsc.fs` | **376-378行目**: BaseAddressプロパティ |
| 2-2 | Fsc.fs | `src/FSharp.Build/Fsc.fs` | **512-515行目**: OutputAssemblyプロパティ |
| 2-3 | Fsc.fs | `src/FSharp.Build/Fsc.fs` | **601-604行目**: Sourcesプロパティ |

**主要プロパティ一覧**:
- **404-406行目**: DebugSymbols
- **427-429行目**: DefineConstants
- **498-500行目**: Optimize
- **571-574行目**: References

#### Step 3: コマンドライン生成を理解する

generateCommandLineBuilder関数によるコマンドライン構築を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Fsc.fs | `src/FSharp.Build/Fsc.fs` | **118-373行目**: generateCommandLineBuilder関数 |
| 3-2 | Fsc.fs | `src/FSharp.Build/Fsc.fs` | **121-122行目**: OutputAssemblyの処理 |
| 3-3 | Fsc.fs | `src/FSharp.Build/Fsc.fs` | **197-201行目**: Optimizeの処理 |

**主要処理フロー**:
- **118-119行目**: FSharpCommandLineBuilderを作成
- **122行目**: -o: オプション追加
- **128-129行目**: DebugSymbolsで-gを追加
- **197-201行目**: Optimizeで--optimize+/-を追加

#### Step 4: 実行処理を理解する

ExecuteTool、GenerateResponseFileCommandsなどの実行処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Fsc.fs | `src/FSharp.Build/Fsc.fs` | **732-790行目**: ExecuteToolメソッド |
| 4-2 | Fsc.fs | `src/FSharp.Build/Fsc.fs` | **792-804行目**: GenerateCommandLineCommands |
| 4-3 | Fsc.fs | `src/FSharp.Build/Fsc.fs` | **802-804行目**: GenerateResponseFileCommands |

**主要処理フロー**:
- **733-737行目**: ProvideCommandLineArgs時にコマンドラインを保存
- **739-740行目**: SkipCompilerExecution時は0を返却
- **742-790行目**: HostObject経由またはベースクラスでコンパイル実行

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

```
MSBuild (Fscタスク呼び出し)
    │
    ├─ Fsc.Execute() (ToolTaskから継承)
    │      │
    │      ├─ GenerateCommandLineCommands()
    │      │      └─ dotnetFscCompilerPathの設定
    │      │
    │      ├─ GenerateResponseFileCommands()
    │      │      └─ generateCommandLineBuilder()
    │      │             ├─ AppendSwitchIfNotNull("-o:", ...)
    │      │             ├─ AppendSwitch("-g")
    │      │             ├─ AppendSwitch("--optimize+/-")
    │      │             └─ ... 他のオプション
    │      │
    │      └─ ExecuteTool()
    │             │
    │             ├─ provideCommandLineArgs → CommandLineArgs出力
    │             │
    │             ├─ skipCompilerExecution → 0返却
    │             │
    │             └─ HostObject確認
    │                    │
    │                    ├─ あり → HostObject.Compile()
    │                    │         └─ インプロセスコンパイル
    │                    │
    │                    └─ なし → base.ExecuteTool()
    │                              └─ fsc.exe プロセス実行
    │
    └─ 終了コード返却
```

### データフロー図

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

.fsproj         ───▶  MSBuild             ───▶  Fscタスクプロパティ
  プロジェクト         (プロパティ評価)            Sources, References等
    │
    ▼
プロパティ      ───▶  generateCommandLine  ───▶  コマンドライン
  値一覧               Builder                    --target:library -o:...
    │
    ▼
fsc.exe/        ───▶  ExecuteTool         ───▶  コンパイル結果
HostObject            (コンパイル実行)            アセンブリ, PDB
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Fsc.fs | `src/FSharp.Build/Fsc.fs` | ソース | Fscタスク実装 |
| FSharpCommandLineBuilder.fs | `src/FSharp.Build/FSharpCommandLineBuilder.fs` | ソース | コマンドラインビルダー |
| FSharp.Build.fsproj | `src/FSharp.Build/FSharp.Build.fsproj` | プロジェクト | ビルドプロジェクト |
