diff --git a/arkts-development/SKILL.md b/arkts-development/SKILL.md index 47e5545..53710c8 100644 --- a/arkts-development/SKILL.md +++ b/arkts-development/SKILL.md @@ -286,3 +286,7 @@ See [references/arkguard-obfuscation.md](references/arkguard-obfuscation.md) for - **IDE**: DevEco Studio - **SDK**: HarmonyOS SDK - **Simulator**: Built-in DevEco Studio emulator + +## Related Skills + +- **Build & Deploy**: See `harmonyos-build-deploy` skill for building, packaging, and device installation diff --git a/harmonyos-build-deploy/SKILL.md b/harmonyos-build-deploy/SKILL.md new file mode 100644 index 0000000..e7759b6 --- /dev/null +++ b/harmonyos-build-deploy/SKILL.md @@ -0,0 +1,332 @@ +--- +name: harmonyos-build-deploy +description: 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. + +## Quick Reference + +```bash +# For time-consuming operations (build, deploy), use subagent Task tool +# See "Workflow with Subagent" section below for details + +# 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 shell "rm -rf /data/local/tmp/install && mkdir -p /data/local/tmp/install" +hdc -t file send /signed /data/local/tmp/install +hdc -t 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. + +## Workflow with Subagent + +For time-consuming operations (build, clean, deploy), use the **general** subagent to handle the entire workflow: + +### Clean Build & Deploy + +```bash +# Launch subagent to clean, build, and deploy to device +Task(description="Clean build and deploy", prompt="Clean build and deploy the HarmonyOS app to device. + +1. Run: hvigorw clean --no-daemon +2. Run: ohpm install --all +3. Run: hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon +4. Find the build output directory (outputs/project/ or outputs/default/) +5. Deploy to device using hdc commands: + - Clean device temp: hdc -t shell \"rm -rf /data/local/tmp/install && mkdir -p /data/local/tmp/install\" + - Send files: hdc -t file send /data/local/tmp/install/ + - Install: hdc -t shell \"bm install -p /data/local/tmp/install/project/bundles/signed\" + - Launch: hdc -t shell \"aa start -a EntryAbility -b \" +6. Report success/failure with details.", subagent_type="general") +``` + +### Deploy Only (No Rebuild) + +```bash +# Launch subagent to deploy existing build to device +Task(description="Deploy app to device", prompt="Deploy the HarmonyOS application to device . + +1. Read AppScope/app.json5 to get bundleName +2. Clean device temp: hdc -t shell \"rm -rf /data/local/tmp/install && mkdir -p /data/local/tmp/install\" +3. Send build output to device: hdc -t file send \"/project/\" \"/data/local/tmp/install/\" +4. Install: hdc -t shell \"bm install -p /data/local/tmp/install/project/bundles/signed\" +5. Launch: hdc -t shell \"aa start -a EntryAbility -b \" +6. Report success/failure with details.", subagent_type="general") +``` + +### Restart App + +```bash +# Launch subagent to restart the app +Task(description="Restart app", prompt="Restart the HarmonyOS app on device . + +1. Force stop: hdc -t shell \"aa force-stop \" +2. Launch: hdc -t shell \"aa start -a EntryAbility -b \" +3. Report success/failure.", subagent_type="general") +``` + +### Clean App Cache/Data + +```bash +# Launch subagent to clean app data +Task(description="Clean app data", prompt="Clean app data on device . + +1. Clean cache: hdc -t shell \"bm clean -n -c\" +2. Clean data: hdc -t shell \"bm clean -n -d\" +3. Report success/failure.", subagent_type="general") +``` + +**Why use subagent?** +- Long-running operations (build ~30s, file transfer ~20s) don't timeout +- Better error handling and reporting +- User gets clear progress updates + +## Build Commands (hvigorw) + +### Incremental Build (Default) + +Use incremental build for normal development - only changed modules are rebuilt: + +```bash +# 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: + +```bash +# 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 + +```bash +# 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) + +```bash +# 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`: + +```bash +hvigorw --sync -p product=default -p buildMode=release --no-daemon +``` + +### Build Types + +```bash +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) | + +## Unwanted Modules in Output Directory + +Sometimes HSP files appear in the output directory that are **not listed in `build-profile.json5`**. These modules should not be deployed. + +**Cause:** Build scripts or dependency configurations may copy precompiled HSP files to the output directory, even though they are not part of the current build. + +**How to identify:** + +1. Check `build-profile.json5` → `modules` array +2. If an HSP file in output is not in the modules list, it should be removed before installation + +**Solution:** Remove these HSP files before installation: + +```bash +# Example: Remove modules not in build-profile.json5 +rm /signed/unwanted-module-default-signed.hsp +``` + +**Note:** Installation will fail with "version code not same" error if these unwanted modules have a different versionCode than the main app. The root cause is that these modules shouldn't be deployed at all. + +## Device Installation (hdc) + +hdc (HarmonyOS Device Connector) is the CLI tool for device communication, similar to Android's adb. + +### Check Device + +```bash +hdc list targets # List connected devices (returns UDID) +hdc -t shell "whoami" # Test connection +``` + +### Push and Install + +```bash +# Clear device directory +hdc -t shell "rm -rf /data/local/tmp/install && mkdir -p /data/local/tmp/install" + +# Push signed bundles +hdc -t file send path/to/signed /data/local/tmp/install + +# Install all HAP/HSP in directory +hdc -t shell "bm install -p /data/local/tmp/install/signed" +``` + +### Verify and Launch + +```bash +# Check installation +hdc -t shell "bm dump -n " + +# Launch app (default ability) +hdc -t shell "aa start -a EntryAbility -b " +``` + +### Uninstall + +```bash +hdc -t shell "bm uninstall -n " +``` + +## hdc Command Reference + +| Command | Description | +|---------|-------------| +| `hdc list targets` | List connected devices | +| `hdc -t shell ""` | Execute shell command on device | +| `hdc -t file send ` | Push file/directory to device | +| `hdc -t file recv ` | Pull file/directory from device | +| `hdc kill` | Kill hdc server | +| `hdc start` | Start hdc server | +| `hdc version` | Show hdc version | + +## Bundle Manager (bm) + +Run via `hdc -t shell "bm ..."`: + +| Command | Description | +|---------|-------------| +| `bm install -p ` | Install from directory (all HAP/HSP) | +| `bm install -p ` | Install single HAP file | +| `bm uninstall -n ` | Uninstall application | +| `bm dump -n ` | Show package info | +| `bm dump -a` | List all installed packages | + +## Ability Assistant (aa) + +Run via `hdc -t shell "aa ..."`: + +| Command | Description | +|---------|-------------| +| `aa start -a -b ` | Start specific ability | +| `aa force-stop ` | Force stop application | +| `aa dump -a` | Dump all running abilities | + +## 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 + +- **Complete Installation Guide**: [references/device-installation.md](references/device-installation.md) diff --git a/harmonyos-build-deploy/references/device-installation.md b/harmonyos-build-deploy/references/device-installation.md new file mode 100644 index 0000000..46b53ed --- /dev/null +++ b/harmonyos-build-deploy/references/device-installation.md @@ -0,0 +1,292 @@ +# Device Installation Guide + +Complete guide for building, packaging, and installing HarmonyOS applications to physical devices. + +## Prerequisites + +- **hdc**: HarmonyOS Device Connector (included in HarmonyOS SDK) +- **Device**: HarmonyOS device with USB debugging enabled +- **Build Output**: Signed HAP/HSP files + +## Complete Workflow + +### Step 1: Check Device Connection + +```bash +hdc list targets +# Output: device UDID (e.g., 1234567890ABCDEF) +``` + +If no device found: +1. Check USB connection +2. Enable Developer Options on device +3. Enable USB debugging +4. Run `hdc kill && hdc start` to restart hdc server + +### Step 2: Build Project + +```bash +# Incremental build (default, use for normal development) +hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon +``` + +Only perform clean build when encountering issues or first time setup: + +```bash +# Clean build (only when needed) +hvigorw clean --no-daemon +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 +``` + +Build outputs location: +- APP bundle: `outputs/{product}/{project}-{product}-signed.app` +- Signed modules: `outputs/{product}/signed/` + +### Step 3: Verify Build Outputs + +All HAP/HSP modules must have the **same versionCode**. Check for mismatches: + +```bash +# Using Python (cross-platform) +python3 -c " +import zipfile, json, glob +for f in glob.glob('outputs/default/signed/*.hsp'): + z = zipfile.ZipFile(f) + data = json.loads(z.read('module.json')) + print(f\"{f.split('/')[-1]}: versionCode = {data['app']['versionCode']}\") +" + +# Using unzip + grep (Linux/macOS) +for f in outputs/default/signed/*.hsp; do + echo -n "$(basename $f): " + unzip -p "$f" module.json | grep -o '"versionCode":[0-9]*' +done +``` + +**How to identify problematic modules:** + +1. Module directory has no `src/` folder (precompiled binary only) +2. Module not listed in `build-profile.json5` modules array +3. Module versionCode differs from `AppScope/app.json5` + +If any module has a different versionCode, remove it before installation: + +```bash +rm outputs/default/signed/problematic-module-default-signed.hsp +``` + +### Step 4: Push Files to Device + +```bash +# Clear and create installation directory on device +hdc -t shell "rm -rf /data/local/tmp/app_install && mkdir -p /data/local/tmp/app_install" + +# Push signed HAP/HSP files +hdc -t file send outputs/default/signed /data/local/tmp/app_install +``` + +### Step 5: Install Application + +```bash +# Install all HAP/HSP from directory +hdc -t shell "bm install -p /data/local/tmp/app_install/signed" + +# Expected output: "install bundle successfully." +``` + +### Step 6: Verify and Launch + +```bash +# Check package info +hdc -t shell "bm dump -n " + +# Launch application +hdc -t shell "aa start -a EntryAbility -b " +``` + +### Uninstall Application + +```bash +hdc -t shell "bm uninstall -n " +``` + +## Quick Installation Script + +Save as `install.sh` (Linux/macOS) or run with Git Bash on Windows: + +```bash +#!/bin/bash + +# === Configuration === +DEVICE_ID="${1:-$(hdc list targets | head -1)}" +SIGNED_PATH="${2:-outputs/default/signed}" +BUNDLE_NAME="${3:-}" +REMOTE_PATH="/data/local/tmp/app_install" + +if [ -z "$DEVICE_ID" ]; then + echo "Error: No device found. Connect a device or specify UDID as first argument." + exit 1 +fi + +echo "Device: $DEVICE_ID" +echo "Source: $SIGNED_PATH" + +# === Clear remote directory === +hdc -t "$DEVICE_ID" shell "rm -rf $REMOTE_PATH && mkdir -p $REMOTE_PATH" + +# === Push signed files === +hdc -t "$DEVICE_ID" file send "$SIGNED_PATH" "$REMOTE_PATH" + +# === Install === +hdc -t "$DEVICE_ID" shell "bm install -p $REMOTE_PATH/$(basename $SIGNED_PATH)" + +echo "" +echo "Installation complete!" + +# === Optional: Launch app === +if [ -n "$BUNDLE_NAME" ]; then + echo "Launching $BUNDLE_NAME..." + hdc -t "$DEVICE_ID" shell "aa start -a EntryAbility -b $BUNDLE_NAME" +fi +``` + +Usage: + +```bash +# Auto-detect device, use default path +./install.sh + +# Specify device UDID +./install.sh 1234567890ABCDEF + +# Specify device and path +./install.sh 1234567890ABCDEF outputs/default/signed + +# Specify device, path, and bundle name (auto-launch) +./install.sh 1234567890ABCDEF outputs/default/signed com.example.app +``` + +## hdc Command Reference + +### Device Management + +| Command | Description | +|---------|-------------| +| `hdc list targets` | List connected devices (UDID) | +| `hdc -t shell ""` | Execute shell command on device | +| `hdc kill` | Kill hdc server | +| `hdc start` | Start hdc server | +| `hdc version` | Show hdc version | + +### File Transfer + +| Command | Description | +|---------|-------------| +| `hdc -t file send ` | Push file/directory to device | +| `hdc -t file recv ` | Pull file/directory from device | + +### Bundle Manager (bm) + +Execute via `hdc -t shell "bm ..."`: + +| Command | Description | +|---------|-------------| +| `bm install -p ` | Install from directory (all HAP/HSP) | +| `bm install -p ` | Install single HAP file | +| `bm uninstall -n ` | Uninstall application | +| `bm dump -n ` | Dump package info | +| `bm dump -a` | Dump all installed packages | + +### Ability Assistant (aa) + +Execute via `hdc -t shell "aa ..."`: + +| Command | Description | +|---------|-------------| +| `aa start -a -b ` | Start specific ability | +| `aa force-stop ` | Force stop application | +| `aa dump -a` | Dump all running abilities | + +## Troubleshooting + +### Error: "version code not same" + +**Cause:** Some HAP/HSP modules have different versionCode than others. + +**Solution:** +1. Use the version check commands to find modules with different versionCode +2. Remove those modules from signed directory before installation +3. Usually caused by precompiled modules not in build-profile.json5 + +### Error: "install parse profile prop check error" + +**Cause:** Signature or profile configuration mismatch. + +**Solution:** +1. Check signing config in `build-profile.json5` +2. Ensure certificate and profile match +3. Verify profile bundleName matches app.json5 bundleName +4. Check certificate is not expired + +### Error: Device not found + +**Cause:** Connection or hdc service issue. + +**Solution:** +1. Check USB cable connection +2. Enable Developer Options: Settings → About → Tap build number 7 times +3. Enable USB debugging: Settings → Developer options → USB debugging +4. Restart hdc server: `hdc kill && hdc start` +5. Try different USB port or cable + +### Error: "install failed due to older sdk version in the device" + +**Cause:** Device system version is lower than app's minimum requirement. + +**Solution:** +1. Update device to latest system version +2. Or lower `compatibleSdkVersion` in `build-profile.json5` + +### Error: "signature verification failed" + +**Cause:** Certificate issues. + +**Solution:** +1. Regenerate debug/release certificate in DevEco Studio +2. Check certificate validity period +3. Ensure using correct signing config for build type + +## Build Output Structure + +``` +outputs/ +└── {product}/ # e.g., default/ + ├── {project}-{product}-signed.app # Complete APP bundle + ├── signed/ + │ ├── entry-{product}-signed.hap # Main entry HAP + │ ├── feature-{product}-signed.hap # Feature HAP (if any) + │ └── *.hsp # Shared library modules + └── unsigned/ + └── ... # Unsigned versions +``` + +## Key Configuration Files + +| File | Description | +|------|-------------| +| `AppScope/app.json5` | App metadata: bundleName, versionCode, versionName, icon, label | +| `build-profile.json5` | Build config: modules list, products, signing configs | +| `{module}/src/main/module.json5` | Module config: abilities, permissions, pages | +| `{module}/oh-package.json5` | Module dependencies | + +## Module Types + +| Type | Extension | Description | +|------|-----------|-------------| +| HAP | `.hap` | Harmony Ability Package - Application entry point | +| HSP | `.hsp` | Harmony Shared Package - Dynamic shared library | +| HAR | `.har` | Harmony Archive - Static library (compiled into HAP) | +| APP | `.app` | Complete bundle containing all HAP + HSP |