openharmonyinsight/compile-analysis

Compilation Efficiency Analysis Skill

Analyze compilation efficiency for individual source files in the ACE Engine project. This skill provides detailed insights into compilation time, resource overhead, and header file dependencies to help identify optimization opportunities.

Overview

Compilation analysis helps identify performance bottlenecks in the build process by measuring:

• Compilation time - How long a file takes to compile
• Resource overhead - Peak memory usage during compilation
• Header dependencies - Tree structure of included headers

Critical Requirements:

• ⚠️ The analyze_compile.sh script can be executed from the current project directory
• ⚠️ Extracted compilation commands MUST be executed in the out/{product} directory (not from the project root)
• ⚠️ All analysis results MUST be based on actual execution - no speculation or estimation
• ⚠️ Header dependencies MUST be parsed using the built-in parse_ii.py script to analyze .ii files - do not use alternative methods

Use this analysis when:

• Investigating slow compilation times
• Identifying files with excessive dependencies
• Optimizing build performance
• Understanding include relationships

Analysis Workflow

Step 1: Locate Source File

Identify the target source file for analysis. Source files in ace_engine typically follow patterns:

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

Step 2: Find OpenHarmony Root

The analysis scripts automatically locate the OpenHarmony root directory by searching for the .gn file marker. Navigate to the OpenHarmony root directory to ensure proper path resolution.

Step 3: Choose Analysis Mode

Option A: Full Analysis (Execute + Display Results)

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

Example:

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

Option B: Save Reusable Compilation Script

Generate a standalone script that can be executed multiple times for performance testing:

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

This creates out/{product}/compile_single_file_{name}.sh with:

• Automatic environment setup
• Performance monitoring (time + memory)
• Generation of .ii and .o files
• Repeatable execution for benchmarking

Step 4: Interpret Results

The analysis produces three key outputs:

1. Compilation command - Full compiler command with all flags
2. Performance metrics:
   • Elapsed time (format: MM:SS.mm)
   • Peak memory usage in KB
3. Dependency tree - Hierarchical view of header inclusions

When using --save-script, a reusable script is generated for repeated performance testing.

Key Scripts

analyze_compile.sh (Main Script)

Primary entry point for compilation analysis. Orchestrates the entire analysis workflow:

Usage:

# 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

Arguments:

• source-file - Path to the source file (relative to ace_engine root or absolute)
• product-name - Target product (default: rk3568)
• --save-script - Save enhanced compilation command to reusable script file

Workflow:

1. Extracts compilation command from ninja build files
2. Generates enhanced compilation command with instrumentation
3. (Optional) Saves script to out/{product}/compile_single_file_{name}.sh
4. Executes compilation with time and memory profiling
5. Parses .ii preprocessed file to extract dependencies
6. Displays comprehensive results

Output with --save-script:

• Generates a standalone bash script at out/{product}/compile_single_file_{name}.sh
• Script includes automatic environment setup
• Performance monitoring (compilation time + peak memory)
• Can be executed multiple times for performance comparisons
• Useful for benchmarking and optimization validation

get_compile_command.py

Extracts the complete compilation command for a source file from the ninja build system.

Usage (from ace_engine root):

# 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

Example:

# 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

Features:

• Parses ninja build files to locate compilation rules
• Extracts compiler flags, defines, and include paths
• Generates two versions:
  1. Original command (with ccache for development)
  2. Enhanced command (without ccache, with -save-temps for analysis)
• Can save commands to standalone scripts for repeated execution

Output:

• Original compilation command
• Enhanced compilation command with instrumentation
• Optional: Saved script files for reuse
  • --save: Creates {file}_compile_command.sh (original command)
  • --save-enhanced: Creates compile_single_file_{file}.sh (enhanced with monitoring)

parse_ii.py

Analyzes .ii preprocessed files to extract and display header file dependencies.

Usage:

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

Features:

• Parses .ii files (preprocessed C++ source)
• Extracts #include directives targeting foundation/arkui/
• Builds dependency tree structure
• Displays tree with Unicode box-drawing characters

Output Format:

头文件的依赖关系树：
└── 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
        └── ...

Understanding the Results

Compilation Time

Format: MM:SS.mm (minutes:seconds.milliseconds)

• Fast: < 5 seconds (typical for small files)
• Moderate: 5-15 seconds
• Slow: > 15 seconds (may indicate optimization opportunities)

Peak Memory

Reported in kilobytes (KB)

• Typical: 100,000 - 500,000 KB (100-500 MB)
• High: > 500,000 KB - may indicate excessive template instantiation or header dependencies

Dependency Tree

The tree shows hierarchical include relationships:

• Each level represents an #include directive
• Multiple children indicate multiple includes in a file
• Deep trees suggest heavy dependency chains

Optimization indicators:

• Wide trees (many direct includes) - Consider header consolidation
• Deep trees (long chains) - Look for circular dependencies or excessive forwarding
• Duplicate paths - Header guards missing or include order issues

Common Use Cases

Analyzing Header File Dependencies

When you need to analyze the header file dependency structure of a source file:

Important: This workflow ONLY uses .ii files generated by compilation scripts. No other dependency analysis methods are used.

Workflow:

1. Check if .ii file exists in out/{product}/obj/ directory
2. If .ii exists → Parse it directly with parse_ii.py
3. If .ii doesn't exist → Generate it using compilation script, then parse
4. Always save the dependency tree to out/{product}/{file_name}_dependency_tree.txt

Example using 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

If .ii file doesn't exist:

# 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 层

If neither .ii nor script exists:

# 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

Trigger phrases:

• "分析这个文件的头文件依赖"
• "头文件依赖关系"
• "这个文件依赖了多少头文件"
• "analyze header dependencies"
• "header dependency tree"
• "how many header files"

Output file naming:

• Format: {file_name}_dependency_tree.txt
• Location: out/{product}/
• Example: out/rk3568/frame_node_dependency_tree.txt

Constraints:

• ✅ MUST parse .ii files using parse_ii.py
• ✅ MUST use compilation scripts to generate .ii if needed
• ✅ MUST save dependency tree to out/{product}/{file_name}_dependency_tree.txt
• ❌ DO NOT use other dependency analysis tools (like clang -E, gcc -M, etc.)
• ❌ DO NOT attempt manual dependency parsing

Standalone Compilation of Individual Files

When you need to compile a single file in isolation (for testing, debugging, or verification):

Important: This workflow ONLY uses pre-generated compilation scripts. No other compilation methods are used.

Workflow:

1. Check if compilation script exists: out/{product}/compile_single_file_{name}.sh
2. If script exists → Execute it directly
3. If script doesn't exist → Generate it first, then execute

Example using 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

If script doesn't exist:

# 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

Trigger phrases:

• "单独编译这个文件"
• "编译单个文件"
• "单编文件"
• "独立编译文件"
• "compile single file"
• "compile individual file"
• "standalone compile"

Constraints:

• ✅ MUST use existing compile_single_file_{name}.sh scripts
• ✅ MUST generate script if it doesn't exist before compilation
• ❌ DO NOT use ninja, make, or other build tools directly
• ❌ DO NOT attempt manual compilation commands

Extracting and Saving Compilation Commands

When you need to extract or save compilation commands for later use:

Save standalone script with performance monitoring:

./.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

Extract command only without execution:

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

This is useful for:

• Creating reusable compilation scripts
• Setting up performance benchmarking
• Generating reproducible build environments
• Isolating specific file compilation for testing

Investigating Slow Builds

When incremental builds are slower than expected:

1. Identify slow-compiling files by reviewing build log timestamps
2. Run analysis on slow files: ./analyze_compile.sh <slow-file>
3. Check dependency tree depth and breadth
4. Look for frequently included heavy headers

Optimizing Header Dependencies

To reduce unnecessary recompilation:

1. Analyze dependency tree for common patterns
2. Identify headers included by many files
3. Consider forward declarations instead of full includes
4. Use precompiled headers (PCH) for stable dependencies

Before/After Comparisons

Measure optimization impact using saved scripts:

1. Generate baseline script:

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

2. Run baseline measurement:

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

3. Apply optimizations (reduce includes, forward declarations, etc.)

4. Run comparison measurement:

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

5. Compare results to quantify improvements

The saved script ensures identical compilation conditions for fair comparison.

Troubleshooting

Issue: "找不到编译规则" (Compilation rule not found)

Cause: Source file path doesn't match build database Solutions:

• Ensure the file is in the ace_engine directory structure
• Check if the file has been built before (run full build first)
• Verify path format: use relative path from ace_engine root

Issue: "找不到 .ii 文件" (.ii file not found)

Cause: Compilation with -save-temps failed or file not created Solutions:

• Check if enhanced compilation command succeeded
• Verify compiler supports -save-temps=obj flag
• Manually search obj directory: find out/<product>/obj -name "*.ii"

Issue: Dependency tree shows few files

Cause: parse_ii.py filters for foundation/arkui/ prefix only Solutions:

• This is expected behavior - focuses on arkui-specific headers
• System headers are intentionally excluded
• Modify target_prefix in parse_ii.py to include other paths

Best Practices

• Start with full build: Ensure project has been built at least once
• Use relative paths: Provide paths relative to ace_engine root
• Product-specific analysis: Specify product name if not using default rk3568
• Compare benchmarks: Track changes over time with saved results
• Focus on hot paths: Prioritize analysis on frequently modified files

Additional Resources

Reference Files

For detailed workflows and advanced usage:

• references/workflow.md - Comprehensive workflow guide
• references/optimization.md - Optimization strategies and patterns

Example Files

Working examples in examples/:

• examples/example-analysis.sh - Complete analysis example
• examples/example-output.txt - Sample output with interpretation

Integration with Build System

This skill integrates with the OpenHarmony GN/Ninja build system:

• Reads build metadata from out/<product>/ directory
• Parses toolchain.ninja for compiler rules
• Extracts file-specific compilation commands from ninja files
• Generates instrumentation-compatible commands for analysis

The enhanced compilation command modifies the original command by:

1. Removing ccache (to get accurate timing)
2. Adding -save-temps=obj (to generate .ii files)
3. Wrapping with /usr/bin/time (to measure resources)
4. Suppressing related warnings (-Wno-undefined-bool-conversion)

This ensures accurate measurements while maintaining compilation compatibility.