From 6e5c7961d48585018ee68d2d7e7003bab16bd43d Mon Sep 17 00:00:00 2001 From: CHE LIANG ZHAO Date: Thu, 22 Jan 2026 16:29:45 +0800 Subject: [PATCH] docs: add command-line tools reference (hvigorw, codelinter, hstack) --- arkts-development/SKILL.md | 134 +++++++++++++ arkts-development/references/codelinter.md | 160 ++++++++++++++++ arkts-development/references/hstack.md | 153 +++++++++++++++ .../references/hvigor-commandline.md | 179 ++++++++++++++++++ 4 files changed, 626 insertions(+) create mode 100644 arkts-development/references/codelinter.md create mode 100644 arkts-development/references/hstack.md create mode 100644 arkts-development/references/hvigor-commandline.md diff --git a/arkts-development/SKILL.md b/arkts-development/SKILL.md index fe7719e..47e5545 100644 --- a/arkts-development/SKILL.md +++ b/arkts-development/SKILL.md @@ -141,11 +141,145 @@ ArkTS enforces stricter rules than TypeScript for performance and safety: See [references/migration-guide.md](references/migration-guide.md) for complete TypeScript → ArkTS migration details. +## Command Line Build (hvigorw) + +hvigorw is the Hvigor wrapper tool for command-line builds. + +```bash +# Common build tasks +hvigorw clean # Clean build directory +hvigorw assembleHap -p buildMode=debug # Build Hap (debug) +hvigorw assembleApp -p buildMode=release # Build App (release) +hvigorw assembleHar # Build Har library +hvigorw assembleHsp # Build Hsp + +# Build specific module +hvigorw assembleHap -p module=entry@default --mode module + +# Run tests +hvigorw onDeviceTest -p module=entry -p coverage=true +hvigorw test -p module=entry # Local test + +# CI/CD recommended +hvigorw assembleApp -p buildMode=release --no-daemon +``` + +Common parameters: + +| Parameter | Description | +|-----------|-------------| +| `-p buildMode={debug\|release}` | Build mode | +| `-p product={name}` | Target product (default: default) | +| `-p module={name}@{target}` | Target module (with `--mode module`) | +| `--no-daemon` | Disable daemon (recommended for CI) | +| `--analyze=advanced` | Enable build analysis | +| `--optimization-strategy=memory` | Memory-optimized build | + +See [references/hvigor-commandline.md](references/hvigor-commandline.md) for complete command reference. + +## Code Linter (codelinter) + +codelinter is the code checking and fixing tool for ArkTS/TS files. + +```bash +# Basic usage +codelinter # Check current project +codelinter /path/to/project # Check specified project +codelinter -c ./code-linter.json5 # Use custom rules + +# Check and auto-fix +codelinter --fix +codelinter -c ./code-linter.json5 --fix + +# Output formats +codelinter -f json -o ./report.json # JSON report +codelinter -f html -o ./report.html # HTML report + +# Incremental check (Git changes only) +codelinter -i + +# CI/CD with exit codes +codelinter --exit-on error,warn # Non-zero exit on error/warn +``` + +| Parameter | Description | +|-----------|-------------| +| `-c, --config ` | Specify rules config file | +| `--fix` | Auto-fix supported issues | +| `-f, --format` | Output format: default/json/xml/html | +| `-o, --output ` | Save result to file | +| `-i, --incremental` | Check only Git changed files | +| `-p, --product ` | Specify product | +| `-e, --exit-on ` | Exit code levels: error,warn,suggestion | + +See [references/codelinter.md](references/codelinter.md) for complete reference. + +## Stack Trace Parser (hstack) + +hstack parses obfuscated crash stacks from Release builds back to source code locations. + +```bash +# Parse crash files directory +hstack -i crashDir -o outputDir -s sourcemapDir -n nameCacheDir + +# Parse with C++ symbols +hstack -i crashDir -o outputDir -s sourcemapDir --so soDir -n nameCacheDir + +# Parse single crash stack +hstack -c "at func (entry|entry|1.0.0|src/main/ets/pages/Index.ts:58:58)" -s sourcemapDir +``` + +| Parameter | Description | +|-----------|-------------| +| `-i, --input` | Crash files directory | +| `-c, --crash` | Single crash stack string | +| `-o, --output` | Output directory (or file with `-c`) | +| `-s, --sourcemapDir` | Sourcemap files directory | +| `--so, --soDir` | Shared object (.so) files directory | +| `-n, --nameObfuscation` | NameCache files directory | + +Requirements: +- Must provide either `-i` or `-c` (not both) +- Must provide at least `-s` or `--so` +- For method name restoration, provide both `-s` and `-n` + +See [references/hstack.md](references/hstack.md) for complete reference. + +## Code Obfuscation (ArkGuard) + +Enable in `build-profile.json5`: + +```json +"arkOptions": { + "obfuscation": { + "ruleOptions": { + "enable": true, + "files": ["./obfuscation-rules.txt"] + } + } +} +``` + +Common rules in `obfuscation-rules.txt`: + +```text +-enable-property-obfuscation # Property name obfuscation +-enable-toplevel-obfuscation # Top-level scope obfuscation +-enable-filename-obfuscation # Filename obfuscation +-keep-property-name apiKey # Whitelist specific names +``` + +See [references/arkguard-obfuscation.md](references/arkguard-obfuscation.md) for complete guide. + ## Reference Files - **Migration Guide**: [references/migration-guide.md](references/migration-guide.md) - Complete TypeScript to ArkTS migration rules and examples - **Component Patterns**: [references/component-patterns.md](references/component-patterns.md) - Advanced component patterns and best practices - **API Reference**: [references/api-reference.md](references/api-reference.md) - Common HarmonyOS APIs +- **ArkGuard Obfuscation**: [references/arkguard-obfuscation.md](references/arkguard-obfuscation.md) - Code obfuscation configuration and troubleshooting +- **Hvigor Command Line**: [references/hvigor-commandline.md](references/hvigor-commandline.md) - Complete hvigorw build tool reference +- **CodeLinter**: [references/codelinter.md](references/codelinter.md) - Code checking and fixing tool +- **Hstack**: [references/hstack.md](references/hstack.md) - Crash stack trace parser for Release builds ## Development Environment diff --git a/arkts-development/references/codelinter.md b/arkts-development/references/codelinter.md new file mode 100644 index 0000000..1778daa --- /dev/null +++ b/arkts-development/references/codelinter.md @@ -0,0 +1,160 @@ +# CodeLinter 代码检查工具 + +codelinter 是 HarmonyOS 的代码检查与修复工具，可集成到门禁或 CI/CD 环境中。 + +## 命令格式 + +```bash +codelinter [options] [dir] +``` + +- `options`: 可选配置参数 +- `dir`: 待检查的工程根目录（可选，默认为当前目录） + +## 命令参数 + +| 参数 | 说明 | +|------|------| +| `--config, -c ` | 指定规则配置文件 (code-linter.json5) | +| `--fix` | 检查同时执行自动修复 | +| `--format, -f ` | 输出格式: `default`/`json`/`xml`/`html` | +| `--output, -o ` | 指定结果保存位置（不在命令行显示） | +| `--version, -v` | 查看版本 | +| `--product, -p ` | 指定生效的 product | +| `--incremental, -i` | 仅检查 Git 增量文件（新增/修改/重命名） | +| `--help, -h` | 查询帮助 | +| `--exit-on, -e ` | 指定返回非零退出码的告警级别 | + +## 基本用法 + +### 在工程根目录下执行 + +```bash +# 使用默认规则检查当前工程 +codelinter + +# 指定规则配置文件 +codelinter -c ./code-linter.json5 + +# 检查并自动修复 +codelinter -c ./code-linter.json5 --fix +``` + +### 在非工程目录下执行 + +```bash +# 检查指定工程目录 +codelinter /path/to/project + +# 检查多个目录或文件 +codelinter dir1 dir2 file1.ets + +# 指定规则文件和工程目录 +codelinter -c /path/to/code-linter.json5 /path/to/project + +# 检查并修复指定工程 +codelinter -c ./code-linter.json5 /path/to/project --fix +``` + +## 输出格式 + +```bash +# 默认文本格式输出到命令行 +codelinter /path/to/project + +# JSON 格式输出 +codelinter /path/to/project -f json + +# HTML 格式保存到文件 +codelinter /path/to/project -f html -o ./report.html + +# XML 格式保存到文件 +codelinter /path/to/project -f xml -o ./report.xml +``` + +## 增量检查 + +对 Git 工程中的增量文件执行检查（仅检查新增、修改、重命名的文件）： + +```bash +codelinter -i +codelinter --incremental +``` + +## 指定 Product + +当工程存在多个 product 时，指定生效的 product： + +```bash +codelinter -p free /path/to/project +codelinter --product default +``` + +## 退出码 (--exit-on) + +用于 CI/CD 中根据告警级别控制流程。告警级别：`error`、`warn`、`suggestion` + +退出码计算方式（3位二进制数，从高到低表示 error, warn, suggestion）： + +| 配置 | 检查结果包含 | 二进制 | 退出码 | +|------|-------------|--------|--------| +| `--exit-on error` | error, warn, suggestion | 100 | 4 | +| `--exit-on error` | warn, suggestion | 000 | 0 | +| `--exit-on error,warn` | error, warn | 110 | 6 | +| `--exit-on error,warn,suggestion` | error | 100 | 4 | +| `--exit-on error,warn,suggestion` | error, warn, suggestion | 111 | 7 | + +```bash +# 仅 error 级别返回非零退出码 +codelinter --exit-on error + +# error 和 warn 级别返回非零退出码 +codelinter --exit-on error,warn + +# 所有级别都返回非零退出码 +codelinter --exit-on error,warn,suggestion +``` + +## CI/CD 集成示例 + +```bash +# 完整的 CI 检查流程 +codelinter -c ./code-linter.json5 \ + -f json \ + -o ./codelinter-report.json \ + --exit-on error,warn + +# 增量检查（仅检查变更文件） +codelinter -i -c ./code-linter.json5 --exit-on error + +# 检查并自动修复，生成 HTML 报告 +codelinter -c ./code-linter.json5 \ + --fix \ + -f html \ + -o ./codelinter-report.html +``` + +## 规则配置文件 (code-linter.json5) + +默认规则清单可在检查完成后，根据命令行提示查看生成的 `code-linter.json5` 文件。 + +示例配置： + +```json5 +{ + "files": [ + "**/*.ets", + "**/*.ts" + ], + "ignore": [ + "**/node_modules/**", + "**/oh_modules/**", + "**/build/**" + ], + "ruleSet": ["plugin:@ohos/recommended"], + "rules": { + "@ohos/no-any": "error", + "@ohos/no-console": "warn" + } +} +``` diff --git a/arkts-development/references/hstack.md b/arkts-development/references/hstack.md new file mode 100644 index 0000000..96678bb --- /dev/null +++ b/arkts-development/references/hstack.md @@ -0,0 +1,153 @@ +# 堆栈解析工具 (hstack) + +hstack 是用于将 Release 应用混淆后的 crash 堆栈解析为源码对应堆栈的工具，支持 Windows、Mac、Linux 三个平台。 + +## 命令格式 + +```bash +hstack [options] +``` + +## 命令参数 + +| 参数 | 说明 | +|------|------| +| `-i, --input` | 指定 crash 文件归档目录 | +| `-c, --crash` | 指定一条 crash 堆栈 | +| `-o, --output` | 指定解析结果输出目录（使用 `-c` 时指定输出文件） | +| `-s, --sourcemapDir` | 指定 sourcemap 文件归档目录 | +| `--so, --soDir` | 指定 shared object (.so) 文件归档目录 | +| `-n, --nameObfuscation` | 指定 nameCache 文件归档目录 | +| `-v, --version` | 查看版本 | +| `-h, --help` | 查询帮助 | + +## 参数约束 + +- crash 文件目录 (`-i`) 与 crash 堆栈 (`-c`) **必须且只能提供一项** +- sourcemap (`-s`) 与 shared object (`--so`) 目录**至少提供一项** +- 如需还原混淆的方法名，需**同时提供** sourcemap 和 nameCache 文件 +- 路径参数不支持特殊字符：`` `~!@#$^&*=|{};,\s\[\]<>? `` + +## 环境配置 + +1. 将 Command Line Tools 的 `bin` 目录配置到 PATH 环境变量 +2. 配置 Node.js 到环境变量 +3. 解析 C++ 异常需配置 SDK 的 `native\llvm\bin` 目录到环境变量 `ADDR2LINE_PATH` + +## 使用示例 + +### 解析 crash 文件目录 + +```bash +# 完整解析命令 +hstack -i crashDir -o outputDir -s sourcemapDir --so soDir -n nameCacheDir + +# 仅使用 sourcemap 解析 (ArkTS) +hstack -i crashDir -o outputDir -s sourcemapDir + +# 仅使用 so 文件解析 (C++) +hstack -i crashDir -o outputDir --so soDir + +# 包含方法名还原 +hstack -i crashDir -o outputDir -s sourcemapDir -n nameCacheDir +``` + +### 解析单条堆栈 + +```bash +# 输出到控制台 +hstack -c "at har (entry|har|1.0.0|src/main/ets/pages/Index.ts:58:58)" -s sourcemapDir + +# 输出到文件 +hstack -c "at har (entry|har|1.0.0|src/main/ets/pages/Index.ts:58:58)" -s sourcemapDir -o result.txt +``` + +## 输出说明 + +- 解析结果输出到 `-o` 指定目录，文件以原始 crash 文件名加 `_` 前缀命名 +- 不指定 `-o` 时： + - 使用 `-i` 输入：输出到 crashDir 目录 + - 使用 `-c` 输入：直接输出到控制台 + +## 文件获取 + +### Sourcemap 文件 + +构建产物中的 sourcemap 文件，包含： +- 路径信息映射 +- 行列号映射 (mappings 字段) +- package-info 信息 + +### NameCache 文件 + +构建产物中的 nameCache 文件，包含： +- `IdentifierCache`: 标识符混淆映射 +- `MemberMethodCache`: 成员方法混淆映射，格式为 `"源码方法名:起始行:结束行": "混淆后方法名"` + +### Shared Object (.so) 文件 + +构建 Release 应用时，默认 so 文件不包含符号表。如需生成包含符号表的 so 文件，在模块 `build-profile.json5` 中配置： + +```json5 +{ + "buildOption": { + "externalNativeOptions": { + "arguments": "-DCMAKE_BUILD_TYPE=RelWithDebInfo" + } + } +} +``` + +## 堆栈解析原理 + +### Crash 堆栈格式 + +``` +at har (entry|har|1.0.0|src/main/ets/components/mainpage/MainPage.js:58:58) +at i (entry|entry|1.0.0|src/main/ets/pages/Index.ts:71:71) +``` + +路径格式：`引用方packageName|被引用方packageName|version|源码相对路径` + +### 解析步骤 + +1. **根据路径信息找到 sourcemap** + - 从路径 `entry|har|1.0.0|src/main/ets/...` 在 entry 模块 sourcemap 中查找对应字段 + +2. **利用 sourcemap 还原路径和行列号** + - 根据 `sources` 和 `mappings` 字段解析 + - 如包含 `package-info`，可进行二次解析获取更准确的源码位置 + +3. **利用 nameCache 还原方法名** + - 查找混淆后方法名对应的所有条目 + - 根据还原后的行号范围匹配正确的源码方法名 + +### 解析示例 + +原始堆栈： +``` +at i (entry|entry|1.0.0|src/main/ets/pages/Index.ts:71:71) +``` + +还原后： +``` +at callHarFunction (entry/src/main/ets/pages/Index.ets:25:3) +``` + +## CI/CD 集成 + +```bash +# 自动化解析脚本示例 +hstack \ + -i ./crash-logs \ + -o ./parsed-logs \ + -s ./build/sourcemap \ + --so ./build/libs \ + -n ./build/nameCache +``` + +## 常见问题 + +1. **方法名未还原**: 确保同时提供 `-s` 和 `-n` 参数 +2. **C++ 堆栈未解析**: 检查 `ADDR2LINE_PATH` 环境变量配置 +3. **so 文件无符号表**: 配置 `RelWithDebInfo` 构建选项 diff --git a/arkts-development/references/hvigor-commandline.md b/arkts-development/references/hvigor-commandline.md new file mode 100644 index 0000000..76e99e6 --- /dev/null +++ b/arkts-development/references/hvigor-commandline.md @@ -0,0 +1,179 @@ +# Hvigor 命令行构建工具 (hvigorw) + +hvigorw 是 Hvigor 的 wrapper 包装工具，支持自动安装 Hvigor 构建工具和相关插件依赖，以及执行 Hvigor 构建命令。 + +## 命令格式 + +```bash +hvigorw [taskNames...] +``` + +## 编译构建任务 + +| 任务 | 说明 | +|------|------| +| `clean` | 清理构建产物 build 目录 | +| `assembleHap` | 构建 Hap 应用 | +| `assembleApp` | 构建 App 应用 | +| `assembleHsp` | 构建 Hsp 包 | +| `assembleHar` | 构建 Har 包 | +| `collectCoverage` | 基于打点数据生成覆盖率统计报表 | + +## 常用构建参数 + +| 参数 | 说明 | +|------|------| +| `-p buildMode={debug\|release}` | 指定构建模式。默认：Hap/Hsp/Har 为 debug，App 为 release | +| `-p debuggable=true/false` | 覆盖 buildOption 中的 debuggable 配置 | +| `-p product={ProductName}` | 指定 product 进行编译，默认为 default | +| `-p module={ModuleName}@{TargetName}` | 指定模块及 target 编译（需配合 `--mode module`） | +| `-p ohos-test-coverage={true\|false}` | 执行测试框架代码覆盖率插桩编译 | +| `-p parameterFile=param.json` | 设置 oh-package.json5 的参数配置文件 | + +## 构建示例 + +```bash +# 清理构建产物 +hvigorw clean + +# Debug 模式构建 Hap +hvigorw assembleHap -p buildMode=debug + +# Release 模式构建 App +hvigorw assembleApp -p buildMode=release + +# 构建指定 product +hvigorw assembleHap -p product=free + +# 构建指定模块 +hvigorw assembleHap -p module=entry@default --mode module + +# 构建多个模块 +hvigorw assembleHar -p module=library1@default,library2@default --mode module +``` + +## 测试命令 + +### Instrument Test (设备测试) + +```bash +hvigorw onDeviceTest -p module={moduleName} -p coverage={true|false} -p scope={suiteName}#{methodName} +``` + +- `module`: 执行测试的模块，缺省执行所有模块 +- `coverage`: 是否生成覆盖率报告，默认 true +- `scope`: 测试范围，格式 `{suiteName}#{methodName}` 或 `{suiteName}` +- `ohos-debug-asan`: 是否启用 ASan 检测，默认 false (5.19.0+) + +**输出路径:** +- 覆盖率报告: `/.test/default/outputs/ohosTest/reports` +- 测试结果: `//.test/default/intermediates/ohosTest/coverage_data/test_result.txt` + +### Local Test (本地测试) + +```bash +hvigorw test -p module={moduleName} -p coverage={true|false} -p scope={suiteName}#{methodName} +``` + +**输出路径:** +- 覆盖率报告: `/.test/default/outputs/test/reports` +- 测试结果: `//.test/default/intermediates/test/coverage_data/test_result.txt` + +## 日志级别 + +| 参数 | 说明 | +|------|------| +| `-e, --error` | 设置日志级别为 error | +| `-w, --warn` | 设置日志级别为 warn | +| `-i, --info` | 设置日志级别为 info | +| `-d, --debug` | 设置日志级别为 debug | +| `--stacktrace` | 开启打印异常堆栈信息 | + +## 构建分析 (Build Analyzer) + +| 参数 | 说明 | +|------|------| +| `--analyze=normal` | 普通模式分析 | +| `--analyze=advanced` | 进阶模式，更详细的任务耗时数据 | +| `--analyze=ultrafine` | 超精细化模式，ArkTS 编译详细打点 (6.0.0+) | +| `--analyze=false` | 不启用构建分析 | +| `--config properties.hvigor.analyzeHtml=true` | 生成 HTML 可视化报告到 `.hvigor/report` | + +## 守护进程 (Daemon) + +| 参数 | 说明 | +|------|------| +| `--daemon` | 启用守护进程 | +| `--no-daemon` | 关闭守护进程（命令行模式推荐） | +| `--stop-daemon` | 关闭当前工程的守护进程 | +| `--stop-daemon-all` | 关闭所有工程的守护进程 | +| `--status-daemon` | 查询所有 Hvigor 守护进程信息 | +| `--max-old-space-size=12345` | 设置老生代内存大小 (MB) | +| `--max-semi-space-size=32` | 设置新生代半空间大小 (MB, 5.18.4+) | + +## 性能与内存优化 + +| 参数 | 说明 | +|------|------| +| `--parallel` / `--no-parallel` | 开启/关闭并行构建（默认开启） | +| `--incremental` / `--no-incremental` | 开启/关闭增量构建（默认开启） | +| `--optimization-strategy=performance` | 性能优先模式，加快构建但占用更多内存 (5.19.2+) | +| `--optimization-strategy=memory` | 内存优先模式（默认）(5.19.2+) | + +## 公共命令 + +| 任务 | 说明 | +|------|------| +| `tasks` | 打印工程各模块包含的任务信息 | +| `taskTree` | 打印工程各模块的任务依赖关系 | +| `prune` | 清除 30 天未使用的缓存并删除 pnpm 未引用包 | +| `buildInfo` | 打印 build-profile.json5 配置信息 (5.18.4+) | + +### buildInfo 扩展参数 + +```bash +# 打印工程级配置 +hvigorw buildInfo + +# 打印指定模块配置 +hvigorw buildInfo -p module=entry + +# 包含 buildOption 配置 +hvigorw buildInfo -p buildOption + +# JSON 格式输出 +hvigorw buildInfo -p json +``` + +## 其他参数 + +| 参数 | 说明 | +|------|------| +| `-h, --help` | 打印帮助信息 | +| `-v, --version` | 打印版本信息 | +| `-s, --sync` | 同步工程信息到 `./hvigor/outputs/sync/output.json` | +| `-m, --mode` | 指定执行目录级别 (如 `-m project`) | +| `--type-check` | 开启 hvigorfile.ts 类型检查 | +| `--watch` | 观察模式，用于预览和热加载 | +| `--node-home ` | 指定 Node.js 路径 | +| `--config, -c` | 指定 hvigor-config.json5 参数 | + +## CI/CD 常用命令组合 + +```bash +# 完整的 Release 构建流程 +hvigorw clean && hvigorw assembleApp -p buildMode=release --no-daemon + +# 带构建分析的 Debug 构建 +hvigorw assembleHap -p buildMode=debug --analyze=advanced --no-daemon + +# 运行测试并生成覆盖率报告 +hvigorw onDeviceTest -p coverage=true --no-daemon + +# 内存受限环境构建 +hvigorw assembleHap --optimization-strategy=memory --no-daemon + +# 清理缓存 +hvigorw prune +hvigorw --stop-daemon-all +```