openharmonyinsight/ohos-app-build-debug

OHOS App Build & Debug

When to Use This Skill

Use this skill when the user needs to work with HarmonyOS/OpenHarmony applications:

• Building: "Build my OHOS app", "Compile the project", "Run hvigorw"
• Installing: "Install this HAP", "Deploy to device", "Install app to device"
• Launching: "Launch the app", "Start the application", "Run on device"
• Debugging: "Take screenshot", "Parse crash stack", "Debug crash"
• Environment: "Check DevEco Studio", "Show SDK path", "Verify tools", "Detect environment"

Quick Start

Build, install, and launch an OHOS application:

# Run scripts from skill directory
python3 $SKILL_DIR/scripts/build.py
python3 $SKILL_DIR/scripts/install.py -f entry/build/default/outputs/default/entry-default-signed.hap
python3 $SKILL_DIR/scripts/launch.py

Bundled Resources

This skill includes executable scripts in scripts/ that automatically detect DevEco Studio environment:

| Script | Purpose | |--------|---------| | build.py | Build OHOS application using hvigorw | | install.py | Install HAP file to connected device | | launch.py | Launch installed application | | screenshot.py | Capture device screenshot | | parse_crash.py | Parse crash stack using hstack | | env_detector.py | Detect DevEco Studio and tools | | ohos_utils.py | Shared utility functions |

For detailed command reference, see references/command-reference.md.

Common Workflows

Build and Install

# 1. Check environment
python3 $SKILL_DIR/scripts/env_detector.py

# 2. Build the application
python3 $SKILL_DIR/scripts/build.py

# 3. Install to device (output from build.py shows HAP path)
python3 $SKILL_DIR/scripts/install.py -f entry/build/default/outputs/default/entry-default-signed.hap

# 4. Launch the app
python3 $SKILL_DIR/scripts/launch.py

One-line Build, Install, Launch

python3 $SKILL_DIR/scripts/build.py && \
python3 $SKILL_DIR/scripts/install.py -f $(find entry/build -name "*.hap" | head -1) && \
python3 $SKILL_DIR/scripts/launch.py

Debug Workflow

# Launch app
python3 $SKILL_DIR/scripts/launch.py

# Take screenshot to verify
python3 $SKILL_DIR/scripts/screenshot.py -o ./screenshots

Crash Analysis

# Parse crash stack from file
python3 $SKILL_DIR/scripts/parse_crash.py -f crash.txt

# Parse from string
python3 $SKILL_DIR/scripts/parse_crash.py -c "stack trace here"

How It Works

Automatic Environment Detection

All scripts automatically detect DevEco Studio installation and configure the environment:

1. DevEco Studio Detection

   • Windows: C:\Program Files\Huawei\DevEco Studio\
   • macOS: /Applications/DevEco-Studio.app/
   • Linux: ~/DevEco-Studio/ or /opt/DevEco-Studio/

2. Toolchain Configuration

   • Sets JAVA_HOME to DevEco's bundled JBR
   • Adds SDK tools to PATH
   • Configures HDC_SERVER_PORT=7035
   • Caches detection result for 24 hours

3. Auto-Detected Tools

   • Core: hdc, hvigorw, java
   • LLVM: clang, clang++, lld, llvm-*
   • Profiler: hiprofiler, hiperf
   • Other: hstack, ohpm, idl, restool, syscap_tool

Response Guidelines

When helping users with OHOS development:

1. Locate Skill Directory

   • Replace $SKILL_DIR with the actual skill installation path
   • Common locations: ~/.claude/skills/ohos-app-build-debug or project-specific paths

2. Execute Scripts

   • Call Python scripts in scripts/ directory using absolute or relative paths
   • Always change to the OHOS project directory before running scripts

3. Show Environment First

   • Run env_detector.py when first building to show tool availability

4. Provide One-liners

   • Combine build, install, launch when appropriate for user convenience

5. Show Actual Commands

   • Display the hvigorw/hdc commands being executed for transparency

6. Handle Errors Gracefully

   • Provide troubleshooting guidance when commands fail
   • Reference references/troubleshooting.md for detailed help

7. Use Project Context

   • Auto-detect bundle names and paths from project structure

Error Handling

If DevEco Studio is not detected:

• Verify DevEco Studio is installed
• Check standard installation paths
• Set DEVECO_STUDIO_PATH environment variable

If device is not connected:

• Check USB cable connection
• Verify USB debugging is enabled on device
• Authorize USB debugging on device when prompted

For detailed troubleshooting, see references/troubleshooting.md.

Prerequisites

• DevEco Studio 3.1+ (4.0+ recommended)
• OHOS Device with USB debugging enabled
• Python 3.7+ (for running scripts)

Download DevEco Studio: https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-download