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
• ホスト：./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／ホスト／エミュレーターに関する注意事項、高速再ビルドの例については、references/build-commands.md を読んでください。

リファレンスの参照先：

• コマンドの構文、製品、ターゲット、SDK／ホスト／エミュレーターのコマンド、高速再ビルドの例を選ぶ場合は、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 はコンポーネント名の後に指定します。
• 両方を指定する場合は、-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 を読み込まないでください。これらはリポジトリ向けの概要であり、実行時の指示ではありません。