arkweb-build

Name: arkweb-build
Author: openharmonyinsight

github.com/openharmonyinsight開発3540 回インストール11 週間前に更新

リポジトリ

arkweb-build について

arkweb-buildは、ArkWeb開発者向けにビルドの実行・検証とログに基づく失敗診断を行うスキルです。増分ビルドを既定とし、コード変更との照合を優先して、プロジェクト内で修正した後に再検証します。

主な機能

01ArkWebビルドの実行と検証
02ターゲットと再開方法の選択
03ビルドログによる失敗分類
04Git変更との照合による原因特定
05プロジェクト内の修正と再ビルド

活用シーン

01初回または増分ビルドの開始
02ビルド成功の確認
03ログに基づくビルド失敗の診断
04プロジェクト内の修正と再検証

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/openharmonyinsight/openharmony-skills --skill arkweb-build

インストール後、Claude Code で/arkweb-buildを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

README.md

examples/

example-workflow.md

references/

build-commands.md

common-errors.md

log-locations.md

scripts/

analyze_build_error.sh

capture_resource_snapshot.sh

check_lfs_artifacts.sh

find_recent_errors.sh

inspect_build_state.sh

show_relevant_changes.sh

詳細

ArkWeb ビルドスキル

このスキルでは、build_arkweb.sh を使った ArkWeb プロジェクトのビルド、結果の検証、および src/out/<product>/build.log に基づく失敗の診断を行います。

GNU coreutils と /proc を利用できる Linux ビルドホストが必要です。

このスキルを使用する場面

ユーザーが次のことを希望する場合に使用します。

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 status と diff には、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：GN または Ninja の実行前に発生する、SDK のインストール、アーカイブの展開、Git LFS ポインター、パッケージ不足、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 ターゲットエラーがない場合です。リソース不足の疑いとして扱い、コードを変更する前に最新のスナップショットを確認します。

1 つのコマンドによる簡易検証は、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 つのコマンドによる検証を使用しないでください。

実行ルール

ラッパーのルートを特定し、そこから実行します。
ワークフローでコマンドが指定されている場合は、そちらを優先します。
ビルドはフォアグラウンドで実行し、実際の終了コードが返るまで待ちます。
タイムアウトは長めに設定します。最大待機時間の既定値は4時間です。
終了コードが 0 の場合は成功とします。ゼロ以外の終了、シグナルによる終了、タイムアウトはすべて失敗です。
失敗した場合は、src/out/<product>/build.log を確認し、その後すぐに bash <skill-dir>/scripts/show_relevant_changes.sh <arkweb-root> を実行して、関連する最近の開発者変更と照合します。最初にデフォルトの変更エントリが除外されていることを確認してください。
ビルドを実行する前に、src/out/<product>/build.log が存在するかを確認し、初回ビルドの可能性が高い場合は呼び出し元に伝えます。
Ninja フェーズのリソーススナップショットを記録します。build_arkweb.sh の場合は、外部ベースラインとしてビルドの起動直前に取得します。Ninja を直接再開する場合は、ninja コマンドの直前に取得します。
コンパイラーまたはリンカーのエラーがなく、プロセスが単に消えてビルドが停止した場合は、まず CPU またはメモリの負荷を疑います。他の原因を検討する前に、最新のリソーススナップショットを確認してください。
このように原因不明で停止した場合は、通常はまず並列度を -j 32 に下げ、負荷が高い状態が続く場合は -j 16 に下げることを積極的に提案します。
src/out/<product>/args.gn がすでに存在し、ユーザーが同じインクリメンタルビルドを明らかに続けている場合は、src/ から ninja -C out/<product> <targets> を直接再実行してもかまいません。前回のビルドと同じターゲットセットを使い、適当な単一ターゲットに変更しないでください。build_arkweb.sh の失敗を隠す目的で Ninja の直接実行に切り替えてはいけません。
ビルドエラーが発生した場合、既定の手順では、エラー概要を出すだけでなく、診断 -> 修正 -> 再ビルド -> 再検証の全サイクルを完了します。
ninja-compile-link の失敗では、問題を修正した後の簡易ローカル確認として、scripts/analyze_build_error.sh が表示する失敗したコマンドと作業ディレクトリを使用します。それが成功したら、新しいリソーススナップショットを記録し、その後 cd <arkweb-root> を実行して、設定済みの build_arkweb.sh コマンドをもう一度実行します。意図的に直接 Ninja でターゲットセットを再実行する場合に限り、<arkweb-root>/src を使用します。
問題の修正では、現在の ArkWeb プロジェクト内で変更が許可されているファイルのみを編集します。src/ohos_sdk/ には触れず、プロジェクトディレクトリ外のサーバーファイルも変更しないでください。
より迅速かつ正確に収束させるため、まず現在の 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 とメモリの余裕を記録し、ビルドが無言で終了した場合に、リソース不足が原因である可能性を診断できるようにします。第 1 引数は製品名です。ラベル付き形式では ArkWeb ルートは第 3 引数、短縮形式では第 2 引数です。
scripts/show_relevant_changes.sh は、想定される変更ファイルをフィルタリングし、src リポジトリと src/arkweb リポジトリそれぞれの関連する Git の変更を分けて表示します。 git status --short -uall を使用し、デフォルトでは無視される変更項目を表示します。完全な未加工の表示が必要な場合は、--show-all／--no-ignore を指定できます。

以下のコマンドでは、<skill-dir> はこの SKILL.md があるディレクトリを意味します。

参照先：

出力に含める内容

適切なビルドの回答には、次の内容を含める必要があります。

実行したコマンドの正確な内容
作業ディレクトリ
製品とターゲット
終了ステータス
確認したログのパス
失敗した場合は、失敗の種類と場所
次に行う最小限の修正、または実行するコマンド

Markdown 対応

ログインしてコメント

基本情報

作者: openharmonyinsight
リポジトリ: openharmonyinsight/openharmony-skills
カテゴリ: 開発
インストール数: 40
GitHub スター: 35

問題を報告