compile-analysis

コンパイル効率分析スキル

ACE Engine プロジェクトの個々のソースファイルについて、コンパイル効率を分析します。このスキルでは、コンパイル時間、リソースのオーバーヘッド、ヘッダーファイルの依存関係を詳しく把握し、最適化の機会を見つけるのに役立ちます。

概要

コンパイル分析では、次の項目を測定して、ビルドプロセスのパフォーマンスのボトルネックを特定します。

• コンパイル時間 - ファイルのコンパイルにかかる時間
• リソースのオーバーヘッド - コンパイル中のピークメモリ使用量
• ヘッダー依存関係 - インクルードされたヘッダーのツリー構造

重要な要件：

• ⚠️ analyze_compile.sh スクリプトは、現在のプロジェクトディレクトリから実行できます
• ⚠️ 抽出したコンパイルコマンドは、out/{product} ディレクトリで実行する必要があります（プロジェクトのルートから実行しないでください）
• ⚠️ すべての分析結果は実際の実行に基づく必要があります。推測や見積もりは使用しないでください
• ⚠️ ヘッダー依存関係は、組み込みの parse_ii.py スクリプトを使用して .ii ファイルを解析する必要があります。代替手段は使用しないでください

次のような場合に、この分析を使用します。

• コンパイル時間が遅い原因を調査する
• 依存関係が過剰なファイルを特定する
• ビルドのパフォーマンスを最適化する
• インクルード関係を把握する

分析ワークフロー

ステップ 1：ソースファイルを特定する

分析対象のソースファイルを特定します。ace_engine のソースファイルには、通常、次のようなパターンがあります。

• frameworks/core/components_ng/base/frame_node.cpp
• frameworks/bridge/declarative_frontend/engine/js_engine.cpp

ステップ 2：OpenHarmony のルートを探す

分析スクリプトは、.gn ファイルのマーカーを検索して、OpenHarmony のルートディレクトリを自動的に特定します。パスを正しく解決できるように、OpenHarmony のルートディレクトリに移動してください。

ステップ 3：分析モードを選択する

オプション A：完全な分析（実行して結果を表示）

./.claude/skills/compile-analysis/scripts/analyze_compile.sh <source-file> [product-name]

例：

./.claude/skills/compile-analysis/scripts/analyze_compile.sh frameworks/core/components_ng/base/frame_node.cpp rk3568

オプション B：再利用可能なコンパイルスクリプトを保存する

パフォーマンステストのために複数回実行できる、独立したスクリプトを生成します。

./.claude/skills/compile-analysis/scripts/analyze_compile.sh <source-file> [product-name] --save-script

これにより、次の内容を含む out/{product}/compile_single_file_{name}.sh が作成されます。

• 環境の自動セットアップ
• パフォーマンスのモニタリング（時間とメモリ）
• .ii ファイルと .o ファイルの生成
• ベンチマークのための繰り返し実行

ステップ 4：結果を解釈する

分析では、次の 3 つの主な出力が得られます。

1. コンパイルコマンド - すべてのフラグを含むコンパイラの完全なコマンド
2. パフォーマンス指標：
   • 経過時間（形式：MM:SS.mm）
   • ピークメモリ使用量（KB）
3. 依存関係ツリー - ヘッダーのインクルードを階層表示

--save-script を使用すると、パフォーマンステストを繰り返すための再利用可能なスクリプトが生成されます。

主なスクリプト

analyze_compile.sh（メインスクリプト）

コンパイル分析の主なエントリーポイントです。分析ワークフロー全体を実行します。

使用方法：

# Full analysis with execution
./.claude/skills/compile-analysis/scripts/analyze_compile.sh <source-file> [product-name]

# Save standalone compilation script
./.claude/skills/compile-analysis/scripts/analyze_compile.sh <source-file> [product-name] --save-script

引数：

• source-file - ソースファイルのパス（ace_engine のルートからの相対パス、または絶対パス）
• product-name - 対象製品（デフォルト：rk3568）
• --save-script - 拡張されたコンパイルコマンドを再利用可能なスクリプトファイルに保存する

ワークフロー：

1. ninja のビルドファイルからコンパイルコマンドを抽出します
2. インストルメンテーションを含む拡張コンパイルコマンドを生成します
3. （任意）スクリプトを out/{product}/compile_single_file_{name}.sh に保存します
4. 時間とメモリのプロファイリングを行いながらコンパイルを実行します
5. .ii プリプロセス済みファイルを解析して、依存関係を抽出します
6. 詳細な結果を表示します

--save-script の出力：

• out/{product}/compile_single_file_{name}.sh に独立した bash スクリプトを生成します
• スクリプトには環境の自動セットアップが含まれます
• パフォーマンスをモニタリングします（コンパイル時間とピークメモリ）
• パフォーマンスを比較するために、複数回実行できます
• ベンチマークと最適化の検証に役立ちます

get_compile_command.py

ninja ビルドシステムから、ソースファイルの完全なコンパイルコマンドを抽出します。

使用方法（ace_engine のルートディレクトリから）：

# Display commands only
python3 ./.claude/skills/compile-analysis/scripts/get_compile_command.py \
  <source-file> <openharmony_root>/out/<product>

# Save enhanced command (with performance monitoring)
python3 ./.claude/skills/compile-analysis/scripts/get_compile_command.py \
  <source-file> <openharmony_root>/out/<product> --save-enhanced

例：

# From ace_engine directory
python3 ./.claude/skills/compile-analysis/scripts/get_compile_command.py \
  frameworks/core/components_ng/base/frame_node.cpp \
  /home/sunfei/workspace/openHarmony/out/rk3568 --save-enhanced

機能：

• ninja のビルドファイルを解析し、コンパイルルールを特定します
• コンパイラーフラグ、定義、インクルードパスを抽出します
• 次の 2 種類のコマンドを生成します：
  1. 元のコマンド（開発用の ccache を使用）
  2. 拡張コマンド（ccache を使用せず、解析用の -save-temps を指定）
• コマンドを単独で実行できるスクリプトに保存できます。繰り返し実行する場合に便利です

出力：

• 元のコンパイルコマンド
• 計測機能を追加した拡張コンパイルコマンド
• オプション：再利用可能な保存済みスクリプトファイル
  • --save：{file}_compile_command.sh（元のコマンド）を作成します
  • --save-enhanced：compile_single_file_{file}.sh（監視機能を追加した拡張コマンド）を作成します

parse_ii.py

.ii プリプロセス済みファイルを解析し、ヘッダーファイルの依存関係を抽出して表示します。

使用方法：

python3 ./.claude/skills/compile-analysis/scripts/parse_ii.py <ii-file>

機能：

• .ii ファイル（プリプロセス済みの C++ ソース）を解析します
• foundation/arkui/ を対象とする #include ディレクティブを抽出します
• 依存関係ツリーを構築します
• Unicode の罫線文字を使ってツリーを表示します

出力形式：

头文件的依赖关系树：
└── foundation/arkui/ace_engine/frameworks/core/components_ng/base/frame_node.h
    └── foundation/arkui/ace_engine/frameworks/core/components_ng/base/ui_node.h
        ├── foundation/arkui/ace_engine/frameworks/core/pipeline/base/element.h
        └── ...

結果の見方

コンパイル時間

形式：MM:SS.mm（分：秒.ミリ秒）

• 高速：5 秒未満（小さなファイルで一般的）
• 中程度：5～15 秒
• 低速：15 秒超（最適化の余地がある可能性があります）

ピークメモリ

キロバイト（KB）単位で表示されます

• 一般的：100,000～500,000 KB（100～500 MB）
• 高い：500,000 KB 超。テンプレートの過剰なインスタンス化やヘッダー依存関係が原因の可能性があります

依存関係ツリー

このツリーは、階層的なインクルード関係を示します：

• 各階層は 1 つの #include ディレクティブを表します
• 子ノードが複数ある場合、そのファイルに複数のインクルードがあることを示します
• ツリーが深い場合、依存関係の連鎖が複雑であることを示します

最適化の指標：

• 幅の広いツリー（直接のインクルードが多い）— ヘッダーの統合を検討してください
• 深いツリー（長い連鎖）— 循環依存や過剰な転送がないか確認してください
• 重複パス — ヘッダーガードの欠如やインクルード順序の問題が考えられます

一般的なユースケース

ヘッダーファイルの依存関係を分析する

ソースファイルのヘッダーファイル依存関係の構造を分析する必要がある場合：

重要：このワークフローでは、コンパイルスクリプトで生成した .ii ファイルのみを使用します。他の依存関係分析方法は使用しません。

ワークフロー：

1. out/{product}/obj/ ディレクトリに .ii ファイルがあるか確認します
2. .ii ファイルがある場合 → parse_ii.py で直接解析します
3. .ii ファイルがない場合 → コンパイルスクリプトで生成してから解析します
4. 依存関係ツリーは必ず out/{product}/{file_name}_dependency_tree.txt に保存します

Claude を使った例：

# User request: "分析 frame_node.cpp 的头文件依赖"
# Claude's response:

# Step 1: Check for existing .ii file
# ✓ Found: out/rk3568/obj/.../frame_node.ii

# Step 2: Parse .ii file and save dependency tree
python3 ./.claude/skills/compile-analysis/scripts/parse_ii.py \
  out/rk3568/obj/.../frame_node.ii \
  --output out/rk3568/frame_node_dependency_tree.txt

# Output:
# 头文件的依赖关系树：
# └── foundation/arkui/ace_engine/frameworks/core/components_ng/base/frame_node.h
#     ├── foundation/arkui/ace_engine/frameworks/core/components_ng/base/ui_node.h
#     │   ├── foundation/arkui/ace_engine/frameworks/core/pipeline/base/element.h
#     │   └── foundation/arkui/ace_engine/base/memory/ace_type.h
#     └── foundation/arkui/ace_engine/frameworks/core/components_ng/property/property.h
#
# ✓ 依赖树已保存到: out/rk3568/frame_node_dependency_tree.txt

.ii ファイルがない場合：

# User request: "这个文件依赖了多少头文件 text_theme.cpp"
# Claude's response:

# Step 1: Check for existing .ii file
# ✗ .ii file not found

# Step 2: Check for compilation script
# ✓ Found: out/rk3568/compile_single_file_text_theme.sh

# Step 3: Generate .ii file by running compilation script
cd out/rk3568
bash compile_single_file_text_theme.sh

# Step 4: Parse .ii file and save dependency tree
python3 ../../.claude/skills/compile-analysis/scripts/parse_ii.py \
  obj/.../text_theme.ii \
  --output text_theme_dependency_tree.txt

# Output:
# 头文件的依赖关系树：
# └── foundation/arkui/ace_engine/frameworks/core/components/text/text_theme.h
#     ├── ...
#
# ✓ 依赖树已保存到: out/rk3568/text_theme_dependency_tree.txt
#
# 统计信息:
# - 总计依赖: 47 个头文件
# - 最大深度: 6 层

.ii ファイルもスクリプトもない場合：

# User request: "头文件依赖关系 button_pattern.cpp"
# Claude's response:

# Step 1: Check for existing .ii file
# ✗ .ii file not found

# Step 2: Check for compilation script
# ✗ Compilation script not found

# Step 3: Generate compilation script first
python3 ./.claude/skills/compile-analysis/scripts/get_compile_command.py \
  frameworks/core/components_ng/pattern/button_pattern.cpp \
  <openharmony_root>/out/rk3568 --save-enhanced

# ✓ Script generated: out/rk3568/compile_single_file_button_pattern.sh

# Step 4: Generate .ii file by running script
cd out/rk3568
bash compile_single_file_button_pattern.sh

# Step 5: Parse .ii file and save dependency tree
python3 ../../.claude/skills/compile-analysis/scripts/parse_ii.py \
  obj/.../button_pattern.ii \
  --output button_pattern_dependency_tree.txt

# ✓ 依赖树已保存到: out/rk3568/button_pattern_dependency_tree.txt

トリガーフレーズ：

• "このファイルのヘッダー依存関係を分析"
• "ヘッダーの依存関係"
• "このファイルはヘッダーファイルにいくつ依存しているか"
• "ヘッダー依存関係を分析"
• "ヘッダー依存関係ツリー"
• "ヘッダーファイルはいくつか"

出力ファイル名：

• 形式：{file_name}_dependency_tree.txt
• 場所：out/{product}/
• 例：out/rk3568/frame_node_dependency_tree.txt

制約：

• ✅ parse_ii.py を使って .ii ファイルを解析する必要があります
• ✅ 必要な場合はコンパイルスクリプトを使って .ii ファイルを生成する必要があります
• ✅ 依存関係ツリーを out/{product}/{file_name}_dependency_tree.txt に保存する必要があります
• ❌ 他の依存関係分析ツール（clang -E、gcc -M など）は使用しないでください
• ❌ 依存関係を手動で解析しないでください

個別ファイルの単独コンパイル

テスト、デバッグ、検証などのために、単一ファイルを単独でコンパイルする必要がある場合：

重要：このワークフローでは、事前生成されたコンパイルスクリプトのみを使用します。それ以外のコンパイル方法は使用しません。

ワークフロー：

1. コンパイルスクリプトが存在するか確認します：out/{product}/compile_single_file_{name}.sh
2. スクリプトが存在する場合 → 直接実行します
3. スクリプトが存在しない場合 → 先に生成してから実行します

Claude を使用する例：

# User request: "单独编译 frame_node.cpp"
# Claude's response:

# Step 1: Check for existing script
# ✓ Found: out/rk3568/compile_single_file_frame_node.sh

# Step 2: Execute the script
cd out/rk3568
bash compile_single_file_frame_node.sh

# Output:
# 编译时间: 0:08.23
# 峰值内存: 234567 KB
# ✓ 已生成: obj/.../frame_node.ii obj/.../frame_node.o

スクリプトが存在しない場合：

# User request: "单编 text_theme.cpp"
# Claude's response:

# Step 1: Check for existing script
# ✗ Script not found: out/rk3568/compile_single_file_text_theme.sh

# Step 2: Generate script first
python3 ./.claude/skills/compile-analysis/scripts/get_compile_command.py \
  frameworks/core/components/text/text_theme.cpp <openharmony_root>/out/rk3568 --save-enhanced

# ✓ Script generated: out/rk3568/compile_single_file_text_theme.sh

# Step 3: Execute the script
cd out/rk3568
bash compile_single_file_text_theme.sh

トリガーフレーズ：

• 「このファイルを単独でコンパイル」
• 「単一ファイルをコンパイル」
• 「ファイルを単独コンパイル」
• 「ファイルを個別にコンパイル」
• "compile single file"
• "compile individual file"
• "standalone compile"

制約：

• ✅ 既存の compile_single_file_{name}.sh スクリプトを必ず使用してください
• ✅ コンパイル前にスクリプトが存在しない場合は、必ず生成してください
• ❌ ninja、make、その他のビルドツールを直接使用しないでください
• ❌ 手動のコンパイルコマンドを実行しないでください

コンパイルコマンドの抽出と保存

後で使用するためにコンパイルコマンドを抽出または保存する必要がある場合：

パフォーマンス監視機能付きの単独スクリプトを保存：

./.claude/skills/compile-analysis/scripts/analyze_compile.sh \
  frameworks/core/components_ng/base/frame_node.cpp rk3568 --save-script

# Script saved to: out/rk3568/compile_single_file_frame_node.sh
# Execute later: cd out/rk3568 && bash compile_single_file_frame_node.sh

実行せずにコマンドのみを抽出：

python3 ./.claude/skills/compile-analysis/scripts/get_compile_command.py \
  frameworks/core/components_ng/base/frame_node.cpp \
  <openharmony_root>/out/rk3568 --save-enhanced

以下の用途に役立ちます：

• 再利用可能なコンパイルスクリプトの作成
• パフォーマンスベンチマークの設定
• 再現可能なビルド環境の生成
• テスト用に特定ファイルのコンパイルを分離

ビルドが遅い場合の調査

インクリメンタルビルドが予想より遅い場合：

1. ビルドログのタイムスタンプを確認し、コンパイルに時間がかかるファイルを特定します
2. 時間のかかるファイルを分析します：./analyze_compile.sh <slow-file>
3. 依存関係ツリーの深さと幅を確認します
4. 頻繁にインクルードされる大きなヘッダーを調べます

ヘッダー依存関係の最適化

不要な再コンパイルを減らすには：

1. 依存関係ツリーを分析し、共通のパターンを確認します
2. 多数のファイルからインクルードされているヘッダーを特定します
3. ヘッダー全体のインクルードではなく、前方宣言を検討します
4. 安定した依存関係にはプリコンパイル済みヘッダー（PCH）を使用します

最適化前後の比較

保存したスクリプトを使用して最適化の効果を測定します：

1. ベースラインスクリプトを生成：

   ./analyze_compile.sh <file> rk3568 --save-script
   cd out/rk3568
   

2. ベースライン測定を実行：

   bash compile_single_file_{name}.sh
   # Record: 编译时间: 0:15.23, 峰值内存: 456789 KB
   

3. 最適化を適用（インクルードの削減、前方宣言など）

4. 比較測定を実行：

   bash compile_single_file_{name}.sh
   # Record: 编译时间: 0:08.45, 峰值内存: 234567 KB
   

5. 結果を比較し、改善度を定量化します

保存したスクリプトにより、比較に適した同一のコンパイル条件を確保できます。

トラブルシューティング

問題：「コンパイルルールが見つかりません」（Compilation rule not found）

原因：ソースファイルのパスがビルドデータベースと一致していません 解決策：

• ファイルが ace_engine のディレクトリ構造内にあることを確認します
• ファイルが以前にビルドされているか確認します（先にフルビルドを実行します）
• パスの形式を確認します：ace_engine のルートからの相対パスを使用します

問題：「.ii ファイルが見つかりません」（.ii file not found）

原因：-save-temps を指定したコンパイルが失敗したか、ファイルが作成されていません 解決策：

• 拡張コンパイルコマンドが正常に実行されたか確認します
• コンパイラが -save-temps=obj フラグに対応しているか確認します
• obj ディレクトリを手動で検索します：find out/<product>/obj -name "*.ii"

問題：依存関係ツリーに表示されるファイルが少ない

原因：parse_ii.py は foundation/arkui/ プレフィックスのみを対象にフィルタリングしています 解決策：

• これは想定された動作です。arkui 固有のヘッダーに焦点を当てています
• システムヘッダーは意図的に除外されています
• 他のパスを含めるには、parse_ii.py の target_prefix を変更します

ベストプラクティス

• フルビルドから開始する：プロジェクトが少なくとも一度はビルドされていることを確認します
• 相対パスを使用する：ace_engine のルートからの相対パスを指定します
• 製品別に分析する：デフォルトの rk3568 を使用しない場合は、製品名を指定します
• ベンチマークを比較する：保存した結果を使って、時間経過に伴う変更を追跡します
• ホットパスに焦点を当てる：頻繁に変更されるファイルを優先して分析します

追加リソース

参照ファイル

詳細なワークフローと高度な使い方については、以下を参照してください：

• references/workflow.md - 包括的なワークフローガイド
• references/optimization.md - 最適化戦略とパターン

サンプルファイル

examples/ に実行可能なサンプルがあります：

• examples/example-analysis.sh - 分析の完全なサンプル
• examples/example-output.txt - 解釈付きの出力サンプル

ビルドシステムとの統合

このスキルは OpenHarmony GN/Ninja ビルドシステムと統合されます：

• out/<product>/ ディレクトリからビルドメタデータを読み取ります
• toolchain.ninja を解析してコンパイラのルールを読み取ります
• ninja ファイルからファイル単位のコンパイルコマンドを抽出します
• 分析用の計測に対応したコマンドを生成します

拡張コンパイルコマンドは、元のコマンドを次のように変更します：

1. ccache を削除します（正確な時間を計測するため）
2. -save-temps=obj を追加します（.ii ファイルを生成するため）
3. /usr/bin/time でラップします（リソースを測定するため）
4. 関連する警告を抑制します（-Wno-undefined-bool-conversion）

これにより、コンパイルとの互換性を維持しながら、正確な測定が可能になります。