Compare commits
9 Commits
c0f1574e47
...
306be63b7c
| Author | SHA1 | Date | |
|---|---|---|---|
|
306be63b7c | ||
|
|
d1d89b7225 | ||
|
|
01da810dfa | ||
|
|
bba88755f6 | ||
|
|
a10227e589 | ||
|
|
4717c93a8b | ||
|
|
ab10765eb3 | ||
|
|
53cdd8e1ae | ||
|
|
a131ad1057 |
24
CHANGELOG.md
24
CHANGELOG.md
@@ -4,6 +4,30 @@ All notable changes to this project will be documented in this file.
|
||||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
### Changed
|
||||
|
||||
- **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**: 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
|
||||
|
||||
### Removed
|
||||
|
||||
- **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)
|
||||
|
||||
### Added
|
||||
|
||||
- **harmonyos-build-deploy**: Additional bm commands (install -r reinstall, clean cache/data)
|
||||
- **harmonyos-build-deploy**: Cross-reference to arkts-development skill
|
||||
- **harmonyos-build-deploy**: New reference file `references/module-discovery.md`
|
||||
|
||||
## [1.0.1] - 2026-02-11
|
||||
|
||||
### Added
|
||||
|
||||
@@ -33,7 +33,8 @@ Build, package, and deploy HarmonyOS applications.
|
||||
**Covers:**
|
||||
- hvigorw build commands
|
||||
- ohpm package manager
|
||||
- hdc device installation
|
||||
- hdc device installation and wireless debugging
|
||||
- Module type identification
|
||||
- Troubleshooting common errors
|
||||
|
||||
## Quick Deploy
|
||||
@@ -92,7 +93,8 @@ arkts-development/
|
||||
harmonyos-build-deploy/
|
||||
├── SKILL.md
|
||||
└── references/
|
||||
└── device-installation.md
|
||||
├── device-installation.md
|
||||
└── module-discovery.md
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
@@ -7,30 +7,19 @@ description: HarmonyOS application build, clean, package and device installation
|
||||
|
||||
Complete workflow for building, cleaning, packaging, and installing HarmonyOS applications.
|
||||
|
||||
## First Step: Ask User for Operation
|
||||
## First Step: Confirm Operation with User
|
||||
|
||||
**IMPORTANT:** Before executing any build or deploy operation, you MUST first ask the user which specific operation(s) they want to perform using the `question` tool.
|
||||
**IMPORTANT:** Before executing any build or deploy operation, confirm which specific operation(s) the user wants to perform. Ask the user to choose from:
|
||||
|
||||
Use the following question configuration:
|
||||
| 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 |
|
||||
|
||||
```javascript
|
||||
question({
|
||||
questions: [{
|
||||
header: "选择操作",
|
||||
multiple: true,
|
||||
question: "您想要执行哪些构建部署操作？",
|
||||
options: [
|
||||
{ label: "清理构建产物", description: "清理之前的构建缓存和产物" },
|
||||
{ label: "安装依赖", description: "使用 ohpm 安装项目依赖" },
|
||||
{ label: "构建项目", description: "使用 hvigorw 构建 HAP/APP 包" },
|
||||
{ label: "安装到设备", description: "使用 hdc 将应用安装到设备" },
|
||||
{ label: "完整流程", description: "依次执行清理、安装依赖、构建、部署到设备" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
**Why ask first:**
|
||||
**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
|
||||
@@ -38,92 +27,71 @@ question({
|
||||
|
||||
**After user responds:**
|
||||
- Execute only the selected operations
|
||||
- Use the subagent Task tool for time-consuming operations (build, deploy)
|
||||
- Report progress and results clearly
|
||||
|
||||
## 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 <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"
|
||||
# Install to device
|
||||
# Use a random directory name to avoid conflicts with previous installations
|
||||
INSTALL_DIR="/data/local/tmp/install_$(date +%s)"
|
||||
hdc -t <UDID> shell "mkdir -p $INSTALL_DIR"
|
||||
hdc -t <UDID> file send outputs/default/bundles/signed $INSTALL_DIR
|
||||
hdc -t <UDID> shell "bm install -p $INSTALL_DIR/signed"
|
||||
hdc -t <UDID> shell "rm -rf $INSTALL_DIR"
|
||||
```
|
||||
|
||||
**Note:** Build output path varies by project. Common paths:
|
||||
- `outputs/default/signed/`
|
||||
- `outputs/project/bundles/signed/`
|
||||
**Note:** Build output path is `outputs/default/bundles/signed/`.
|
||||
|
||||
Check your project's actual output after build.
|
||||
## Workflows
|
||||
|
||||
## Workflow with Subagent
|
||||
|
||||
For time-consuming operations (build, clean, deploy), use the **general** subagent to handle the entire workflow:
|
||||
**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
|
||||
|
||||
```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.
|
||||
Delegate to subagent with the following steps:
|
||||
|
||||
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 <UDID> shell \"rm -rf /data/local/tmp/install && mkdir -p /data/local/tmp/install\"
|
||||
- Send files: hdc -t <UDID> file send <output_path> /data/local/tmp/install/
|
||||
- Install: hdc -t <UDID> shell \"bm install -p /data/local/tmp/install/project/bundles/signed\"
|
||||
- Launch: hdc -t <UDID> shell \"aa start -a EntryAbility -b <bundleName>\"
|
||||
6. Report success/failure with details.", subagent_type="general")
|
||||
```
|
||||
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 <UDID> shell "mkdir -p $INSTALL_DIR"
|
||||
hdc -t <UDID> file send outputs/default/bundles/signed $INSTALL_DIR
|
||||
hdc -t <UDID> shell "bm install -p $INSTALL_DIR/signed"
|
||||
hdc -t <UDID> shell "rm -rf $INSTALL_DIR"
|
||||
```
|
||||
6. Launch: `hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"`
|
||||
7. Report success/failure with details
|
||||
|
||||
### 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 <UDID>.
|
||||
Delegate to subagent with the following steps:
|
||||
|
||||
1. Read AppScope/app.json5 to get bundleName
|
||||
2. Clean device temp: hdc -t <UDID> shell \"rm -rf /data/local/tmp/install && mkdir -p /data/local/tmp/install\"
|
||||
3. Send build output to device: hdc -t <UDID> file send \"<output_path>/project/\" \"/data/local/tmp/install/\"
|
||||
4. Install: hdc -t <UDID> shell \"bm install -p /data/local/tmp/install/project/bundles/signed\"
|
||||
5. Launch: hdc -t <UDID> shell \"aa start -a EntryAbility -b <bundleName>\"
|
||||
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 <UDID>.
|
||||
|
||||
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.", subagent_type="general")
|
||||
```
|
||||
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 <UDID> shell "mkdir -p $INSTALL_DIR"
|
||||
hdc -t <UDID> file send outputs/default/bundles/signed $INSTALL_DIR
|
||||
hdc -t <UDID> shell "bm install -p $INSTALL_DIR/signed"
|
||||
hdc -t <UDID> shell "rm -rf $INSTALL_DIR"
|
||||
```
|
||||
3. Launch: `hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"`
|
||||
4. Report success/failure with details
|
||||
|
||||
### Clean App Cache/Data
|
||||
|
||||
```bash
|
||||
# Launch subagent to clean app data
|
||||
Task(description="Clean app data", prompt="Clean app data on device <UDID>.
|
||||
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.", 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
|
||||
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)
|
||||
|
||||
@@ -145,7 +113,7 @@ Build only a specific module for faster iteration:
|
||||
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
|
||||
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
|
||||
@@ -155,7 +123,7 @@ hvigorw assembleHsp -p module=module1@default,module2@default --mode module -p b
|
||||
```
|
||||
|
||||
**Module name format:** `{moduleName}@{targetName}`
|
||||
- `moduleName`: Directory name of the module (e.g., `entry`, `feature_home`)
|
||||
- `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:**
|
||||
@@ -225,20 +193,14 @@ hvigorw assembleApp # Build complete APP bundle
|
||||
|
||||
## Build Outputs
|
||||
|
||||
Build output path varies by project configuration. Common patterns:
|
||||
Build output path: `outputs/default/bundles/signed/`
|
||||
|
||||
```
|
||||
outputs/
|
||||
├── default/signed/ # Pattern 1
|
||||
│ ├── entry-default-signed.hap
|
||||
│ └── *.hsp
|
||||
└── project/bundles/signed/ # Pattern 2
|
||||
├── entry-default-signed.hap
|
||||
└── *.hsp
|
||||
outputs/default/bundles/signed/
|
||||
├── entry-default-signed.hap
|
||||
└── *.hsp
|
||||
```
|
||||
|
||||
**Tip:** After build, check the actual output directory in your project.
|
||||
|
||||
### Module Types
|
||||
|
||||
| Type | Extension | Description |
|
||||
@@ -250,131 +212,17 @@ outputs/
|
||||
|
||||
## Finding Modules
|
||||
|
||||
All modules are defined in `build-profile.json5` at the project root, in the `modules` array.
|
||||
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 Definition Structure
|
||||
| `type` value | Module Type | Build Command |
|
||||
|--------------|-------------|---------------|
|
||||
| `"entry"` / `"feature"` | **HAP** | `assembleHap` |
|
||||
| `"shared"` | **HSP** | `assembleHsp` |
|
||||
| `"har"` | **HAR** | `assembleHar` |
|
||||
|
||||
```json5
|
||||
{
|
||||
"modules": [
|
||||
{
|
||||
"name": "entry", // Module name (used in build commands)
|
||||
"srcPath": "./entry", // Module source path (relative to project root)
|
||||
"targets": [ // Build target config (optional)
|
||||
{
|
||||
"name": "default",
|
||||
"applyToProducts": ["default", "app_store"]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "support_http",
|
||||
"srcPath": "./support/support_http",
|
||||
"targets": [...]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
Module build outputs: `{srcPath}/build/default/outputs/default/`
|
||||
|
||||
### Key Fields
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `name` | Module name, used in build commands (e.g., `-p module=entry@default`) |
|
||||
| `srcPath` | Module source path relative to project root |
|
||||
| `targets` | Build target config, specifies which products this module applies to |
|
||||
|
||||
### Module Type Identification
|
||||
|
||||
| Characteristic | Module Type |
|
||||
|----------------|-------------|
|
||||
| Has `targets` and `name` is `entry` | **HAP** (Application entry) |
|
||||
| Has `targets` config | **HSP** (Dynamic shared package) |
|
||||
| No `targets` config | **HAR** (Static library, compiled into other modules) |
|
||||
|
||||
### Quick Commands
|
||||
|
||||
```bash
|
||||
# Read build-profile.json5 to find all modules
|
||||
cat build-profile.json5
|
||||
|
||||
# Extract module names and paths (grep)
|
||||
grep -E '"name"|"srcPath"' build-profile.json5
|
||||
```
|
||||
|
||||
## Finding Module Build Outputs
|
||||
|
||||
Module build outputs are located at:
|
||||
|
||||
```
|
||||
{srcPath}/build/default/outputs/default/
|
||||
```
|
||||
|
||||
**Note:** Debug and Release builds output to the same directory. The difference is in the signing configuration used (defined in `build-profile.json5` → `signingConfigs`).
|
||||
|
||||
### Output Files
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `{name}-default-signed.hsp` | **Signed HSP** (ready for installation) |
|
||||
| `{name}-default-unsigned.hsp` | Unsigned HSP |
|
||||
| `{name}.har` | HAR static library |
|
||||
| `app/{name}-default.hsp` | Intermediate artifact |
|
||||
| `mapping/sourceMaps.map` | Source maps for debugging |
|
||||
|
||||
### Example
|
||||
|
||||
For module `support_http` with `srcPath: "./support/support_http"`:
|
||||
|
||||
```
|
||||
support/support_http/build/default/outputs/default/
|
||||
├── support_http-default-signed.hsp ← Signed, ready to install
|
||||
├── support_http-default-unsigned.hsp
|
||||
├── support_http.har
|
||||
├── app/
|
||||
│ └── support_http-default.hsp
|
||||
├── mapping/
|
||||
│ └── sourceMaps.map
|
||||
└── pack.info
|
||||
```
|
||||
|
||||
### Search Commands
|
||||
|
||||
```bash
|
||||
# Find all signed HSP/HAP outputs
|
||||
dir /s /b "*-signed.hsp" "*-signed.hap" 2>nul # Windows
|
||||
find . -name "*-signed.hsp" -o -name "*-signed.hap" # Linux/macOS
|
||||
|
||||
# Find specific module's output
|
||||
dir /s /b "{srcPath}\build\default\outputs\default\*" # Windows
|
||||
ls -la {srcPath}/build/default/outputs/default/ # Linux/macOS
|
||||
```
|
||||
|
||||
### Notes
|
||||
|
||||
1. **Build required**: If `build/` directory doesn't exist, run build first
|
||||
2. **Project-level outputs**: Complete app bundle is in project root `outputs/` after `assembleApp`
|
||||
3. **oh_modules outputs**: Dependency modules may have outputs in `oh_modules/@xxx/build/...` (these are resolved dependencies)
|
||||
|
||||
## 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 <output_path>/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.
|
||||
For detailed module discovery, build output structure, and handling unwanted modules, see [references/module-discovery.md](references/module-discovery.md).
|
||||
|
||||
## Device Installation (hdc)
|
||||
|
||||
@@ -390,14 +238,18 @@ hdc -t <UDID> shell "whoami" # Test connection
|
||||
### Push and Install
|
||||
|
||||
```bash
|
||||
# Clear device directory
|
||||
hdc -t <UDID> shell "rm -rf /data/local/tmp/install && mkdir -p /data/local/tmp/install"
|
||||
# Create random temp directory on device
|
||||
INSTALL_DIR="/data/local/tmp/install_$(date +%s)"
|
||||
hdc -t <UDID> shell "mkdir -p $INSTALL_DIR"
|
||||
|
||||
# Push signed bundles
|
||||
hdc -t <UDID> file send path/to/signed /data/local/tmp/install
|
||||
hdc -t <UDID> file send outputs/default/bundles/signed $INSTALL_DIR
|
||||
|
||||
# Install all HAP/HSP in directory
|
||||
hdc -t <UDID> shell "bm install -p /data/local/tmp/install/signed"
|
||||
hdc -t <UDID> shell "bm install -p $INSTALL_DIR/signed"
|
||||
|
||||
# Clean up temp directory
|
||||
hdc -t <UDID> shell "rm -rf $INSTALL_DIR"
|
||||
```
|
||||
|
||||
### Verify and Launch
|
||||
@@ -436,9 +288,12 @@ Run via `hdc -t <UDID> shell "bm ..."`:
|
||||
|---------|-------------|
|
||||
| `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)
|
||||
|
||||
@@ -448,7 +303,6 @@ Run via `hdc -t <UDID> shell "aa ..."`:
|
||||
|---------|-------------|
|
||||
| `aa start -a <ability> -b <bundle>` | Start specific ability |
|
||||
| `aa force-stop <bundleName>` | Force stop application |
|
||||
| `aa dump -a` | Dump all running abilities |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
@@ -471,4 +325,9 @@ Run via `hdc -t <UDID> shell "aa ..."`:
|
||||
|
||||
## Reference Files
|
||||
|
||||
- **Complete Installation Guide**: [references/device-installation.md](references/device-installation.md)
|
||||
- **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
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **arkts-development**: ArkTS/ArkUI development patterns, state management, component lifecycle, and API usage. Use alongside this skill when developing HarmonyOS application code.
|
||||
|
||||
@@ -1,14 +1,49 @@
|
||||
# Device Installation Guide
|
||||
|
||||
Complete guide for building, packaging, and installing HarmonyOS applications to physical devices.
|
||||
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.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **hdc**: HarmonyOS Device Connector (included in HarmonyOS SDK)
|
||||
- **Device**: HarmonyOS device with USB debugging enabled
|
||||
- **Build Output**: Signed HAP/HSP files
|
||||
- **Build Output**: Signed HAP/HSP files from `hvigorw assembleApp`
|
||||
|
||||
## Complete Workflow
|
||||
## Verifying Build Outputs Before Installation
|
||||
|
||||
All HAP/HSP modules must have the **same versionCode**. Mismatched versions cause `"version code not same"` errors during installation.
|
||||
|
||||
### Check versionCode of All Modules
|
||||
|
||||
```bash
|
||||
# Using Python (cross-platform)
|
||||
python3 -c "
|
||||
import zipfile, json, glob
|
||||
for f in glob.glob('outputs/default/bundles/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/bundles/signed/*.hsp; do
|
||||
echo -n "$(basename $f): "
|
||||
unzip -p "$f" module.json | grep -o '"versionCode":[0-9]*'
|
||||
done
|
||||
```
|
||||
|
||||
### Identifying Problematic Modules
|
||||
|
||||
A module should be removed from the output before installation if:
|
||||
|
||||
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`
|
||||
|
||||
```bash
|
||||
rm outputs/default/bundles/signed/problematic-module-default-signed.hsp
|
||||
```
|
||||
|
||||
## Complete Installation Workflow
|
||||
|
||||
### Step 1: Check Device Connection
|
||||
|
||||
@@ -19,85 +54,34 @@ hdc list targets
|
||||
|
||||
If no device found:
|
||||
1. Check USB connection
|
||||
2. Enable Developer Options on device
|
||||
3. Enable USB debugging
|
||||
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: Build Project
|
||||
### Step 2: Push Files to Device
|
||||
|
||||
```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 <UDID> shell "rm -rf /data/local/tmp/app_install && mkdir -p /data/local/tmp/app_install"
|
||||
# Create random temp directory on device
|
||||
INSTALL_DIR="/data/local/tmp/install_$(date +%s)"
|
||||
hdc -t <UDID> shell "mkdir -p $INSTALL_DIR"
|
||||
|
||||
# Push signed HAP/HSP files
|
||||
hdc -t <UDID> file send outputs/default/signed /data/local/tmp/app_install
|
||||
hdc -t <UDID> file send outputs/default/bundles/signed $INSTALL_DIR
|
||||
```
|
||||
|
||||
### Step 5: Install Application
|
||||
### Step 3: Install Application
|
||||
|
||||
```bash
|
||||
# Install all HAP/HSP from directory
|
||||
hdc -t <UDID> shell "bm install -p /data/local/tmp/app_install/signed"
|
||||
hdc -t <UDID> shell "bm install -p $INSTALL_DIR/signed"
|
||||
|
||||
# Expected output: "install bundle successfully."
|
||||
|
||||
# Clean up temp directory
|
||||
hdc -t <UDID> shell "rm -rf $INSTALL_DIR"
|
||||
```
|
||||
|
||||
### Step 6: Verify and Launch
|
||||
### Step 4: Verify and Launch
|
||||
|
||||
```bash
|
||||
# Check package info
|
||||
@@ -107,12 +91,6 @@ hdc -t <UDID> shell "bm dump -n <bundleName>"
|
||||
hdc -t <UDID> shell "aa start -a EntryAbility -b <bundleName>"
|
||||
```
|
||||
|
||||
### Uninstall Application
|
||||
|
||||
```bash
|
||||
hdc -t <UDID> shell "bm uninstall -n <bundleName>"
|
||||
```
|
||||
|
||||
## Quick Installation Script
|
||||
|
||||
Save as `install.sh` (Linux/macOS) or run with Git Bash on Windows:
|
||||
@@ -122,9 +100,9 @@ Save as `install.sh` (Linux/macOS) or run with Git Bash on Windows:
|
||||
|
||||
# === Configuration ===
|
||||
DEVICE_ID="${1:-$(hdc list targets | head -1)}"
|
||||
SIGNED_PATH="${2:-outputs/default/signed}"
|
||||
SIGNED_PATH="${2:-outputs/default/bundles/signed}"
|
||||
BUNDLE_NAME="${3:-}"
|
||||
REMOTE_PATH="/data/local/tmp/app_install"
|
||||
REMOTE_PATH="/data/local/tmp/install_$(date +%s)"
|
||||
|
||||
if [ -z "$DEVICE_ID" ]; then
|
||||
echo "Error: No device found. Connect a device or specify UDID as first argument."
|
||||
@@ -133,15 +111,20 @@ fi
|
||||
|
||||
echo "Device: $DEVICE_ID"
|
||||
echo "Source: $SIGNED_PATH"
|
||||
echo "Remote: $REMOTE_PATH"
|
||||
|
||||
# === Clear remote directory ===
|
||||
hdc -t "$DEVICE_ID" shell "rm -rf $REMOTE_PATH && mkdir -p $REMOTE_PATH"
|
||||
# === Create remote directory ===
|
||||
hdc -t "$DEVICE_ID" shell "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)"
|
||||
BASENAME="$(basename "$SIGNED_PATH")"
|
||||
hdc -t "$DEVICE_ID" shell "bm install -p $REMOTE_PATH/$BASENAME"
|
||||
|
||||
# === Clean up ===
|
||||
hdc -t "$DEVICE_ID" shell "rm -rf $REMOTE_PATH"
|
||||
|
||||
echo ""
|
||||
echo "Installation complete!"
|
||||
@@ -163,61 +146,20 @@ Usage:
|
||||
./install.sh 1234567890ABCDEF
|
||||
|
||||
# Specify device and path
|
||||
./install.sh 1234567890ABCDEF outputs/default/signed
|
||||
./install.sh 1234567890ABCDEF outputs/default/bundles/signed
|
||||
|
||||
# Specify device, path, and bundle name (auto-launch)
|
||||
./install.sh 1234567890ABCDEF outputs/default/signed com.example.app
|
||||
./install.sh 1234567890ABCDEF outputs/default/bundles/signed com.example.app
|
||||
```
|
||||
|
||||
## hdc Command Reference
|
||||
|
||||
### Device Management
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `hdc list targets` | List connected devices (UDID) |
|
||||
| `hdc -t <UDID> shell "<cmd>"` | 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 <UDID> file send <local> <remote>` | Push file/directory to device |
|
||||
| `hdc -t <UDID> file recv <remote> <local>` | Pull file/directory from device |
|
||||
|
||||
### Bundle Manager (bm)
|
||||
|
||||
Execute 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 uninstall -n <bundleName>` | Uninstall application |
|
||||
| `bm dump -n <bundleName>` | Dump package info |
|
||||
| `bm dump -a` | Dump all installed packages |
|
||||
|
||||
### Ability Assistant (aa)
|
||||
|
||||
Execute 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 |
|
||||
|
||||
## Troubleshooting
|
||||
## Troubleshooting Details
|
||||
|
||||
### 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
|
||||
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
|
||||
|
||||
@@ -237,8 +179,8 @@ Execute via `hdc -t <UDID> shell "aa ..."`:
|
||||
|
||||
**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
|
||||
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
|
||||
|
||||
@@ -258,35 +200,3 @@ Execute via `hdc -t <UDID> shell "aa ..."`:
|
||||
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 |
|
||||
|
||||
142
harmonyos-build-deploy/references/module-discovery.md
Normal file
142
harmonyos-build-deploy/references/module-discovery.md
Normal file
@@ -0,0 +1,142 @@
|
||||
# Module Discovery & Build Outputs
|
||||
|
||||
Guide for finding modules in a HarmonyOS project, identifying module types, locating build outputs, and handling unwanted modules.
|
||||
|
||||
## Finding Modules
|
||||
|
||||
All modules are defined in `build-profile.json5` at the project root, in the `modules` array.
|
||||
|
||||
### Module Definition Structure
|
||||
|
||||
```json5
|
||||
{
|
||||
"modules": [
|
||||
{
|
||||
"name": "entry", // Module name (used in build commands)
|
||||
"srcPath": "./entry", // Module source path (relative to project root)
|
||||
"targets": [ // Build target config (optional)
|
||||
{
|
||||
"name": "default",
|
||||
"applyToProducts": ["default", "app_store"]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "my_library",
|
||||
"srcPath": "./library/my_library",
|
||||
"targets": [...]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Key Fields
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `name` | Module name, used in build commands (e.g., `-p module=entry@default`) |
|
||||
| `srcPath` | Module source path relative to project root |
|
||||
| `targets` | Build target config, specifies which products this module applies to |
|
||||
|
||||
### Module Type Identification
|
||||
|
||||
The module type is defined in each module's `module.json5` file:
|
||||
|
||||
```json5
|
||||
// {module}/src/main/module.json5
|
||||
{
|
||||
"module": {
|
||||
"name": "entry",
|
||||
"type": "entry", // "entry" = HAP, "shared" = HSP, "har" = HAR
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| `type` field value | Module Type | Description |
|
||||
|--------------------|-------------|-------------|
|
||||
| `"entry"` | **HAP** | Application entry point |
|
||||
| `"feature"` | **HAP** | Feature module (also a HAP) |
|
||||
| `"shared"` | **HSP** | Dynamic shared package |
|
||||
| `"har"` | **HAR** | Static library (compiled into other modules) |
|
||||
|
||||
**To identify all module types in a project:**
|
||||
|
||||
```bash
|
||||
# Read type from each module's module.json5
|
||||
# Check {srcPath}/src/main/module.json5 for each module in build-profile.json5
|
||||
```
|
||||
|
||||
## Finding Module Build Outputs
|
||||
|
||||
Module build outputs are located at:
|
||||
|
||||
```
|
||||
{srcPath}/build/default/outputs/default/
|
||||
```
|
||||
|
||||
**Note:** Debug and Release builds output to the same directory. The difference is in the signing configuration used (defined in `build-profile.json5` → `signingConfigs`).
|
||||
|
||||
### Output Files
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `{name}-default-signed.hsp` | **Signed HSP** (ready for installation) |
|
||||
| `{name}-default-unsigned.hsp` | Unsigned HSP |
|
||||
| `{name}.har` | HAR static library |
|
||||
| `app/{name}-default.hsp` | Intermediate artifact |
|
||||
| `mapping/sourceMaps.map` | Source maps for debugging |
|
||||
|
||||
### Example
|
||||
|
||||
For module `my_library` with `srcPath: "./library/my_library"`:
|
||||
|
||||
```
|
||||
library/my_library/build/default/outputs/default/
|
||||
├── my_library-default-signed.hsp ← Signed, ready to install
|
||||
├── my_library-default-unsigned.hsp
|
||||
├── my_library.har
|
||||
├── app/
|
||||
│ └── my_library-default.hsp
|
||||
├── mapping/
|
||||
│ └── sourceMaps.map
|
||||
└── pack.info
|
||||
```
|
||||
|
||||
### Search Commands
|
||||
|
||||
```bash
|
||||
# Find all signed HSP/HAP outputs
|
||||
dir /s /b "*-signed.hsp" "*-signed.hap" 2>nul # Windows
|
||||
find . -name "*-signed.hsp" -o -name "*-signed.hap" # Linux/macOS
|
||||
|
||||
# Find specific module's output
|
||||
dir /s /b "{srcPath}\build\default\outputs\default\*" # Windows
|
||||
ls -la {srcPath}/build/default/outputs/default/ # Linux/macOS
|
||||
```
|
||||
|
||||
### Notes
|
||||
|
||||
1. **Build required**: If `build/` directory doesn't exist, run build first
|
||||
2. **Project-level outputs**: Complete app bundle is in project root `outputs/` after `assembleApp`
|
||||
3. **oh_modules outputs**: Dependency modules may have outputs in `oh_modules/@xxx/build/...` (these are resolved dependencies)
|
||||
|
||||
## 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 outputs/default/bundles/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.
|
||||
Reference in New Issue
Block a user