clz/arkts-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
cheliangzhao
2026-02-11 11:38:12 +08:00
parent 53cdd8e1ae
commit ab10765eb3
4 changed files with 156 additions and 135 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
CHANGELOG.md
View File

@@ -9,9 +9,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
### Changed ### Changed
- **harmonyos-build-deploy**: Translated Chinese UI strings to English in SKILL.md - **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**: 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**: 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 - **harmonyos-build-deploy**: Fixed unquoted variable in install.sh script
### Added ### 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**: Wireless debugging documentation (hdc tconn)
- **harmonyos-build-deploy**: Additional bm commands (install -r reinstall, clean cache/data) - **harmonyos-build-deploy**: Additional bm commands (install -r reinstall, clean cache/data)
- **harmonyos-build-deploy**: Cross-reference to arkts-development skill - **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 ## [1.0.1] - 2026-02-11

3
README.md
View File

@@ -94,7 +94,8 @@ arkts-development/
harmonyos-build-deploy/ harmonyos-build-deploy/
├── SKILL.md ├── SKILL.md
└── references/ └── references/
└── device-installation.md ├── device-installation.md
└── module-discovery.md
``` ```
## Contributing ## Contributing

142
harmonyos-build-deploy/SKILL.md
View File

@@ -223,142 +223,17 @@ outputs/
## Finding Modules ## 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 Module build outputs: `{srcPath}/build/default/outputs/default/`
{
"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 For detailed module discovery, build output structure, and handling unwanted modules, see [references/module-discovery.md](references/module-discovery.md).
| 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 <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.
## Device Installation (hdc) ## Device Installation (hdc)
@@ -529,6 +404,7 @@ hilog.error(DOMAIN, TAG, 'Failed to load data: %{public}s', error.message);
## Reference Files ## 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) - Detailed troubleshooting, version verification scripts, and installation script
## Related Skills ## Related Skills

142
harmonyos-build-deploy/references/module-discovery.md Normal file
View 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": "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 <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.