From ab10765eb3c509ce171883b30c2731fc87b73d52 Mon Sep 17 00:00:00 2001 From: cheliangzhao Date: Wed, 11 Feb 2026 11:38:12 +0800 Subject: [PATCH] refactor: extract module discovery into separate reference file - Move Finding Modules, Build Outputs, Unwanted Modules (~138 lines) to references/module-discovery.md - Replace with summary table and cross-reference in SKILL.md - Update README file tree and CHANGELOG --- CHANGELOG.md | 4 +- README.md | 3 +- harmonyos-build-deploy/SKILL.md | 142 ++---------------- .../references/module-discovery.md | 142 ++++++++++++++++++ 4 files changed, 156 insertions(+), 135 deletions(-) create mode 100644 harmonyos-build-deploy/references/module-discovery.md diff --git a/CHANGELOG.md b/CHANGELOG.md index da396ae..08c5142 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,9 +9,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### 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 +- **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 ### Added @@ -20,6 +21,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - **harmonyos-build-deploy**: Wireless debugging documentation (hdc tconn) - **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 diff --git a/README.md b/README.md index 24a31ce..e61c400 100644 --- a/README.md +++ b/README.md @@ -94,7 +94,8 @@ arkts-development/ harmonyos-build-deploy/ ├── SKILL.md └── references/ - └── device-installation.md + ├── device-installation.md + └── module-discovery.md ``` ## Contributing diff --git a/harmonyos-build-deploy/SKILL.md b/harmonyos-build-deploy/SKILL.md index 57723db..d4552d6 100644 --- a/harmonyos-build-deploy/SKILL.md +++ b/harmonyos-build-deploy/SKILL.md @@ -223,142 +223,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 - -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 `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 /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) @@ -529,6 +404,7 @@ hilog.error(DOMAIN, TAG, 'Failed to load data: %{public}s', error.message); ## 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 ## Related Skills diff --git a/harmonyos-build-deploy/references/module-discovery.md b/harmonyos-build-deploy/references/module-discovery.md new file mode 100644 index 0000000..3850bdb --- /dev/null +++ b/harmonyos-build-deploy/references/module-discovery.md @@ -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": "support_http", + "srcPath": "./support/support_http", + "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 `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 /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.