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:

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 (Git Bash compatible)
# If you use Git Bash on Windows, disable MSYS path conversion for hdc commands.
export MSYS_NO_PATHCONV=1

INSTALL_DIR="//data/local/tmp/install_$(date +%s)"
hdc -t <UDID> shell "mkdir -p $INSTALL_DIR"
# Push files one-by-one to explicit remote file paths (most reliable on Git Bash)
for f in outputs/*.hap outputs/*.hsp; do
    [ -f "$f" ] && hdc -t <UDID> file send "$f" "$INSTALL_DIR/$(basename "$f")"
done

# Install (reinstall) HSPs first, then the HAP
for f in outputs/*.hsp outputs/*.hap; do
    [ -f "$f" ] && hdc -t <UDID> shell "bm install -p $INSTALL_DIR/$(basename \"$f\") -r"
done

hdc -t <UDID> shell "rm -rf $INSTALL_DIR"

Note: Build output path is outputs/.

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. Deploy to device (see Push and Install below)
5. Launch: hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"
6. 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. Check outputs/ for existing build outputs. If empty or missing, collect signed HAP/HSP from each module's build directory ({srcPath}/build/default/outputs/default/*-signed.*) into outputs/. See module-discovery.md for details.
3. Deploy to device (see Push and Install below)
4. Launch: hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"
5. Report success/failure with details

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=my_feature@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, my_feature)
• 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 Parameters

Build Outputs

Build output path: outputs/

outputs/
├── entry-default-signed.hap
└── *.hsp

Module Types

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:

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

# Create temp directory on device (Git Bash compatible)
# If you use Git Bash on Windows, disable MSYS path conversion for hdc commands.
export MSYS_NO_PATHCONV=1

INSTALL_DIR="//data/local/tmp/install_$(date +%s)"
hdc -t <UDID> shell "mkdir -p $INSTALL_DIR"

# Push files one-by-one to explicit remote file paths (most reliable on Git Bash)
for f in outputs/*.hap outputs/*.hsp; do
    [ -f "$f" ] && hdc -t <UDID> file send "$f" "$INSTALL_DIR/$(basename "$f")"
done

# Install (reinstall) HSPs first, then the HAP
for f in outputs/*.hsp outputs/*.hap; do
    [ -f "$f" ] && hdc -t <UDID> shell "bm install -p $INSTALL_DIR/$(basename \"$f\") -r"
done

# Clean up temp directory
hdc -t <UDID> shell "rm -rf $INSTALL_DIR"

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

Bundle Manager (bm)

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

Ability Assistant (aa)

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

Troubleshooting

Key Configuration Files

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