【テクニカル・上級編】GCC/Clangの診断プラグイン活用術：Clang Static Analyzerで独自チェックルールを自作する – 実行環境・ランタイム・コンパイラ生産性向上バイブル

はじめに：標準の静的解析の「その先」へ

コンパイラの警告フラグをどれほど厳格に設定しようとも、`-Wall -Wextra -Werror -pedantic` の彼方にある「プロジェクト固有のドメイン知識に根ざした規約違反」や「暗黙のAPI利用規約の踏み外し」は、容赦なくすり抜けて本番環境へ到達する。

「解放済みのポインタ構造体を再度デキューしてはならない」「特定のロック取得関数と解放関数は必ず同一スタックフレーム内で対になっていなければならない」「社内共通のメモリプールから切り出したバッファを、別のサブシステムへ渡す前に特定の検証マクロを通さなければならない」。

これらは、汎用的なコンパイラ警告が検出できる領域を遥かに超越している。CI/CDのプルリクエスト段階で、これらの違反を完全自動で弾き落とす仕組みを構築できない限り、コードレビューの負荷は減らず、品質は人間の注意力という脆弱なリソースに依存し続けることになる。

本稿では、世界中のトップカンパニーで採用されている Clang Static Analyzer (CSA) の内部APIを直接叩き、プロジェクト固有のカスタムチェッカー（独自診断プラグイン）をスクラッチから実装する手法を解説する。さらに、それをDockerコンテナ内で完全に自己完結させ、CI/CDパイプラインへと極限までシームレスに統合する実践的アーキテクチャを紐解く。

—

1. Clang Static Analyzer 内部アーキテクチャとChecker APIの核心

Clang Static Analyzerは、単純な構文木（AST）のパターンマッチングを行っているわけではない。LLVM/Clangのフロントエンドが生成したASTをベースに、符号化されたパス感度解析（Path-Sensitive Analysis）を実行する高度な仮想実行エンジンである。

ExplodedGraphとシンボリック実行

CSAの内部では、プログラムの取りうるすべての実行パスを `ExplodedGraph`（爆発グラフ） という巨大な状態遷移グラフとして構築する。
各ノードは「プログラムポイント（どこにいるか）」と「プログラムステート（変数の値、ヒープの状態、制約条件）」のペアを保持している。

カスタムチェッカーを開発するということは、この `ExplodedGraph` が構築される過程において、特定のノード（例えば関数呼び出しの直前・直後）にフックし、現在の `ProgramState` を検査して、もし規約違反の制約（シンボリック制約）を満たしていればバグ報告（`BugReporter` を通じた警告）を発行するプログラムを書くことに他ならない。

—

2. 実践：カスタムチェッカー「CompanyMemoryGuard」の実装

ここでは、「特定のカスタムメモリ確保関数 `company_alloc()` で取得したポインタは、必ず専用の `company_free()` で解放されなければならず、標準の `free()` を直接呼んではならない」という、実務で頻出するドメイン固有の規約を強制するチェッカーを実装する。

2.1. 開発環境のセットアップとプラグイン構造

Clangのチェッカーは、LLVM/Clangのソースツリー外部ロード可能なダイナミックライブラリ（プラグイン）としてビルドできる。

プロジェクトのディレクトリ構造は以下の通りとする。

clang-custom-checker/
├── CMakeLists.txt
└── CompanyMemoryGuardChecker.cpp

2.2. CMakeLists.txt

LLVM/Clangのビルドシステム（LLVM CMakeモジュール）を利用してプラグインをコンパイルする。

cmake_minimum_required(VERSION 3.16.0)
project(CompanyMemoryGuardPlugin)

LLVMとClangのパッケージをホスト環境から読み込む
find_package(LLVM REQUIRED CONFIG)
find_package(Clang REQUIRED CONFIG)

include_directories(${LLVM_INCLUDE_DIRS} ${CLANG_INCLUDE_DIRS})
add_definitions(${LLVM_DEFINITIONS})

プラグインを共有ライブラリ（モジュール）としてビルド
add_library(CompanyMemoryGuardPlugin MODULE
CompanyMemoryGuardChecker.cpp
)

LLVM/Clangのライブラリリンク設定
target_link_libraries(CompanyMemoryGuardPlugin PRIVATE
clangBasic
clangAST
clangASTMatchers
clangAnalysis
clangStaticAnalyzerCore
)

2.3. CompanyMemoryGuardChecker.cpp の実装

以下が、カスタムチェッカーの全コードである。ASTのコールサイト（関数呼び出し）をフックし、`free()` が直接呼び出された瞬間に静的解析エラーを検知する。

include “clang/StaticAnalyzer/Core/BugReporter/BugType.h”
include “clang/StaticAnalyzer/Core/Checker.h”
include “clang/StaticAnalyzer/Core/PathSensitive/CallEvent.h”
include “clang/StaticAnalyzer/Core/PathSensitive/CheckerContext.h”
include “clang/AST/StmtVisitor.h”

using namespace clang;
using namespace ento;

namespace {

// チェッカー本体の定義：CallEvent（関数/メソッド呼び出し）をフックする
class CompanyMemoryGuardChecker : public Checker {
private:
mutable std::unique_ptr ForbidFreeBugType;

public:
CompanyMemoryGuardChecker() {
// バグの種類とレポートのカテゴリを初期化
ForbidFreeBugType.reset(new BugType(
this,
“Forbidden Standard Free”,
“Company Memory Management Rules”
));
}

void checkPreCall(const CallEvent &Call, CheckerContext &C) const {
// 呼び出された関数が識別可能かチェック
const FunctionDecl FD = dyn_cast_or_null(Call.getDecl());
if (!FD)
return;

IdentifierInfo II = FD->getIdentifier();
if (!II)
return;

// 呼び出し先が標準の “free” 関数であるかを判定
if (II->isStr(“free”)) {
// ExplodedGraphに新しい診断ノードを作成
ExplodedNode ErrorNode = C.generateErrorNode();
if (!ErrorNode)
return;

// BugReporterを用いて開発者にエラーメッセージを通知
auto R = std::make_unique(
ForbidFreeBugType,
“Violation: Standard ‘free()’ is strictly prohibited. Use ‘company_free()’ instead.”,
ErrorNode
);

// 該当するソースコード上の位置情報をレポートに添付
R->addRange(Call.getSourceRange());
C.emitReport(std::move(R));
}
}
};

} // namespace

// Clang Static Analyzerへチェッカーを登録するエントリポイント
extern “C” const char clang_analyzerAPIVersionString[] = CLANG_ANALYZER_API_VERSION_STRING;

// プラグインロード時にCSAレジストリへ登録
void clang_registerCheckers(CheckerRegistry &registry) {
registry.addChecker(
“alpha.company.CompanyMemoryGuard”,
“Enforces the usage of company_free instead of standard free”,
“An internal security and architecture compliance check”
);
}

void clang_aotRegisterCheckers(CheckerRegistry &registry) {
clang_registerCheckers(registry);
}

—

3. 独自チェッカーのビルドとローカル検証コマンド

作成したプラグインをビルドし、実際にC言語のソースコードに対して走らせる。

3.1. ビルドの実行

ビルドディレクトリを作成し、LLVM/Clangのパスを指定してCMakeを実行
mkdir build && cd build
cmake -DCMAKE_PREFIX_PATH=”/usr/lib/llvm-16″ ..
make -j$(nproc)

これにより、`libCompanyMemoryGuardPlugin.so`（macOSの場合は `.dylib`）が生成される。

3.2. テスト用Cソースコードの用意 (`test.c`)

include

// 社内共通のダミーアロケータ宣言
void company_alloc(size_t size);
void company_free(void ptr);

void bad_code_example(void) {
int p = (int)company_alloc(1024);

// ここで禁止されている標準の free() を呼び出す
free(p); // 期待値: 静的解析でここでエラーが検出されるべき
}

void good_code_example(void) {
int p = (int)company_alloc(1024);

// 正しい解放関数の呼び出し
company_free(p);
}

3.3. Clangへのプラグインロードと解析実行

`clang` コマンドに `-Xclang -load` を渡し、`-analyzer-checker` で自作のチェッカー名を指定して実行する。

clang -cc1 \
-load ./libCompanyMemoryGuardPlugin.so \
-analyzer-checker=alpha.company.CompanyMemoryGuard \
-analyze \
test.c

実行結果のコンソール出力例:

test.c:11:5: warning: Violation: Standard ‘free()’ is strictly prohibited. Use ‘company_free()’ instead. [alpha.company.CompanyGuard]
free(p);
^~~~~~~
1 warning generated.

完璧だ。想定通り `free(p)` の箇所だけでピンポイントに独自の静的解析警告が発報されている。

—

4. Dockerコンテナ環境による完全自動構成

開発者のローカル環境に依存せず、CI/CDパイプライン上で安定してカスタムチェッカーをコンパイル・実行するため、多段ビルド（Multi-stage build）を用いたDocker環境を構築する。LLVM/Clangの開発パッケージは巨大であるため、ビルド環境と実行環境を分離するのが鉄則である。

`Dockerfile`

==========================================
Stage 1: ビルドステージ (LLVM/Clang開発環境)
==========================================
FROM ubuntu:22.04 AS builder

必須のビルドツールとLLVM/Clang 16のインストール
RUN apt-get update && apt-get install -y –no-install-recommends \
cmake \
g++ \
llvm-16-dev \
libclang-16-dev \
clang-16 \
git \
&& rm -rf /var/lib/apt/lists/

WORKDIR /app
COPY . /app

プラグインのコンパイル
RUN mkdir build && cd build \
&& cmake -DCMAKE_PREFIX_PATH=/usr/lib/llvm-16 .. \
&& make -j$(nproc)

==========================================
Stage 2: 実行ステージ (軽量なランタイム環境)
==========================================
FROM ubuntu:22.04 AS runtime

解析実行に必要な最小限のランタイムとClang本体のみをインストール
RUN apt-get update && apt-get install -y –no-install-recommends \
clang-16 \
libclang-common-16-dev \
&& rm -rf /var/lib/apt/lists/

ビルドステージからコンパイル済みのプラグイン共有ライブラリのみを抽出配置
COPY –from=builder /app/build/libCompanyMemoryGuardPlugin.so /usr/local/lib/libCompanyMemoryGuardPlugin.so

WORKDIR /workspace
ENTRYPOINT [“clang”, “-cc1”, “-load”, “/usr/local/lib/libCompanyMemoryGuardPlugin.so”, “-analyzer-checker=alpha.company.CompanyMemoryGuard”, “-analyze”]

—

5. CI/CDパイプラインとの高度な連携（GitHub Actions）

Dockerイメージをビルド・プッシュするか、あるいはCIランナー上で直接コンテナを回し、プロジェクト全体のビルドプロセスにカスタム静的解析を組み込む。ここではGitHub Actionsを使った実戦的なワークフローを示す。

`.github/workflows/static-analysis.yml`

name: Custom Static Analysis Pipeline

on:
pull_request:
branches: [ main, master ]

jobs:
analyze:
runs-on: ubuntu-latest

container:
image: ubuntu:22.04
options: –user root

steps:
# リポジトリのチェックアウト

  • name: Checkout Repository

uses: actions/checkout@v4

# 依存ツール（LLVM/Clang 16, CMakeなど）のセットアップ

  • name: Install LLVM and Build Dependencies

run: |
apt-get update && apt-get install -y –no-install-recommends \
cmake \
g++ \
llvm-16-dev \
libclang-16-dev \
clang-16 \
git

# 1. 自作チェッカープラグインのビルド

  • name: Build Custom Analyzer Plugin

run: |
mkdir -p .checker_build
cd .checker_build
cmake -DCMAKE_PREFIX_PATH=/usr/lib/llvm-16 ${{ github.workspace }}/checker_src
make -j$(nproc)

# 2. 対象プロジェクトのソースコードに対してカスタムチェッカーを実行
# （JSON形式やPlist形式で結果を出力させ、後続のダッシュボード等へ連携可能）

  • name: Run Clang Static Analyzer with Custom Plugin

run: |
PLUGIN_PATH=”${{ github.workspace }}/.checker_build/libCompanyMemoryGuardPlugin.so”

# 解析対象ファイルを走査してコンパイル＆解析
# エラーが見つかった場合は非ゼロ終了コードを返すように制御
find src/ -name “.c” | while read file; do
echo “Analyzing: $file”
clang-16 -cc1 \
-load “$PLUGIN_PATH” \
-analyzer-checker=alpha.company.CompanyMemoryGuard \
-analyzer-output=text \
-analyze “$file” || exit 1
done

このパイプラインにより、開発者がプルリクエストを作成した瞬間に、既存のコンパイラ警告では絶対に検知できない「社内独自規約の違反」が自動検知され、違反コードが含まれている場合はマージが物理的にブロックされる。

—

6. パフォーマンスとメモリ消費の最適化ハック（エキスパート知見）

最後に、大規模なコードベース（数百万行規模のC/C++プロジェクト）に対してCSAのカスタムチェッカーを導入する際、避けて通れないパフォーマンスのボトルネックとメモリ爆発を防ぐためのハックを共有する。

1. 状態爆発（State Explosion）の抑制

パス感度解析は、条件分岐（`if/else`）やループが増えるごとに、`ExplodedGraph` のノード数が指数関数的に爆発する。

  • 対策: カスタムチェッカー内で複雑なループを展開したり、深いポインタ追跡を素朴なアルゴリズムで実装しないこと。不要な場合は `CheckerContext::isDifferent()`, `ProgramState` の不必要なカスタムデータ保持を避け、`checkPreCall` や `checkPostCall` など最小限のライフサイクルイベントだけに処理を絞る。

2. キャッシュとインクリメンタル解析の活用

CI上ですべてのファイルを毎回ゼロからフル解析していると、ビルド・解析時間が数十分〜数時間に及ぶ。

  • 対策: `Clang Tidy` や `scan-build` の仕組みを応用し、`intercept-build`（Bear等を使用）によってコンパイルデータベース（`compile_commands.json`）を生成。変更のあったファイルのみを対象に差分解析（Incremental Analysis）を行うラッパースクリプトをCIに組み込むことで、解析時間を数秒〜数十秒レベルにまで劇的に短縮できる。

—

おわりに

標準のツールに縛られる開発は、今日の高度に複雑化したソフトウェア工学において明らかなボトルネックである。

Clang Static AnalyzerのAPIを直接ハックし、自社独自の制約事項をコンパイルタイムのセキュリティゲートとして組み込む技術は、組織のコード品質を「属人化された規約チェック」から「完全自動化された不変の防壁」へとシフトさせる。

この知見をベースに、あなたのプロジェクト固有のバグパターンを封じ込める最強のチェッカーを自らの手で組み上げ、開発プロセスの主導権を完全に掌握せよ。

スポンサーリンク
タイトルとURLをコピーしました