arkts-skills/harmonyos-build-deploy/SKILL.md

name, description

name	description
harmonyos-build-deploy	HarmonyOS application build, clean, package and device installation. Use when building HarmonyOS projects with hvigorw, cleaning build artifacts, managing ohpm dependencies, packaging HAP/HSP/APP bundles, installing to devices via hdc, or troubleshooting installation errors like "version code not same".

HarmonyOS Build & Deploy

Complete workflow for building, cleaning, packaging, and installing HarmonyOS applications.

First Step: Confirm Operation with User

IMPORTANT: Before executing any build or deploy operation, confirm which specific operation(s) the user wants to perform. Ask the user to choose from:

Operation	Description
Clean build artifacts	Remove previous build cache and outputs
Install dependencies	Use ohpm to install project dependencies
Build project	Use hvigorw to build HAP/APP packages
Install to device	Use hdc to install the app on a device
Full pipeline	Clean → install deps → build → deploy to device

Why confirm first:

• Different scenarios require different operations (e.g., incremental build vs clean build)
• Avoid unnecessary time-consuming operations
• Give user control over the workflow
• Prevent accidental device installation

After user responds:

• Execute only the selected operations
• Report progress and results clearly

Quick Reference

# Build complete app (incremental)
hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon

# Install to device (check actual output path in your project)
hdc -t <UDID> shell "rm -rf /data/local/tmp/install && mkdir -p /data/local/tmp/install"
hdc -t <UDID> file send <output_path>/signed /data/local/tmp/install
hdc -t <UDID> shell "bm install -p /data/local/tmp/install/signed"

Note: Build output path varies by project. Common paths:

• outputs/default/signed/
• outputs/project/bundles/signed/

Check your project's actual output after build.

Workflows

IMPORTANT: Build, clean, and deploy operations are long-running (build ~30s, file transfer ~20s). Always delegate these workflows to a subagent to avoid timeout. This also provides better error handling and clearer progress reporting to the user.

Clean Build & Deploy

Delegate to subagent with the following steps:

1. Clean: hvigorw clean --no-daemon
2. Install dependencies: ohpm install --all
3. Build: hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon
4. Find build output (check outputs/default/signed/ or outputs/project/bundles/signed/)
5. Deploy to device:

   hdc -t <UDID> shell "rm -rf /data/local/tmp/install && mkdir -p /data/local/tmp/install"
   hdc -t <UDID> file send <output_path>/signed /data/local/tmp/install
   hdc -t <UDID> shell "bm install -p /data/local/tmp/install/signed"
   

6. Launch: hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"
7. Report success/failure with details

Deploy Only (No Rebuild)

Delegate to subagent with the following steps:

1. Read AppScope/app.json5 to get bundleName
2. Push existing build output to device:

   hdc -t <UDID> shell "rm -rf /data/local/tmp/install && mkdir -p /data/local/tmp/install"
   hdc -t <UDID> file send <output_path>/signed /data/local/tmp/install
   hdc -t <UDID> shell "bm install -p /data/local/tmp/install/signed"
   

3. Launch: hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"
4. Report success/failure with details

Restart App

Delegate to subagent:

1. Force stop: hdc -t <UDID> shell "aa force-stop <bundleName>"
2. Launch: hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"
3. Report success/failure

Clean App Cache/Data

Delegate to subagent:

1. Clean cache: hdc -t <UDID> shell "bm clean -n <bundleName> -c"
2. Clean data: hdc -t <UDID> shell "bm clean -n <bundleName> -d"
3. Report success/failure

Build Commands (hvigorw)

Incremental Build (Default)

Use incremental build for normal development - only changed modules are rebuilt:

# Build complete app (incremental)
hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon

Single Module Build

Build only a specific module for faster iteration:

# Build single HAP module
hvigorw assembleHap -p module=entry@default --mode module -p buildMode=release --no-daemon

# Build single HSP module
hvigorw assembleHsp -p module=feature_module@default --mode module -p buildMode=release --no-daemon

# Build single HAR module
hvigorw assembleHar -p module=library@default --mode module -p buildMode=release --no-daemon

# Build multiple modules at once
hvigorw assembleHsp -p module=module1@default,module2@default --mode module -p buildMode=release --no-daemon

Module name format: {moduleName}@{targetName}

• moduleName: Directory name of the module (e.g., entry, feature_home)
• targetName: Target defined in module's build-profile.json5 (usually default)

When to use single module build:

• Developing/debugging a specific module
• Faster build times during iteration
• Testing changes in isolated module

Note: After single module build, you still need to run assembleApp to package the complete application for installation.

Clean Build (When Needed)

Only perform clean build when:

• First time building the project
• Encountering unexplained build errors
• After modifying build-profile.json5 or SDK version
• Dependency resolution issues

# Clean build artifacts
hvigorw clean --no-daemon

# Deep clean (for dependency issues)
ohpm clean && ohpm cache clean
ohpm install --all
hvigorw --sync -p product=default -p buildMode=release --no-daemon
hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon

Install Dependencies (ohpm)

# Install all dependencies (after clean or first clone)
ohpm install --all

# With custom registry
ohpm install --all --registry "https://repo.harmonyos.com/ohpm/"

Sync Project

Only needed after modifying build-profile.json5 or oh-package.json5:

hvigorw --sync -p product=default -p buildMode=release --no-daemon

Build Types

hvigorw assembleHap    # Build HAP (Harmony Ability Package)
hvigorw assembleHsp    # Build HSP (Harmony Shared Package)
hvigorw assembleHar    # Build HAR (Harmony Archive)
hvigorw assembleApp    # Build complete APP bundle

Build Parameters

Parameter	Description
-p product={name}	Target product defined in build-profile.json5
-p buildMode={debug|release}	Build mode
-p module={name}@{target}	Target module with --mode module
--mode project	Build all modules in project
--mode module	Build specific module only
--no-daemon	Disable daemon (recommended for CI)
--analyze=advanced	Enable build analysis

Build Outputs

Build output path varies by project configuration. Common patterns:

outputs/
├── default/signed/                      # Pattern 1
│   ├── entry-default-signed.hap
│   └── *.hsp
└── project/bundles/signed/              # Pattern 2
    ├── entry-default-signed.hap
    └── *.hsp

Tip: After build, check the actual output directory in your project.

Module Types

Type	Extension	Description
HAP	.hap	Harmony Ability Package - Application entry module
HSP	.hsp	Harmony Shared Package - Dynamic shared library
HAR	.har	Harmony Archive - Static library (compiled into HAP)
APP	.app	Complete application bundle (all HAP + HSP)

Finding Modules

Modules are defined in build-profile.json5 at the project root. The module type is determined by the type field in {module}/src/main/module.json5:

type value	Module Type	Build Command
"entry" / "feature"	HAP	assembleHap
"shared"	HSP	assembleHsp
"har"	HAR	assembleHar

Module build outputs: {srcPath}/build/default/outputs/default/

For detailed module discovery, build output structure, and handling unwanted modules, see references/module-discovery.md.

Device Installation (hdc)

hdc (HarmonyOS Device Connector) is the CLI tool for device communication, similar to Android's adb.

Check Device

hdc list targets              # List connected devices (returns UDID)
hdc -t <UDID> shell "whoami"  # Test connection

Push and Install

# Clear device directory
hdc -t <UDID> shell "rm -rf /data/local/tmp/install && mkdir -p /data/local/tmp/install"

# Push signed bundles
hdc -t <UDID> file send path/to/signed /data/local/tmp/install

# Install all HAP/HSP in directory
hdc -t <UDID> shell "bm install -p /data/local/tmp/install/signed"

Verify and Launch

# Check installation
hdc -t <UDID> shell "bm dump -n <bundleName>"

# Launch app (default ability)
hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"

Uninstall

hdc -t <UDID> shell "bm uninstall -n <bundleName>"

hdc Command Reference

Command	Description
hdc list targets	List connected devices
hdc -t <UDID> shell "<cmd>"	Execute shell command on device
hdc -t <UDID> file send <local> <remote>	Push file/directory to device
hdc -t <UDID> file recv <remote> <local>	Pull file/directory from device
hdc tconn <IP>:<port>	Connect to device over Wi-Fi
hdc kill	Kill hdc server
hdc start	Start hdc server
hdc version	Show hdc version

Wireless Debugging (Wi-Fi)

Connect to a device over the network instead of USB:

# 1. Connect device via USB first and get its IP address
hdc -t <UDID> shell "ifconfig"    # Find wlan0 IP

# 2. Enable TCP port on device (if supported)
hdc -t <UDID> shell "param set persist.hdc.port 5555"

# 3. Connect wirelessly
hdc tconn <device_IP>:5555

# 4. Verify connection
hdc list targets
# Should show the IP-based target alongside or instead of USB target

Note: Wireless debugging may require the device and host to be on the same network. Not all devices support hdc tconn.

Bundle Manager (bm)

Run via hdc -t <UDID> shell "bm ...":

Command	Description
bm install -p <path>	Install from directory (all HAP/HSP)
bm install -p <file.hap>	Install single HAP file
bm install -r -p <path>	Reinstall (replace existing, keep data)
bm uninstall -n <bundleName>	Uninstall application
bm dump -n <bundleName>	Show package info
bm dump -a	List all installed packages
bm clean -n <bundleName> -c	Clean application cache
bm clean -n <bundleName> -d	Clean application data

Ability Assistant (aa)

Run via hdc -t <UDID> shell "aa ...":

Command	Description
aa start -a <ability> -b <bundle>	Start specific ability
aa force-stop <bundleName>	Force stop application
aa dump -a	Dump all running abilities

Device Logging (hilog)

Use hilog to view device logs for debugging. Run via hdc -t <UDID> shell "hilog ...":

# Stream all logs (like adb logcat)
hdc -t <UDID> shell "hilog"

# Filter by tag
hdc -t <UDID> shell "hilog -T <tag>"

# Filter by log level (DEBUG, INFO, WARN, ERROR, FATAL)
hdc -t <UDID> shell "hilog -L ERROR"

# Combine tag and level filters
hdc -t <UDID> shell "hilog -T MyApp -L WARN"

# Clear log buffer
hdc -t <UDID> shell "hilog -r"

# Show only recent logs (last N lines)
hdc -t <UDID> shell "hilog -t 100"

Common hilog Options

Option	Description
-T <tag>	Filter by log tag
-L <level>	Minimum log level: DEBUG, INFO, WARN, ERROR, FATAL
-D <domain>	Filter by domain (hex, e.g., 0x0001)
-r	Clear log buffer
-t <count>	Show only last N log entries
-x	Exit after printing existing logs (no streaming)

Logging in ArkTS Code

import { hilog } from '@kit.PerformanceAnalysisKit';

const DOMAIN: number = 0x0000;
const TAG: string = 'MyApp';

hilog.info(DOMAIN, TAG, 'Application started');
hilog.error(DOMAIN, TAG, 'Failed to load data: %{public}s', error.message);

Note: Use %{public}s for string parameters that should be visible in logs. Without {public}, parameters are masked as <private> in release builds.

Troubleshooting

Error	Cause	Solution
version code not same	HSP in output not in build-profile.json5	Remove unwanted HSP files before install
install parse profile prop check error	Signature/profile mismatch	Check signing config in build-profile.json5
install failed due to older sdk version	Device SDK < app's compatibleSdkVersion	Update device or lower compatibleSdkVersion
Device not found	Connection issue	Check USB, enable debugging, hdc kill && hdc start
signature verification failed	Invalid or expired certificate	Regenerate signing certificate

Key Configuration Files

File	Description
AppScope/app.json5	App metadata (bundleName, versionCode, versionName)
build-profile.json5	Modules list, products, signing configs
{module}/src/main/module.json5	Module config (abilities, permissions)
{module}/oh-package.json5	Module dependencies

Reference Files

• Module Discovery & Build Outputs: references/module-discovery.md - Module definitions, type identification, build output paths, unwanted modules
• Complete Installation Guide: references/device-installation.md - Detailed troubleshooting, version verification scripts, and installation script

Related Skills

• arkts-development: ArkTS/ArkUI development patterns, state management, component lifecycle, and API usage. Use alongside this skill when developing HarmonyOS application code.