openharmony-build

OpenHarmony 构建技能

使用此技能执行 OpenHarmony 构建、定向构建验证和构建日志诊断。保持上下文精简：从此处开始，然后只加载与任务相符的参考文档。

<skill-dir> 表示包含此 SKILL.md 的目录。

核心规则

• 从同时包含 .gn 和 build.sh 的 OpenHarmony 根目录运行构建。
• 如果用户提供了确切命令，就运行该命令。
• 出现失败时，先检查主要构建日志，再推测源代码修复方案。
• 不要还原工作区中无关的未提交更改。
• 修复后优先进行范围较小的重新构建；条件允许时，再重新运行用户要求的命令。

禁止事项 / 需先征得同意

• 除非用户明确要求进行环境设置，否则绝不运行 repo sync、下载源代码或预构建文件，或进行环境引导；这些操作耗时较长，且可能修改工作区。
• 绝不要仅为通过构建而删除源代码逻辑；应保留行为，并修复真正的依赖、符号或配置问题。
• 如果存在 build.log，绝不要仅凭终端输出末尾诊断构建失败；主要日志才是事实依据。
• 未经确认，绝不要将仓库名称当作 hb build 的部件名称；独立构建需要使用 OpenHarmony 部件名称。
• 绝不要大范围删除 out/、生成的产物或测试二进制文件。除非用户要求清理，否则先征得同意；对于测试列表导致的磁盘空间不足，只能使用 references/test-list-builds.md 中的路径。
• 更改产品、目标、分支或用户提供的命令参数前，先征得同意。

查找根目录

使用以下根目录检查方法：

find_oh_root() {
    local dir="${1:-$PWD}"
    while [[ "$dir" != "/" ]]; do
        if [[ -f "$dir/.gn" && -f "$dir/build.sh" ]]; then
            echo "$dir"
            return 0
        fi
        dir="$(dirname "$dir")"
    done
    return 1
}

命令选择

默认完整构建：

./build.sh --export-para PYCACHE_ENABLE:true --product-name rk3568 --ccache

定向构建：

./build.sh --export-para PYCACHE_ENABLE:true --product-name <product> --build-target <target> --ccache

特殊产品：

• SDK：./build.sh --export-para PYCACHE_ENABLE:true --product-name ohos-sdk --ccache
• Host：./build.sh --product-name host_product --ccache --no-prebuilt-sdk
• 最小模拟器：./build.sh --product-name qemu-arm-linux-min --ccache --no-prebuilt-sdk --deps-guard=false --load-test-config false --gn-args linux_kernel_version=\"linux-5.10\"
• 完整模拟器：./build.sh --product-name arm64_virt --ccache --deps-guard=false

完整的命令矩阵、产品、目标、SDK/Host/模拟器说明和快速重新构建示例，请阅读 references/build-commands.md。

参考文档路由：

• 选择命令语法、产品、目标、SDK/Host/模拟器命令或快速重新构建示例时，阅读 references/build-commands.md。
• 仅在查找或说明构建输出和日志时，阅读 references/log-locations.md。
• 仅在确认具体错误类别后，阅读 references/common-errors.md。

快速重新构建

仅当构建配置未发生变化时，才使用 --fast-rebuild。编辑了 BUILD.gn、*.gni、产品配置、依赖元数据，或首次生成输出后，不要使用此选项。

辅助脚本：

bash <skill-dir>/scripts/check_fast_rebuild.sh 30 "$OH_ROOT"

部件独立构建

适用于“部件独立编译”“独立编译部件”或明确要求运行 hb build 的情况。

command -v hb
hb build <component-name> -i
hb build <component-name> -t

规则：

• 使用 OpenHarmony 部件名称，不一定是仓库名称。
• 将 -i 或 -t 放在部件名称之后。
• 同时要求 -i 和 -t 时，先运行 -i。
• 根据 out/standard/ 中的内容诊断独立构建。

参考文档路由：对于 hb 独立构建，始终阅读 references/independent-build.md；除非任务专门涉及目标列表构建，否则不要加载 references/test-list-builds.md。

测试构建

对于 ACE Engine 开发，优先使用：

./build.sh --export-para PYCACHE_ENABLE:true --product-name rk3568 --build-target ace_engine_test --ccache

仅在用户要求或确有需要时，构建所有单元测试：

./build.sh --export-para PYCACHE_ENABLE:true --product-name rk3568 --build-target unittest --ccache

对于目标列表构建：

bash <skill-dir>/scripts/build_test_list.sh rk3568 "$OH_ROOT"

参考文档路由：对于目标列表构建，阅读 references/test-list-builds.md；除非目标列表运行使用 hb build，否则不要加载 references/independent-build.md。

成功检查

构建成功通常满足以下条件：

• 命令退出代码为 0
• 输出 =====build successful===== 或等效的成功信息
• out/ 下存在预期产物
• 主要构建日志末尾没有致命错误或错误信息

首先依据退出代码判断。只有用户需要确认产物时，才检查产物。

失败分析

始终从主日志入手：

• 常规产品：out/<product>/build.log
• SDK：out/sdk/build.log
• 主机产品：out/host/host_product/build.log
• 独立构建：out/standard/build.log 或相关的 out/standard/ 子日志

广泛手动搜索之前，先使用脚本：

bash <skill-dir>/scripts/resolve_build_log.sh <product> "$OH_ROOT"
bash <skill-dir>/scripts/find_recent_errors.sh <product> "$OH_ROOT"
bash <skill-dir>/scripts/analyze_build_error.sh <product> "$OH_ROOT"

对于 hb build 失败，请将 standard 作为产品传入：

bash <skill-dir>/scripts/find_recent_errors.sh standard "$OH_ROOT"
bash <skill-dir>/scripts/analyze_build_error.sh standard "$OH_ROOT"

参考资料索引：

• 对于非零构建退出、提取首个失败以及修复/重新构建工作流，请阅读 references/failure-analysis.md。
• 日志路径不明确时，请阅读 references/log-locations.md。
• 确认错误类别后，再阅读 references/common-errors.md。

捆绑资源

脚本：

• scripts/resolve_build_log.sh：打印某个产品/根目录的主构建日志。
• scripts/analyze_build_error.sh：汇总主日志中的失败信息。
• scripts/find_recent_errors.sh：快速扫描近期错误。
• scripts/check_fast_rebuild.sh：判断是否适合使用 --fast-rebuild。
• scripts/build_test_list.sh：构建 unittest_targets.txt 中列出的目标。

参考资料：

• references/build-commands.md：完整的命令参考。
• references/log-locations.md：输出和日志路径映射。
• references/common-errors.md：常见失败类别及修复方法。
• references/failure-analysis.md：结构化诊断工作流。
• references/independent-build.md：hb build 规则和诊断模式。
• references/test-list-builds.md：目标列表构建和磁盘空间恢复。

正常执行技能时，不要加载 README.md 或 examples/example-workflow.md；它们是面向仓库的概要说明，而非运行时指令。