diff --git a/CHANGELOG.md b/CHANGELOG.md index 7721739..74cc91e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,7 +10,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - **harmonyos-build-deploy**: Translated Chinese UI strings to English in SKILL.md - **harmonyos-build-deploy**: Removed agent-framework coupling (question() tool, Task() subagent references) — workflows are now framework-agnostic but marked for subagent delegation -- **harmonyos-build-deploy**: Deduplicated content between SKILL.md and device-installation.md — reference file now focuses on version verification, install script, and detailed troubleshooting +- **harmonyos-build-deploy**: Deduplicated content between SKILL.md and device-installation.md — reference file now focuses on version verification and install script - **harmonyos-build-deploy**: Fixed module type identification — now uses `module.json5` `type` field instead of heuristic based on `targets` presence - **harmonyos-build-deploy**: Extracted module discovery, build outputs, and unwanted modules into `references/module-discovery.md` (~138 lines moved out of SKILL.md) - **harmonyos-build-deploy**: Fixed unquoted variable in install.sh script @@ -20,7 +20,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - **harmonyos-build-deploy**: Wireless debugging (hdc tconn) section — environment setup, not build/deploy - **harmonyos-build-deploy**: Restart App workflow — runtime operation, not build/deploy - **harmonyos-build-deploy**: `aa dump -a` command — runtime debugging, not build/deploy -- **harmonyos-build-deploy**: Duplicate Build Output Structure from device-installation.md (already in SKILL.md and module-discovery.md) +- **harmonyos-build-deploy**: Build Types section — redundant with Single Module Build and Module Types table +- **harmonyos-build-deploy**: Duplicate installation workflow and troubleshooting from device-installation.md (consolidated into SKILL.md) ### Added diff --git a/harmonyos-build-deploy/SKILL.md b/harmonyos-build-deploy/SKILL.md index f04bc7c..2b88a47 100644 --- a/harmonyos-build-deploy/SKILL.md +++ b/harmonyos-build-deploy/SKILL.md @@ -57,31 +57,16 @@ 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. Build output is at `outputs/default/bundles/signed/` -5. Deploy to device: - ```bash - INSTALL_DIR="/data/local/tmp/install_$(date +%s)" - hdc -t shell "mkdir -p $INSTALL_DIR" - hdc -t file send outputs/default/bundles/signed $INSTALL_DIR - hdc -t shell "bm install -p $INSTALL_DIR/signed" - hdc -t shell "rm -rf $INSTALL_DIR" - ``` -6. Launch: `hdc -t shell "aa start -a EntryAbility -b "` -7. Report success/failure with details +4. Deploy to device (see [Push and Install](#push-and-install) below) +5. Launch: `hdc -t shell "aa start -a EntryAbility -b "` +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. Push existing build output to device: - ```bash - INSTALL_DIR="/data/local/tmp/install_$(date +%s)" - hdc -t shell "mkdir -p $INSTALL_DIR" - hdc -t file send outputs/default/bundles/signed $INSTALL_DIR - hdc -t shell "bm install -p $INSTALL_DIR/signed" - hdc -t shell "rm -rf $INSTALL_DIR" - ``` +2. Deploy to device (see [Push and Install](#push-and-install) below) 3. Launch: `hdc -t shell "aa start -a EntryAbility -b "` 4. Report success/failure with details @@ -170,15 +155,6 @@ Only needed after modifying `build-profile.json5` or `oh-package.json5`: 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 | @@ -308,11 +284,11 @@ Run via `hdc -t shell "aa ..."`: | 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 | +| `version code not same` | HSP in output not in build-profile.json5 | Remove unwanted HSP files before install (see [module-discovery.md](references/module-discovery.md)) | +| `install parse profile prop check error` | Signature/profile mismatch | Check signing config in build-profile.json5; verify bundleName matches app.json5; check certificate not expired | | `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 | +| Device not found | Connection issue | Check USB; enable Developer Options (tap build number 7x) and USB debugging; `hdc kill && hdc start`; try different USB port/cable | +| `signature verification failed` | Invalid or expired certificate | Regenerate certificate in DevEco Studio; check validity period; ensure correct signing config for build type | ## Key Configuration Files @@ -326,7 +302,7 @@ Run via `hdc -t shell "aa ..."`: ## Reference Files - **Module Discovery & Build Outputs**: [references/module-discovery.md](references/module-discovery.md) - Module definitions, type identification, build output paths, unwanted modules -- **Complete Installation Guide**: [references/device-installation.md](references/device-installation.md) - Detailed troubleshooting, version verification scripts, and installation script +- **Complete Installation Guide**: [references/device-installation.md](references/device-installation.md) - Version verification scripts and installation script ## Related Skills diff --git a/harmonyos-build-deploy/references/device-installation.md b/harmonyos-build-deploy/references/device-installation.md index 8a2793c..374488a 100644 --- a/harmonyos-build-deploy/references/device-installation.md +++ b/harmonyos-build-deploy/references/device-installation.md @@ -1,6 +1,6 @@ # Device Installation Guide -Detailed guide for packaging and installing HarmonyOS applications to physical devices. This supplements the main [SKILL.md](../SKILL.md) with deeper troubleshooting, version verification, and an installation script. +Detailed guide for verifying build outputs and automating device installation. This supplements the main [SKILL.md](../SKILL.md) with version verification scripts and an installation script. ## Prerequisites @@ -43,54 +43,6 @@ A module should be removed from the output before installation if: rm outputs/default/bundles/signed/problematic-module-default-signed.hsp ``` -## Complete Installation 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: Settings > About > Tap build number 7 times -3. Enable USB debugging: Settings > Developer options > USB debugging -4. Run `hdc kill && hdc start` to restart hdc server - -### Step 2: Push Files to Device - -```bash -# Create random temp directory on device -INSTALL_DIR="/data/local/tmp/install_$(date +%s)" -hdc -t shell "mkdir -p $INSTALL_DIR" - -# Push signed HAP/HSP files -hdc -t file send outputs/default/bundles/signed $INSTALL_DIR -``` - -### Step 3: Install Application - -```bash -# Install all HAP/HSP from directory -hdc -t shell "bm install -p $INSTALL_DIR/signed" - -# Expected output: "install bundle successfully." - -# Clean up temp directory -hdc -t shell "rm -rf $INSTALL_DIR" -``` - -### Step 4: Verify and Launch - -```bash -# Check package info -hdc -t shell "bm dump -n " - -# Launch application -hdc -t shell "aa start -a EntryAbility -b " -``` - ## Quick Installation Script Save as `install.sh` (Linux/macOS) or run with Git Bash on Windows: @@ -151,52 +103,3 @@ Usage: # Specify device, path, and bundle name (auto-launch) ./install.sh 1234567890ABCDEF outputs/default/bundles/signed com.example.app ``` - -## Troubleshooting Details - -### Error: "version code not same" - -**Cause:** Some HAP/HSP modules have different versionCode than others. - -**Solution:** -1. Use the version check commands above 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