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

はじめに：なぜ「標準の警告」だけでは大規模Cプロジェクトが崩壊するのか

テックリードとして数百万行規模のC言語製ミドルウェアや組込みファームウェアのコードベースに向き合っていると、ある残酷な現実に行き当たります。`-Wall -Wextra -Werror` を有効にし、最新のGCCやClangで厳格にコンパイルしていても、「ドメイン固有の致命的なバグ」はすり抜けてくるのです。

  • 「特定のロック取得関数を呼んだら、必ず対応する解放関数を特定のパス以外で呼んでいないか」
  • 「非スレッドセーフなレガシーAPIを、マルチスレッドコンテキストで誤って直接叩いていないか」
  • 「特定のポインタ引数に対し、NULLチェックだけでなく特定の初期化マクロを通したかどうかのバリデーションを強制したい」

これらは、コンパイラが標準で提供する構文解析やデータフロー解析の枠外（アプリケーションのビジネスロジックやアーキテクチャ規約）に依存しています。コードレビューの人力に頼るのは、スケールの観点から破綻しています。

ここで投入すべき究極の武器が、Clang Static Analyzer (CSA) を用いた「カスタムチェッカー（独自診断プラグイン）」の開発です。本記事では、ClangのAST（抽象構文木）とパス感度解析（Path-sensitive analysis）のエンジンをハックし、プロジェクト固有の規約違反をコンパイル時（厳密には解析時）に完全自動検出する実践的アプローチを伝授します。

—

1. Clang Static Analyzerの内部アーキテクチャを理解する

カスタムチェッカーを書く前に、Clangがソースコードをどのように解釈し、バグを見つけ出しているのか、その内部データフローを把握しておく必要があります。

[C Source Code]
│
▼
[Clang Lexer / Parser]
│
▼
[AST (Abstract Syntax Tree)] ◄─── 構文レベルの解析 (ASTMatchersでフック可能)
│
▼
[CFG (Control Flow Graph)] ◄───── 制御フローの分岐・ループ構造
│
▼
[ExplodedGraph (符号化された実行パス空間)] ◄─── パス感度解析 (符号実行/Symbolic Execution)
│
▼
[BugReporter / Custom Checker] ◄─── 違反検出時に警告をアタッチ

Clang Static Analyzerは、単なる静的コードリーダではありません。プログラムの実行可能なすべての分岐パスを仮想的にトレースする「符号実行（Symbolic Execution）」エンジンを内蔵しています。
私たちが作成するカスタムチェッカーは、このエンジンのイベント（関数呼び出し時、分岐時、メモリ割り当て時など）をフックし、プログラムの状態（State）を監視・検証することで、独自のルール違反を検知します。

—

2. 実践：プロジェクト固有ルールを検出するカスタムチェッカーの自作

今回は実務で非常によくある要件として、「自社製のリソース管理関数 `secure_alloc()` を呼んだら、必ず対応する `secure_free()` を同一関数内で呼んでいなければならない（リソースリークの検出）」というカスタムチェッカーを実装します。

開発環境のセットアップ

Clangのチェッカーを開発するには、LLVM/Clangのソースツリー、またはLLVM開発用ヘッダとライブラリが必要です。プラグインは動的ライブラリ（`.so` または `.dylib`）としてビルドし、`clang` コマンドに読み込ませます。

プロジェクトのディレクトリ構造は以下のように設計します。

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

設定ファイル・ビルドスクリプト（CMakeLists.txt）

LLVM/Clangのエコシステムに適合させた、堅牢な `CMakeLists.txt` のベストプラクティスです。

cmake_minimum_required(VERSION 3.16.0)
project(SecureAllocCheckerPlugin)

C++17標準を強制（LLVM/ClangのモダンなAPIを利用するため必須）
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

LLVMパッケージのロード（ホスト環境のLLVMインフラを利用）
find_package(LLVM REQUIRED CONFIG)
find_package(Clang REQUIRED CONFIG)

インクルードパスと定義の統合
include_directories(${LLVM_INCLUDE_DIRS} ${CLANG_INCLUDE_DIRS})
add_definitions(${LLVM_DEFINITIONS})

プラグイン本体をモジュール型ライブラリとしてビルド
add_library(SecureAllocChecker MODULE
SecureAllocChecker.cpp
)

LLVM/Clangのリンク設定（シンボル未解決を防ぐための設定）
target_link_libraries(SecureAllocChecker PRIVATE
clangBasic
clangAST
clangASTMatchers
clangAnalysis
clangStaticAnalyzerCore
clangStaticAnalyzerFrontend
)

プラグインの出力名を設定（libをプレフィックスから外す場合もあるが標準に準拠）
set_target_properties(SecureAllocChecker PROPERTIES
PREFIX “”
SUFFIX “.so”
)

チェッカー実装コード（SecureAllocChecker.cpp）

以下が、Clang Static AnalyzerのAPIを叩いてリソースのライフサイクルを追跡するC++コードです。

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/StaticAnalyzer/Frontend/CheckerRegistry.h”

using namespace clang;
using namespace ento;

namespace {

// 状態追跡用のプログラムステート（ProgramState）を定義するカスタムキー
// どの関数で確保が行われたかをトラッキングする
class SecureAllocChecker : public Checker {
// 検出時に出力するバグの種類
std::unique_ptr LeakBug;

public:
SecureAllocChecker()
: LeakBug(std::make_unique(this, “Resource Leak”, “Custom Security Rules”)) {}

// 関数呼び出し時に特定の関数（secure_alloc / secure_free）を検知するコールバック
void checkCall(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;

ProgramStateRef State = C.getState();

// 1. secure_alloc() が呼ばれた場合の状態遷移
if (II->isStr(“secure_alloc”)) {
// 確保されたというフラグやシンボルをプログラム状態に記録
// ここでは簡易的に「確保済み」の目印を状態に持たせる
State = State->set(true);
C.addTransition(State);
}
// 2. secure_free() が呼ばれた場合の状態遷移
else if (II->isStr(“secure_free”)) {
// 解放されたのでフラグをリセット
State = State->set(false);
C.addTransition(State);
}
}

// 関数のスコープを抜ける瞬間に、リソースが未解放（メモリリーク）になっていないか検証
void checkEndFunction(CheckerContext &C) const {
ProgramStateRef State = C.getState();

// 状態から「確保されたまま解放されていないか」を取得
bool isAllocated = State->get();
if (isAllocated) {
// バグ報告のパスを作成
ExplodedNode ErrorNode = C.generateErrorNode(State);
if (!ErrorNode) return;

auto R = std::make_unique(
LeakBug, “secure_alloc() で確保されたリソースが関数内で secure_free() されていません”, ErrorNode);
C.emitReport(std::move(R));
}
}
};

} // namespace

// ProgramState 内でデータを保持するためのトレーサー定義
REGISTER_STATE_TRAIT(AllocatedState, bool)

// Clangのプラグインシステムへチェッカーを登録するエントリポイント
extern “C” const char clang_analyzerAPIVersionString[] = CLANG_ANALYZER_API_VERSION_STRING;

// Clang 15/16以降の新しいプラグインレジストリインターフェース
void clang_registerCheckers(CheckerRegistry &registry) {
registry.addChecker(
“example.SecureAllocChecker”,
“Ensures secure_alloc is matched with secure_free”,
“”);
}

—

3. チーム開発における静的解析の統制：ビルドパイプラインへの統合

プラグインを作成しても、個人のローカル環境で手動実行しているだけではチーム開発の品質担保には繋がりません。CI/CDパイプラインおよび日常のビルドプロセスにシームレスに組み込む必要があります。

1. 開発効率を最大化する Makefile / 実行スクリプト

Clangの標準アナライザに自作プラグインをロードさせるためのコマンドライン引数は複雑化しがちです。開発者が意識せずとも使えるよう、以下のようなラッパースクリプト（または Makefile）を用意します。

Makefile のベストプラクティス例
CC = clang
PLUGIN_PATH = ./build/SecureAllocChecker.so
CHECKER_NAME = example.SecureAllocChecker

ソースコードの静的解析を実行するターゲット
analyze:
# -Xclang プラグイン引数を経由して独自プラグインをロードし、対象チェッカーを有効化する
$(CC) -Xclang -load -Xclang $(PLUGIN_PATH) \
-Xclang -analyzer-checker=$(CHECKER_NAME) \
–analyze src/main.c

2. コンパイルエラーとしてCIで弾くための設定（JSONコンパイルデータベース）

大規模なCプロジェクトでは、CMakeやBear（Build ear）を用いて `compile_commands.json` を生成し、解析ツールに流し込むのがデファクトスタンダードです。

`.clang-analyzer` やプロジェクトルートの `.clang-format` と並び、静的解析の厳格度を定義する設定ファイル群のベストプラクティス構成を以下に示します。

// .clang-tidy や Static Analyzer の挙動を定義するプロジェクト共通設定例 (json)
{
“Checks”: “,example.SecureAllocChecker”,
“CheckOptions”: [
{
“key”: “example.SecureAllocChecker:StrictMode”,
“value”: “true”
}
],
“WarningsAsErrors”: “example.SecureAllocChecker”
}

  • `Checks`: 標準のClang-Tidy / Static Analyzerの全チェックに加え、自作のプラグインチェッカーを明示的に有効化。
  • `WarningsAsErrors`: 独自ルール違反を「単なる警告」ではなく「ビルドエラー（終了コード非0）」として扱い、CIパイプラインを確実に停止させる。

—

4. 現場で直面するトラブルシューティングとプロの知見

実際にClang Static Analyzerのカスタムチェッカーを本番導入する際、シニアエンジニアが必ずハマる「落とし穴」とその対策を共有します。

罠1：ASTのバージョンアップによるABI破壊

Clangの内部API（ASTやPathSensitiveのノード構造）は、メジャーバージョンアップ（例: Clang 15から16）で破壊的変更が頻繁に入ります。

  • 解決策: プラグインをビルドするコンパイラ（LLVM/Clangのバージョン）と、実際に解析を実行するコンパイラのバージョンをCI環境も含めて完全に一致（Docker等でコンテナ化）させてください。

罠2：偽陽性（False Positive）の爆発

パス感度解析は強力ですが、複雑なポインタ演算やマクロ展開が絡むと、実際には起きえない分岐パスをトレースして誤検知（偽陽性）を出します。

  • 解決策: チェッカーコード内で `C.getBugReporter().isSuppressed(R)` や、アノテーション（例: `#__attribute__((annotate(“custom_safe”)))`）をパースするロジックを挟み、開発者が意図的に解析から除外できるエスケープハッチを必ず設計段階で用意してください。

—

おわりに：コードレビューを「人間が行うべき本質的な議論」へ回帰させる

静的解析の目的は、機械的に検知できるバグや規約違反を人間の脳のメモリから完全に排除することです。
今回紹介したClang Static Analyzerのプラグイン開発は、一見すると学習コストが高く見えるかもしれません。しかし、チーム固有のバグパターンを1つでも自動検出するチェッカーを作り上げれば、それは「二度と同じ種類のバグをプロダクトに混入させない永久不変の盾」を手に入れたことと同義です。

標準の枠組みに縛られず、コンパイラの内部機構までハックして開発環境を最適化する——これこそが、プロダクトのスケールを支える真のエンジニアリングです。ぜひあなたのプロジェクトでも、独自の診断ルールをコードベースに組み込み、開発スピードと品質を極限まで高めてください。

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