Build Error Analyzer Skill

This skill specializes in analyzing OpenHarmony build errors from last_error.log and providing fix recommendations only (no automatic code modifications) based on error patterns and historical case studies.

IMPORTANT: This skill provides analysis and recommendations ONLY. It does NOT automatically modify code files.

⚠️ CRITICAL WORKFLOW (MUST FOLLOW)

YOU MUST ALWAYS FOLLOW THIS EXACT SEQUENCE:

1. FIRST: Extract errors from out/<product>/build.log → generates out/<product>/last_error.log
2. THEN: Read and analyze ONLY from out/<product>/last_error.log
3. NEVER: Read directly from out/<product>/build.log or any other log files (error.log, build_output*.log, etc.)
4. SUCCESS CASE: If last_error.log contains "build success" or "no error", STOP and report success

Why?:

• build.log contains the entire build history (thousands of lines)
• last_error.log contains ONLY the most recent error block (extracted by script)
• Reading build.log directly will give you STALE or IRRELEVANT errors
• The extraction script ensures you always analyze the LATEST errors
• Other log files (error.log, build_output*.log) may contain outdated errors from previous builds

Before reading ANY errors, ALWAYS run:

# ⚠️ CRITICAL: First cd to OpenHarmony root directory, then run the script
cd <openharmony_root>
foundation/arkui/ace_engine/.claude/skills/build-error-analyzer/script/extract_last_error.sh out/<product>/build.log

⚠️ CRITICAL - CHECK FOR SUCCESS FIRST: After reading last_error.log, if you see:

• build success, no error
• no error
• Or similar success messages

IMMEDIATELY STOP and report:

## ✅ 构建成功

最新的构建已经成功完成，没有发现任何错误。

**构建状态**: 成功
**错误信息**: 无

建议: 您可以继续进行开发或测试工作。

DO NOT:

• ❌ Continue searching for errors in other log files
• ❌ Read error.log
• ❌ Read build_output*.log files
• ❌ Look for historical errors

Important Path Information

Always use these paths:

• Extraction Script: foundation/arkui/ace_engine/.claude/skills/build-error-analyzer/script/extract_last_error.sh (relative to OpenHarmony root)
• Source Build Log: out/<product>/build.log (e.g., out/rk3568/build.log) - DO NOT READ DIRECTLY
• Target Error Log: out/<product>/last_error.log (auto-generated in same directory as build.log) - READ ONLY THIS FILE

⚠️ SPECIAL CASE - SDK Build Paths:

• SDK Build Log: out/sdk/build.log (NOT out/ohos-sdk/build.log)
• SDK Error Log: out/sdk/last_error.log (NOT out/ohos-sdk/last_error.log)
• SDK Product Exception: SDK uses out/sdk/ directory instead of out/ohos-sdk/
• Trigger Keywords: "分析SDK的编译错误", "analyze SDK build errors", "check SDK errors"

Workflow:

1. ✅ Extract errors from out/<product>/build.log using the script → creates out/<product>/last_error.log
2. ✅ For SDK: Extract from out/sdk/build.log → creates out/sdk/last_error.log
3. ✅ Analyze errors from the extracted last_error.log ONLY
4. ✅ Provide fix recommendations ONLY - do NOT modify code

Common Mistakes to Avoid:

• ❌ Reading build.log directly (will get stale/wrong errors)
• ❌ Reading error.log (contains outdated errors from previous builds)
• ❌ Reading other log files (build_output*.log, error.*.log, etc.)
• ❌ Continuing to search for errors when last_error.log shows "build success"
• ❌ Analyzing errors without extraction step
• ❌ Running extraction script from wrong directory (MUST be from OpenHarmony root)
• ✅ ALWAYS cd to <openharmony_root> first
• ✅ ALWAYS extract → then read last_error.log ONLY
• ✅ If last_error.log shows success → STOP and report success

Behavior Guidelines

This skill provides ANALYSIS and RECOMMENDATIONS ONLY:

✅ DO:

• Extract errors from build logs
• Analyze and categorize errors
• Match errors against known patterns
• Provide detailed fix recommendations with file paths and line numbers
• Show before/after code examples
• Explain root causes
• Suggest verification steps

❌ DO NOT:

• Use Edit tool to modify code files
• Use Write tool to create or modify files
• Run build commands automatically
• Apply fixes without user confirmation
• Make any changes to the codebase
• Read from log files other than last_error.log (error.log, build_output*.log, error.*.log, etc.)
• Continue searching for errors when build is successful

⚠️ CRITICAL - NEVER SUGGEST CLEARING LTO CACHE:

• ❌ NEVER suggest clearing thinlto-cache directory
• ❌ NEVER suggest clearing llvmcache-* directories
• ❌ NEVER suggest deleting out/obj directory
• ❌ NEVER suggest deleting entire out/ directory
• ❌ NEVER blame LTO cache for build errors
• ❌ NEVER suggest "clean build" as first solution

Why: The user should review and apply fixes manually to maintain control over code changes and understand the modifications. LTO cache issues are extremely rare and clearing caches as first resort masks real problems, wastes rebuild time, and disrupts incremental compilation benefits.

Prerequisites

1. ⚠️ CRITICAL: ALWAYS extract from out/<product>/build.log FIRST before reading
2. Error log location: The skill reads errors ONLY from out/<product>/last_error.log (same directory as build.log)
3. Error extraction: ALWAYS use the extraction script from foundation/arkui/ace_engine/.claude/skills/build-error-analyzer/script/extract_last_error.sh (from OpenHarmony root) to generate/update last_error.log before reading
4. Source build.log: Errors are extracted ONLY from out/<product>/build.log in the OpenHarmony output directory
5. Codebase context: Can be executed from any OpenHarmony directory (ace_engine, root, etc.)
6. ⚠️ SUCCESS CHECK: If last_error.log contains "build success" or "no error", STOP and report success - DO NOT read other log files like error.log, build_output*.log, etc.
7. EXCLUSIVE LOG SOURCE: ONLY read from last_error.log - NEVER from error.log, build_output*.log, error.*.log, or any other log files

Analysis Workflow

Step 1: Extract Latest Error (REQUIRED - ALWAYS DO THIS FIRST)

⚠️ CRITICAL: This step is MANDATORY and must be done BEFORE reading any errors.

Why this is required:

• build.log contains the full build output (old and new errors mixed together)
• Reading it directly will analyze STALE or IRRELEVANT errors
• The extraction script isolates ONLY the most recent error block
• last_error.log is generated in the same directory as build.log

⚠️ IMPORTANT: Always navigate to OpenHarmony root first, then run the script:

# Step 1: Navigate to OpenHarmony root directory
cd <openharmony_root>

# Step 2: Run the extraction script (relative path from root)
# Example for rk3568 product - extract errors from out/rk3568/build.log
foundation/arkui/ace_engine/.claude/skills/build-error-analyzer/script/extract_last_error.sh out/rk3568/build.log

# Example for SDK product - extract errors from out/sdk/build.log (⚠️ SPECIAL CASE: out/sdk/ NOT out/ohos-sdk/)
foundation/arkui/ace_engine/.claude/skills/build-error-analyzer/script/extract_last_error.sh out/sdk/build.log

# Example for other products:
foundation/arkui/ace_engine/.claude/skills/build-error-analyzer/script/extract_last_error.sh out/rk3588/build.log

The script will:

• Extract ONLY the latest error block from out/<product>/build.log
• Output to out/<product>/last_error.log (same directory)
• Show error block size and summary
• Overwrite previous last_error.log if it exists

⚠️ DO NOT SKIP THIS STEP

• Even if last_error.log exists, RE-EXTRACT to get the latest errors
• DO NOT read build.log directly
• DO NOT read other log files (build_output*.log, error.log, error.*.log, etc.)
• ONLY analyze last_error.log after extraction

Step 2: Read and Categorize Errors

⚠️ CRITICAL: Only read last_error.log from out/<product>/ directory in the OpenHarmony output tree.

After extraction, the error log is located at:

• out/<product>/last_error.log (same directory as build.log)

Read the extracted error log:

# Check for last_error.log in common product directories
cat out/rk3568/last_error.log
# or for SDK (⚠️ SPECIAL CASE: out/sdk/ NOT out/ohos-sdk/)
cat out/sdk/last_error.log
# or for other products
cat out/rk3588/last_error.log

⚠️ CRITICAL - CHECK FOR SUCCESS FIRST:

Before any analysis, CHECK if the build succeeded:

If last_error.log contains:

• build success, no error
• no error
• Or similar success messages

IMMEDIATELY STOP and report:

## ✅ 构建成功

最新的构建已经成功完成，没有发现任何错误。

**构建状态**: 成功
**错误信息**: 无

建议: 您可以继续进行开发或测试工作。

DO NOT continue to:

• ❌ Search for errors in error.log
• ❌ Search for errors in build_output*.log
• ❌ Search for errors in error.*.log files
• ❌ Look for historical errors
• ✅ STOP and report success

Only if there are actual errors, proceed to categorize them:

Error Categories:

1. Compilation errors (CXX tasks) - Syntax, missing headers, incomplete types
2. Linker errors (SOLINK/LINK tasks) - Undefined symbols, missing libraries
3. Build system errors - GN/Ninja configuration issues

Step 3: Match Against Known Cases

Compare error patterns against historical cases in references/ directory and provide specific solutions.

Case matching priority:

1. Match by error signature (e.g., "undefined symbol" + "referred by")
2. Match by error context (e.g., "timepicker module" usage)
3. Match by file pattern (e.g., BUILD.gn issues)
4. Provide general guidance if no specific case matches

Step 4: Provide Fix Recommendations (NO Automatic Modifications)

CRITICAL: This step provides recommendations ONLY. Do NOT use Edit/Write tools to modify code.

Based on error type and matched cases, provide:

• Root cause analysis
• Specific file modifications needed (with exact line numbers and code snippets)
• Build system configuration changes (with exact GN file paths)
• Verification steps

Recommended Output Format:

## 构建错误分析

### 错误类型
[编译错误/链接错误/构建系统错误]

### 错误位置
[文件路径:行号]

### 错误信息
[完整的错误消息]

### 根本原因
[详细解释为什么会出现这个错误]

### 修复建议

**文件**: [完整文件路径:行号]

**当前代码**:
```cpp
[错误代码片段]

应修改为:

[正确代码片段]

修改说明: [解释为什么要这样修改]

验证步骤

1. [第一步验证操作]
2. [第二步验证操作]
3. [如何确认修复成功]

参考

[相关的历史案例或文档链接]

**DO NOT**:
- ❌ Use Edit tool to make changes
- ❌ Use Write tool to create/modify files
- ❌ Run build commands automatically

**DO**:
- ✅ Provide clear recommendations with file paths and line numbers
- ✅ Show before/after code snippets
- ✅ Explain why the fix works
- ✅ Suggest verification commands

## Error Patterns and Solutions

### Pattern 1: Undefined Symbol Errors

**Error signature:**

ld.lld: error: undefined symbol: <symbol_name>

referenced by :

**⚠️ CRITICAL ANALYSIS WORKFLOW (MUST FOLLOW IN ORDER):**

When encountering `ld.lld: error: undefined symbol:` linker errors, you MUST follow this sequence:

#### Step 1: Identify Which Library is Failing to Link

Check the error message to determine which library has the undefined symbol:
- Look for the target being built (e.g., `libace.z.so`, `libace_compatible.z.so`, `libarkoala_native_ani.so`, `libace_ndk.z.so`)
- Check which library is referencing the symbol (`>>> referenced by`)

#### Step 2: Apply the Correct Scenario Based on Library Type

**Scenario 1: libace/libace_compatible Main Library Cannot Find Symbol**

**Symptoms:**
- Error occurs when linking `libace.z.so` or `libace_compatible.z.so`
- Symbol is undefined in the main library itself

**Root Cause:**
- Symbol implementation is missing or not compiled
- Method exists but .cpp file not in BUILD.gn

**Solution:**
1. **Check if implementation exists:**
   ```bash
   grep -r "SymbolName" --include="*.cpp" frameworks/

2. If implementation exists, check BUILD.gn:

   grep -r "implementation_file.cpp" frameworks/*/BUILD.gn
   

3. Add .cpp to BUILD.gn:

   • Find where other files in same directory are added
   • Add the missing .cpp to the appropriate source_set
   • Important: Reference files in same directory to find correct source_set
   • DO NOT assume all files go to ace_core_ng_source_set

4. Verify with other files:

   # Find where similar files in same directory are compiled
   find frameworks/core/components_ng/pattern/<pattern_name>/ -name "*.cpp"
   grep "similar_file.cpp" frameworks/core/BUILD.gn
   

Scenario 2: Other Library Links with libace/libace_compatible Dependency

Symptoms:

• Error occurs when linking a library that depends on libace or libace_compatible
• GN file shows deps includes libace/libace_compatible
• Symbol should come from main library

Root Cause:

• Symbol exists in main library but not exported
• Missing ACE_FORCE_EXPORT macro
• Symbol not in libace.map whitelist

⚠️ CRITICAL: Distinguish Non-Template vs Template FIRST

Before applying any solution, determine the type:

undefined symbol error
    ↓
Is it a non-template class method?
    → YES: Use Non-Template Solution (Step 1A)
    → NO: Use Template Solution (Step 1B, see Scenario 3)

Solution (Step-by-Step):

Step 1A: For NON-TEMPLATE class methods ⭐

⚠️ CHECK 1: Does the class have ACE_FORCE_EXPORT?

// Case A: Class WITHOUT ACE_FORCE_EXPORT
class PaddingPropertyF {
    float Width() const;
};

// Case B: Class WITH ACE_FORCE_EXPORT
class ACE_FORCE_EXPORT PaddingPropertyF {
    float Width() const;
};

For Case A (Class WITHOUT export) - PREFERRED METHOD:

• ✅ Add ACE_FORCE_EXPORT to method declaration in header (.h file)
• ❌ DO NOT add to method definition in .cpp file
• Reason: Fine-grained export control, clear API boundaries

Example (PaddingPropertyF case):

// In header file (.h) - Add ACE_FORCE_EXPORT to method declarations
class PaddingPropertyF {
    ACE_FORCE_EXPORT float Width() const;   // ← Add here
    ACE_FORCE_EXPORT float Height() const;  // ← Add here
};

// In implementation file (.cpp) - NO ACE_FORCE_EXPORT here
float PaddingPropertyF::Width() const
{
    return left.value_or(0.0f) + right.value_or(0.0f);
}

float PaddingPropertyF::Height() const
{
    return top.value_or(0.0f) + bottom.value_or(0.0f);
}

For Case B (Class WITH export):

• ✅ NO additional export needed - class export covers all methods
• ❌ DO NOT add ACE_FORCE_EXPORT to individual methods
• Reason: Entire class already exported

Example:

// In header file (.h) - Class already exported
class ACE_FORCE_EXPORT PaddingPropertyF {  // ← Entire class exported
    float Width() const;   // Automatically exported
    float Height() const;  // Automatically exported
};

// In implementation file (.cpp) - No individual exports needed
float PaddingPropertyF::Width() const { /* implementation */ }

Step 1B: For TEMPLATE class methods/functions (see Scenario 3)

Template-specific rules apply - refer to Scenario 3 for detailed steps.

Step 2: Add to libace.map with fine-grained symbol names ⭐

After adding exports, add the symbol to build/libace.map:

# Check if symbol already in libace.map
grep "ClassName" build/libace.map

Required changes:

• ⭐ ALWAYS prefer fine-grained symbol patterns - Export specific methods over entire class
• Add symbol pattern to build/libace.map whitelist
• Use method-level granularity when possible

Example - Regular Methods:

# In build/libace.map
{
  global:
    # ✅ FINE-GRAINED - Export specific methods (PREFERRED for non-template)
    OHOS::Ace::PaddingPropertyF::Width*;
    OHOS::Ace::PaddingPropertyF::Height*;

    # ⚠️ ACCEPTABLE - Export entire class (if class has ACE_FORCE_EXPORT)
    OHOS::Ace::PaddingPropertyF::*;

    # ⚠️ DIFFERENT - Template patterns (use wildcards)
    void?OHOS::Ace::StringUtils::StringSplitter*;  # Template function
    OHOS::Ace::NG::LayoutConstraintT*;             # Template class
  };
}

Why fine-grained for non-templates?

• ⭐ Minimizes exported symbol surface - Only export what's needed
• ⭐ Clearer API boundaries - Explicit about which symbols are public
• ⭐ Reduces symbol conflicts - Smaller export surface = fewer conflicts
• ⭐ Better dependency tracking - Easy to see what's used by other modules
• ⭐ Security - Limits attack surface of exported symbols

Common Mistakes (DO NOT do):

• ❌ Using ClassName::*; when only specific methods are needed
• ❌ Exporting private methods that aren't used externally
• ❌ Forgetting that constructor wildcards match all overloads

Step 3: Verify symbol export:

nm -D out/rk3568/arkui/ace_engine/libace.z.so | grep SymbolName

• If symbol not shown, export failed
• Rebuild after adding ACE_FORCE_EXPORT and libace.map entry

Common mistakes (DO NOT do):

• ❌ DO NOT use ClassName::*; when only specific methods are needed (⚠️ COMMON MISTAKE)
• ❌ DO NOT export all class members when only constructors are undefined
• ❌ DO NOT mix non-template and template rules
• ❌ DO NOT add export to .cpp for non-template methods
• ❌ DO NOT add individual method exports if class already has ACE_FORCE_EXPORT
• ❌ DO NOT use __attribute__((visibility("default"))) directly

⚠️ Example of Common Mistake - Over-Exporting:

// ❌ WRONG - Exports entire class when only constructors needed
OHOS::Ace::VelocityTracker::*;  // Exports ALL members unnecessarily

// ✅ CORRECT - Fine-grained constructor export
OHOS::Ace::VelocityTracker::VelocityTracker*;  // Only constructors

When to use each pattern:

• Use ClassName::MethodName*; for specific methods
• Use ClassName::ClassName*; for all constructor overloads
• Use ClassName::*; ONLY when most/all members are exported (rare)

Scenario 3: Template Function Instantiation Issues

Symptoms:

• Undefined symbol is a template function
• Template uses forward declaration + explicit instantiation in .cpp
• Error shows missing specific template specialization (e.g., StringSplitter<Color>, TransformStrCase<std::string>)

Root Cause:

• New specialization not explicitly instantiated
• Template declaration or implementation missing export macro
• libace.map missing pattern for template instantiation

Solution (3 steps required):

Step 1: Add extern template declaration in header (.h)

Add explicit template declaration for new specialization:

// In header file (.h)
extern template void StringSplitter<Color>(const std::string& source, char delimiter,
    Color (*)(const std::string&), std::vector<Color>& out);

Step 2: Add ACE_FORCE_EXPORT to template function declaration

// In header file (.h) - Template function declaration
template<class T>
ACE_FORCE_EXPORT
void StringSplitter(
    const std::string& source, char delimiter, T (*func)(const std::string&), std::vector<T>& out);

Step 3: Add explicit instantiation in .cpp

// In implementation file (.cpp)
template void StringSplitter<Color>(const std::string& source, char delimiter,
    Color (*)(const std::string&), std::vector<Color>& out);

Step 4: Add ACE_FORCE_EXPORT to template implementation

// In implementation file (.cpp) - Template function implementation
template<class T>
ACE_FORCE_EXPORT
void StringSplitter(
    const std::string& source, char delimiter, T (*func)(const std::string&), std::vector<T>& out)
{
    // implementation
}

Step 5: Add to libace.map whitelist

# In build/libace.map
{
  global:
    OHOS::Ace::StringUtils::*;
    void?OHOS::Ace::StringUtils::StringSplitter*;  # Match template instantiations
    void?OHOS::Ace::StringUtils::TransformStrCase*;  # Match template instantiations
};

⚠️ Template Special Notes:

• Templates require BOTH declaration and implementation to have export macros
• Explicit instantiation must be in .cpp file
• libace.map pattern must use * wildcard to match template instantiations
• Example pattern: void?OHOS::Ace::StringUtils::StringSplitter*;

Scenario 4: Special Libraries (Rare Cases)

Symptoms:

• Library does NOT depend on libace/libace_compatible
• But uses utility functions from main library (previously inline, now in .cpp)
• Only applies to these specific libraries:
  • libarkoala_native_ani.so
  • libace_ndk.z.so

Root Cause:

• Utility functions changed from inline to .cpp implementation
• Symbol not available because library doesn't link main library
• Special case requiring local compilation

Solution:

• Add the utility .cpp file directly to the library's BUILD.gn sources

Example for libarkoala_native_ani:

# In: frameworks/bridge/arkts_frontend/koala_projects/arkoala-arkts/arkui-ohos/src/ani/native/BUILD.gn
ohos_shared_library("arkoala_native_ani") {
  sources = [
    "//foundation/arkui/ace_engine/frameworks/base/utils/string_utils.cpp",
    "UINode/uinode_module_methods.cpp",
    # ... other sources
  ]
}

Example for ace_ndk:

# In: interfaces/native/BUILD.gn
ohos_shared_library("ace_ndk") {
  sources = [
    "//foundation/arkui/ace_engine/frameworks/base/utils/string_utils.cpp",
    "//foundation/arkui/ace_engine/frameworks/core/accessibility/native_interface_accessibility_impl.cpp",
    # ... other sources
  ]
}

⚠️ IMPORTANT:

• This solution is ONLY for libarkoala_native_ani and ace_ndk
• DO NOT use this pattern for other libraries
• These libraries use utility functions but don't link main library

Scenario 5: Template Class Method Export Issues

Symptoms:

• Error occurs when linking a library that depends on libace or libace_compatible
• Undefined symbol is a template class method with explicit instantiation
• Error shows: undefined symbol: ClassName<T>::MethodName(params)
• Template class has ACE_FORCE_EXPORT on struct declaration but methods still not exported

Example Error:

ld.lld: error: undefined symbol: OHOS::Ace::NG::LayoutConstraintT<float>::UpdateSelfMarginSizeWithCheck(OHOS::Ace::NG::OptionalSize<float> const&)
>>> referenced by slider_layout_algorithm.cpp:212

Root Cause:

• Template class struct declaration has ACE_FORCE_EXPORT (e.g., struct ACE_FORCE_EXPORT LayoutConstraintT)
• But individual method implementations in .cpp file lack ACE_FORCE_EXPORT macro
• Template explicit instantiation doesn't export individual methods automatically
• Each method implementation that needs to be exported must have the macro

Solution:

Step 1: Add ACE_FORCE_EXPORT to method implementation in .cpp

Add ACE_FORCE_EXPORT to each template method implementation that needs to be exported:

// In implementation file (.cpp)
template<typename T>
ACE_FORCE_EXPORT  // ← Add this macro before return type
bool LayoutConstraintT<T>::UpdateSelfMarginSizeWithCheck(const OptionalSize<T>& size)
{
    if (selfIdealSize == size) {
        return false;
    }
    return selfIdealSize.UpdateSizeWithCheck(size);
}

template<typename T>
ACE_FORCE_EXPORT  // ← Add this macro before return type
bool LayoutConstraintT<T>::UpdateMaxSizeWithCheck(const SizeT<T>& size)
{
    if (maxSize == size) {
        return false;
    }
    return maxSize.UpdateSizeWhenSmaller(size);
}

⚠️ Template Method Export Notes:

• Struct declaration export is NOT enough: Having struct ACE_FORCE_EXPORT LayoutConstraintT doesn't automatically export all methods
• Each method needs macro: Every method implementation in .cpp that must be exported needs ACE_FORCE_EXPORT
• Place macro before return type: The macro goes between template<> and return type
• Not needed in header: Don't add ACE_FORCE_EXPORT to method declarations in header file (struct declaration is sufficient)

Step 2: Verify libace.map has wildcard pattern

Check that libace.map includes the template class with wildcard: