arkweb-build

ArkWeb 构建技能

此技能支持通过 build_arkweb.sh 构建 ArkWeb 项目、验证构建结果，并根据 src/out/<product>/build.log 诊断故障。

需要 Linux 构建主机，并具备 GNU coreutils 和 /proc。

何时使用此技能

用户希望执行以下操作时，请使用此技能：

• 执行 ArkWeb 构建
• 选择合适的 ArkWeb 构建目标
• 验证构建是否确实成功
• 根据日志诊断 ArkWeb 构建失败
• 不清理代码树，继续执行 ArkWeb 增量构建

项目根目录规则

ArkWeb 封装根目录在当前工作区中通常为 arkweb_* 目录，且包含：

• build_arkweb.sh
• src/arkweb/build/build.sh

构建命令必须从封装根目录运行，而不是从 src/ 运行。

请使用此辅助工具从代码树中的任意位置查找根目录：

find_arkweb_root() {
  local dir="${1:-$PWD}"
  while [[ "$dir" != "/" ]]; do
    if [[ -f "$dir/build_arkweb.sh" && -f "$dir/src/arkweb/build/build.sh" ]]; then
      echo "$dir"
      return 0
    fi
    dir="$(dirname "$dir")"
  done
  echo "ArkWeb root not found" >&2
  return 1
}

对于 git 状态和差异，请使用 src/ 下的实际工作树：

git -C "$(find_arkweb_root)/src" status --short

注意：src 和 src/arkweb 是两个不同的 git 仓库。arkweb 仓库位于 src/ 下，但诊断变更时必须分别检查这两个仓库。

配置优先级

如果调用方已提供工作流或构建配置，请勿用默认值替换：

• context.automation.buildCommands
• context.automation.verifyCommands
• context.automation.buildTarget
• context.automation.buildOutputDir
• context.automation.buildTimeoutMinutes

只有在配置不完整时，才使用下方的默认命令。

默认构建行为

默认执行增量构建。除非用户明确要求清理构建，否则不要清理代码树。

绝不要自动执行以下操作：

• git clean
• git reset --hard
• rm -rf src/out
• gn clean
• ninja -t clean
• 仅为“获得干净环境”而重新同步依赖项

开始构建前，务必先检查当前产品是否曾经构建过。请将 src/out/<product>/build.log 是否存在作为主要判断依据：

if [[ -f <arkweb-root>/src/out/rk3568_64/build.log ]]; then
  echo "Incremental build path"
else
  echo "First build path"
fi

如果 build.log 尚不存在，则将其视为首次构建，除非调用方提供了更有力的证据。首次构建通常耗时更长，运行前应明确说明：

• 预计耗时：约 2 到 3 小时
• 不要将其误称为普通增量构建
• 不要仅因构建长时间停留在设置或预构建阶段，就过早判断其卡住

默认主要命令：

cd <arkweb-root>
./build_arkweb.sh rk3568_64 -t w -A

最常见的变体列于 references/build-commands.md。

修复责任和变更范围

构建失败时，不要仅提取并报告错误。默认应继续分析根本原因、实施允许的修复，并重新运行构建以验证结果。

允许的修复：

• 修改当前 ArkWeb 代码树中的源文件、BUILD.gn / .gni、ArkWeb 自有构建脚本或项目配置
• 为当前项目恢复缺失的 Git LFS 资源，或在当前项目中重新运行构建命令
• 调整构建目标、恢复策略或并行度，然后再次构建以进行验证

明确禁止的变更：

• 不得修改 <arkweb-root>/src/ohos_sdk/ 下的工具链、SDK 归档文件、安装脚本或其他预构建载荷
• 不得修改当前 ArkWeb 项目目录之外的服务端文件，包括其他检出目录、全局环境文件、系统目录或用户主目录下无关的文件

如果问题只能通过改动上述禁止区域来绕过，请明确说明此限制，并改用项目内的替代方案，例如：

• 重新检查并恢复当前项目的 Git LFS 资源
• 在当前项目中修复依赖项、目标配置或源代码错误
• 降低并行度后重新运行构建

优先检查改动，诊断问题

为了更快定位构建失败，请先检查开发者改了什么，再扩大搜索范围。大多数构建失败都由当前补丁引入，因此通常从 git 入手，能更快、更准确地找到最小修复方案。

ArkWeb 代码树通常自带一些默认的未提交文件，不应将其视为开发者的改动。请从随附的过滤脚本开始：

• bash <skill-dir>/scripts/show_relevant_changes.sh <arkweb-root>

随附脚本内置的过滤规则：

• 按目录前缀忽略整个 third_party/rust-toolchain/ 目录
• 按目录前缀忽略整个 third_party/rust/chromium_crates_io/ 目录
• 在 src 仓库中，还要忽略以下默认噪声条目： third_party/ohos_ndk/includes/ohos_adapter/screenlock_manager_adapter.h、 third_party/ohos_nweb_hap/hvigor/、 third_party/ohos_nweb_hap/signature/
• 在 src/arkweb 仓库中，还要忽略以下默认噪声条目： build/search_engines/prepopulated_engines.json

如果仍需要查看更详细的原始 git 信息，请接着检查：

• git -C <arkweb-root>/src status --short
• git -C <arkweb-root>/src diff --stat
• git -C <arkweb-root>/src diff --cached --stat
• git -C <arkweb-root>/src/arkweb status --short
• git -C <arkweb-root>/src/arkweb diff --stat
• git -C <arkweb-root>/src/arkweb diff --cached --stat
• 如果 build.log 已指向某个文件、目标或符号，请用 git diff 检查相应路径

诊断规则：

• 先将日志中的失败文件、目标或缺失符号与开发者当前的改动关联起来
• 在判断哪些改动与失败真正相关之前，先过滤默认的未提交条目
• 如果当前补丁已经足以解释失败，就不要将搜索范围扩大到无关目录或目标
• 以最小修复为目标，通常在引入问题的改动代码或依赖声明附近修复
• 只有当当前 git 改动无法解释问题时，才扩大到更广泛的项目级调查

失败阶段分类

选择重新运行策略前，先根据 build.log 对失败阶段进行分类：

• pre-gn/sdk-lfs：SDK 安装、压缩包解压、Git LFS 指针、缺少软件包，或 GN、Ninja 启动前出现 gzip/tar/unzip 错误。修复资源文件或配置后，再运行已配置的构建命令。
• gn-generation：出现 ERROR at //...、Unable to load、BUILD.gn 或 .gni 求值错误。修复 GN 配置后，再运行 GN 或已配置的构建命令。
• ninja-graph-or-target：出现 ninja: error: unknown target、缺少 build.ninja，或 Ninja 图加载错误。修复目标选择或生成的构建图后，再运行已配置的目标集。
• ninja-compile-link：Ninja 启动后发生编译器或链接器错误，例如 FAILED:、fatal error:、undefined reference、multiple definition、ld.lld: error 或 clang++: error。
• resource-or-terminated：明确出现 killed 或 OutOfMemory。
• resource-or-terminated-suspected：日志末尾看起来仍是 Ninja 进度，且没有 FAILED:、GN 错误或 Ninja 目标错误。将此情况视为资源压力的疑似迹象；更改代码前先检查最新快照。

单命令快速验证仅适用于 ninja-compile-link。修复该根因后，先运行 cd <arkweb-root>/src/out/<product>，然后重新运行 build.log 中首个 FAILED: 行之后显示的失败编译器或链接器命令（如果有）。该命令是相对于 Ninja 输出目录生成的，因此从封装脚本根目录或 src/ 运行可能会导致错误。如果该命令成功，再切换回正确目录进行更广泛的验证：运行完整的 build_arkweb.sh 命令时使用 <arkweb-root>；仅在有意重新运行同一组直接 Ninja 目标时使用 <arkweb-root>/src。进行更广泛的验证前，仍须使用 scripts/capture_resource_snapshot.sh 记录资源快照。不要对 pre-gn/sdk-lfs、gn-generation 或 ninja-graph-or-target 使用单命令验证。

执行规则

1. 确定封装根目录，并从该目录执行。
2. 如果工作流提供了命令，优先使用这些命令。
3. 在前台运行构建，并等待实际退出码。
4. 使用较长的超时时间。默认最长等待时间：4 小时。
5. 将退出码 0 视为成功。任何非零退出码、信号终止或超时都视为失败。
6. 失败时，检查 src/out/<product>/build.log，然后立即通过 bash <skill-dir>/scripts/show_relevant_changes.sh <arkweb-root> 对照近期的开发者改动，以便先过滤掉默认的脏工作区条目。
7. 运行构建前，检查 src/out/<product>/build.log 是否存在，并告知调用方这是否可能是首次构建。
8. 为 Ninja 阶段记录资源快照。对于 build_arkweb.sh，在启动构建前立即采集，作为外部基线。对于直接续跑 Ninja，在执行 ninja 命令前立即采集。
9. 如果构建停止时没有编译器或链接器错误，且进程只是消失，首先怀疑 CPU 或内存压力。得出其他结论前，检查最新的资源快照。
10. 在这种无提示停止的情况下，主动建议降低并行度，通常先用 -j 32；如果压力仍然很高，再用 -j 16。
11. 如果 src/out/<product>/args.gn 已存在，且用户显然是在继续同一次增量构建，则可以从 src/ 直接重新运行 ninja -C out/<product> <targets>。沿用上一次构建的同一组目标，不要随意换成单个目标。不要仅为了掩盖 build_arkweb.sh 的失败而改用直接运行 Ninja。
12. 构建出错后，默认流程是完整执行“诊断 -> 修复 -> 重新构建 -> 重新验证”，而不只是总结错误。
13. 对于 ninja-compile-link 失败，修复问题后，使用 scripts/analyze_build_error.sh 显示的失败命令和工作目录进行快速本地检查。检查成功后，记录新的资源快照，然后先 cd <arkweb-root>，再重新运行完整配置的 build_arkweb.sh 命令；只有在有意通过直接运行 Ninja 重新构建指定目标集时，才使用 <arkweb-root>/src。
14. 修复问题时，只修改当前 ArkWeb 项目内允许修改的文件。不要触碰 src/ohos_sdk/，也不要修改项目目录外的服务器文件。
15. 为更快、更准确地解决问题，先尝试根据当前 git 改动解释失败原因，并尽量将修复限制在最小范围内，不要编辑无关文件。

日志和诊断

主要日志位于：

<arkweb-root>/src/out/<product>/build.log

启动新构建时，旧日志通常会轮转为带时间戳的文件名。

始终先检查日志末尾：

tail -200 <arkweb-root>/src/out/<product>/build.log

如果信息不够，请搜索：

• error:
• fatal error
• undefined reference
• multiple definition
• ERROR at
• No such file
• cannot find
• killed
• OutOfMemory

使用随附的脚本：

• scripts/analyze_build_error.sh：生成结构化摘要、失败阶段分类、首个错误的上下文，以及失败的 Ninja 命令候选项。接受 <product> <arkweb-root> 或 <build.log> <arkweb-root>。
• scripts/find_recent_errors.sh：快速扫描近期错误
• scripts/inspect_build_state.sh：检查可用的输出目录和近期日志
• scripts/check_lfs_artifacts.sh：解析相关的 LFS 属性文件，检查必需的预构建文件，并检测缺失文件或 LFS 指针文件
• scripts/capture_resource_snapshot.sh：在 Ninja 阶段开始前记录 CPU 和内存余量，以便诊断可能由资源压力导致的无提示构建退出。第一个参数是产品名称；在带标签的形式中，ArkWeb 根目录是第三个参数，在简写形式中则是第二个参数。
• scripts/show_relevant_changes.sh：筛选预期的脏文件，并分别显示 src 仓库和 src/arkweb 仓库中的相关 git 变更 它使用 git status --short -uall，打印默认忽略的脏文件条目；需要查看完整原始内容时，可使用 --show-all / --no-ignore。

以下命令中的 <skill-dir> 指包含此 SKILL.md 的目录。

参见：

• references/build-commands.md
• references/common-errors.md
• references/log-locations.md
• examples/example-workflow.md

输出要求

优秀的构建答复应包含：

• 使用的确切命令
• 工作目录
• 产品和目标
• 退出状态
• 已检查的日志路径
• 失败时的失败类型和位置
• 最精简的后续修复方案或命令