# バッチ設計書 21-m4マクロ群

## 概要

本ドキュメントは、libuvプロジェクトの `m4/` ディレクトリ配下に配置されたAutotools用マクロファイル群のバッチ設計書である。これらのマクロは `autogen.sh` および `configure.ac` から参照され、Autotoolsビルドシステムの構成処理において、コンパイラフラグ検証・Pthread検出・プラットフォーム条件分岐・バージョン検証などの基盤機能を提供する。

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

m4マクロ群は、Autotoolsビルドシステム（autoconf/automake）の `configure` スクリプト生成時に展開・実行されるマクロ定義ファイル群である。`autogen.sh` 実行時に `aclocal -I m4` を通じてマクロパスに追加され、`autoconf` による `configure` スクリプト生成の過程で各マクロが展開される。

**業務上の目的・背景**：libuvは20以上のプラットフォーム（Linux、macOS、FreeBSD、AIX、Solaris、Windows/MinGW等）をサポートするクロスプラットフォームライブラリである。各プラットフォームで異なるコンパイラフラグ、リンカフラグ、POSIXスレッドライブラリの検出方法を抽象化し、ビルドシステムの可搬性を担保するためにm4マクロ群が必要となる。これらのマクロにより、開発者は `./configure && make` という統一された手順でビルドを実行でき、プラットフォームごとの差異をマクロが吸収する。

**バッチの実行タイミング**：`autogen.sh` スクリプトの実行時（手動）。具体的には、リリースビルドの準備時、CI/CD環境でのAutotools系ビルド実行時、または開発者がソースツリーから初回ビルドを行う際に実行される。

**主要な処理内容**：
1. `as_case.m4` - `AS_CASE` マクロの定義。シェルスクリプトの `case` 文を生成するm4マクロを提供し、`configure.ac` 内でプラットフォーム判別に使用される
2. `libuv-check-flags.m4` - コンパイラ・リンカフラグ検証マクロ群の定義。`CC_CHECK_CFLAGS`、`CC_CHECK_LDFLAGS`、`CC_CHECK_CFLAG_APPEND`、`CC_ATTRIBUTE_*` 系マクロ等を提供する
3. `ax_pthread.m4` - POSIX Threads（pthread）検出マクロの定義。GNU Autoconf Archiveから取得した `AX_PTHREAD` マクロで、各プラットフォーム固有のpthreadフラグ・ライブラリを自動検出する
4. `libuv-check-versions.m4` - リリース時のAutotools最低バージョン要件定義。`autogen.sh release` 実行時に動的に上書きされる

**前後の処理との関連**：`autogen.sh`（No.1）が本マクロ群を `aclocal -I m4` で参照し、`configure.ac`（No.2）内で各マクロを呼び出す。生成される `configure` スクリプトは `Makefile.am`（No.3）と連携してビルドプロセス全体を構成する。

**影響範囲**：Autotoolsベースのビルドシステム全体。`configure` スクリプトの動作、コンパイラフラグの設定（`AM_CFLAGS`、`PTHREAD_CFLAGS`等）、リンカフラグの設定（`PTHREAD_LIBS`等）、プラットフォーム検出結果に影響する。

## バッチ種別

ビルド設定 / ビルドシステム構成前処理

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動（`autogen.sh` 実行時に間接的に呼び出し） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| autoconf >= 2.57 | `configure.ac` の `AC_PREREQ(2.57)` で要求 |
| automake | `aclocal` コマンドが利用可能であること |
| libtool | `libtoolize` コマンドが利用可能であること |
| m4ディレクトリの存在 | `m4/` ディレクトリに各 `.m4` ファイルが配置されていること |
| リリースビルド時のバージョン要件 | `libuv-check-versions.m4` に記載（autoconf 2.72、automake 1.17、libtool 2.4.7） |

### 実行可否判定

`autogen.sh` が `aclocal -I m4` を実行する際に、m4ディレクトリ内のマクロファイルが自動的に読み込まれる。個別のマクロは `configure.ac` 内での `m4_include` ディレクティブまたは `AC_DEFUN` によるマクロ名呼び出しによって展開される。マクロファイルが存在しない場合、`aclocal` または `autoconf` がエラーを返す。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | m4マクロは宣言的定義であり、`configure.ac` から呼び出されるパラメータに依存 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| `m4/as_case.m4` | m4マクロ定義 | `AS_CASE` マクロ定義。シェルcase文生成用 |
| `m4/libuv-check-flags.m4` | m4マクロ定義 | コンパイラ・リンカフラグ検証マクロ群（`CC_CHECK_CFLAGS`、`CC_ATTRIBUTE_*` 等） |
| `m4/ax_pthread.m4` | m4マクロ定義 | POSIX Threads検出マクロ `AX_PTHREAD`（GNU Autoconf Archive由来、serial 24） |
| `m4/libuv-check-versions.m4` | m4マクロ定義 | Autotoolsバージョン要件チェック（リリースビルド時に `autogen.sh` が上書き） |
| `m4/.gitignore` | テキスト | `libtoolize` が生成するm4ファイルを無視し、リポジトリ管理対象を限定する設定 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| `configure` スクリプト | シェルスクリプト | `autoconf` が各m4マクロを展開して生成する構成スクリプト |
| `config.h` | Cヘッダ | マクロ展開結果として定義されるプリプロセッサシンボル（`HAVE_PTHREAD`、`SUPPORT_ATTRIBUTE_*` 等） |
| `AM_CFLAGS` | Makefile変数 | `CC_CHECK_CFLAG_APPEND` により検証・追加されたコンパイラフラグ |
| `PTHREAD_LIBS` / `PTHREAD_CFLAGS` / `PTHREAD_CC` | Makefile変数 | `AX_PTHREAD` により検出されたpthread関連設定 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | `configure`（autoconf展開結果） |
| 出力先 | プロジェクトルート |
| 文字コード | ASCII |
| 区切り文字 | 該当なし（シェルスクリプト） |

## 処理フロー

### 処理シーケンス

```
1. autogen.sh 実行開始
   └─ Autotools環境のバージョン確認

2. libuv-extra-automake-flags.m4 動的生成
   └─ automakeバージョンに基づき serial-tests フラグを設定

3. libtoolize --copy --force 実行
   └─ libtoolの補助m4ファイル群（lt*.m4等）をm4/に配置

4. aclocal -I m4 実行
   └─ m4/ディレクトリ内の全.m4ファイルをスキャンしaclocal.m4を生成

5. configure.ac のm4_include処理
   ├─ m4/libuv-extra-automake-flags.m4 読み込み
   ├─ m4/as_case.m4 読み込み（AS_CASEマクロ定義）
   └─ m4/libuv-check-flags.m4 読み込み（CC_CHECK_*マクロ群定義）

6. autoconf によるconfigure生成
   ├─ CC_ATTRIBUTE_VISIBILITY 呼び出し → visibilityサポート検出
   ├─ CC_CHECK_FLAG_SUPPORTED_APPEND → -fno-strict-aliasing検証
   ├─ CC_CHECK_CFLAGS_APPEND → -g, -std=gnu11, -Wall, -Wextra等の検証
   ├─ AX_PTHREAD → Pthreadライブラリ・フラグの検出
   └─ AS_CASE → プラットフォーム別条件分岐（16プラットフォーム対応）

7. リリースビルド時追加処理（autogen.sh release）
   └─ libuv-check-versions.m4にバージョン要件を書き込み
```

### フローチャート

```mermaid
flowchart TD
    A[autogen.sh 実行] --> B[Autoolsバージョン確認]
    B --> C[libuv-extra-automake-flags.m4 生成]
    C --> D[libtoolize 実行]
    D --> E[aclocal -I m4 実行]
    E --> F{リリースビルド?}
    F -->|Yes| G[libuv-check-versions.m4 上書き]
    F -->|No| H[autoconf 実行]
    G --> H
    H --> I[configure.ac 内のマクロ展開]
    I --> J[as_case.m4: AS_CASE展開]
    I --> K[libuv-check-flags.m4: CC_CHECK_* 展開]
    I --> L[ax_pthread.m4: AX_PTHREAD 展開]
    J --> M[configureスクリプト生成]
    K --> M
    L --> M
    M --> N[automake --add-missing 実行]
    N --> O[ビルドシステム構成完了]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 該当なし | - | - | 本バッチはファイルシステム上のビルド構成処理であり、データベース操作は行わない |

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| EXIT 1 | マクロ未定義エラー | `configure.ac` が参照するマクロが `m4/` 内に存在しない場合 | 対象の `.m4` ファイルがリポジトリに含まれていることを確認。`m4/.gitignore` の設定も確認する |
| EXIT 1 | コンパイラフラグ非対応 | `CC_CHECK_CFLAGS` でフラグが非対応と判定された場合 | 該当フラグはスキップされ、`AM_CFLAGS` に追加されない（正常動作） |
| EXIT 1 | Pthread検出失敗 | `AX_PTHREAD` でpthreadライブラリが検出できない場合 | `PTHREAD_LIBS` / `PTHREAD_CFLAGS` 環境変数を手動設定するか、pthreadライブラリをインストールする |
| EXIT 1 | バージョン不足 | `AC_PREREQ` / `AM_INIT_AUTOMAKE` / `LT_PREREQ` でバージョンが不足している場合 | 指定バージョン以上のAutotools・libtoolをインストールする |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 該当なし（手動実行のため自動リトライなし） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

m4マクロの展開に失敗した場合は、以下の手順でリカバリを行う：
1. `autogen.sh` の出力ログから失敗したマクロ名を特定する
2. 該当する `.m4` ファイルの存在と内容を確認する
3. `m4/.gitignore` により必要なファイルが除外されていないか確認する
4. Autotoolsのバージョンが要件を満たしているか確認する
5. 必要に応じて `autoreconf -fiv` で再生成を試みる

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし（ファイル生成処理） |
| コミットタイミング | 該当なし |
| ロールバック条件 | `autoconf` / `automake` がエラー終了した場合、`configure` スクリプトは生成されない |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | m4ファイル4個 + 動的生成1個 |
| 目標処理時間 | 数秒以内（`autogen.sh` 全体で10秒以内） |
| メモリ使用量上限 | 特に制約なし（autoconfプロセスのメモリ使用量に依存） |

## 排他制御

同一ディレクトリでの `autogen.sh` の同時実行は避けるべきである。`aclocal` や `autoconf` がm4ディレクトリ内のファイルを読み書きするため、同時実行時にファイルの不整合が発生する可能性がある。CI/CD環境では、ビルドごとに独立した作業ディレクトリを使用することで回避する。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 進捗ログ | `autogen.sh` 内 `set -x` | 実行中のコマンド（`aclocal -I m4`、`autoconf`、`automake` 等） |
| 検出結果ログ | `configure` 実行時 | `checking if $CC supports ... flag ... yes/no`、`checking for pthread_join ... yes/no` 等 |
| エラーログ | マクロ展開失敗時 | `autoconf` / `aclocal` のエラーメッセージ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| `autogen.sh` 実行結果 | 終了コード != 0 | CI/CDワークフロー（GitHub Actions） |
| `configure` 実行結果 | 終了コード != 0 | CI/CDワークフロー（GitHub Actions） |

## 備考

- `m4/.gitignore` は `libtoolize` が自動生成するm4ファイル（`lt*.m4` 等）を無視する設定となっており、リポジトリには `as_case.m4`、`ax_pthread.m4`、`libuv-check-flags.m4` のみがバージョン管理対象として明示的に保持されている
- `libuv-check-versions.m4` は `.gitignore` に含まれるが、`autogen.sh release` 実行時に動的に上書き生成されるファイルである
- `ax_pthread.m4` はGNU Autoconf Archive（https://www.gnu.org/software/autoconf-archive/ax_pthread.html）から取得したマクロで、serial 24バージョンが使用されている
- `libuv-check-flags.m4` の `CC_CHECK_ATTRIBUTE_*` マクロ群は、GCC/Clang固有の `__attribute__` 構文のサポート検出に使用される（visibility、format、nonnull、packed等）
- CMakeLists.txt（No.4）によるCMakeビルドシステムでは、これらのm4マクロは使用されない。Autotoolsビルド専用の構成要素である
