jetson-build-source

BSP ソースをビルドする

目的

<source.root_path>/bsp_sources/ 以下の変更から必要となるカーネル側の成果物（DTB、OOT モジュール、ツリー内モジュール、カーネルの Image）を再ビルドし、/jetson-promote-image がこれらの出力を BSP イメージにステージングするために読み取るマニフェストを書き込みます。このスキルが <bsp_image.root_path> 自体に書き込むことはありません。

前提条件

• bsp_image: と source.toolchain: が解決済みのアクティブなターゲットプラットフォームプロファイル（先に /jetson-init-image と /jetson-init-source を実行してください）。
• <source.root_path>/bsp_sources/ に、/jetson-init-source が生成するカーネル側のチェックアウトレイアウトが配置されていること。
• <bsp_image.root_path>/Linux_for_Tegra/source/kernel_src_build_env.sh が存在すること（public_sources.tbz2 から展開されます）。
• ホストパッケージ：flex、bison、libssl-dev（必須）、git、build-essential、bc、zstd（警告のみ）。
• クロスツールチェーンが ${source.toolchain}gcc としてディスク上で解決可能であること。

概要

このスキルはワークフローの Build ステージです。Setup → Customize → Build → Deploy パイプラインにおける位置づけと、実行条件については ../../context/bsp-customization-workflow.md を参照してください。このスキルはソース側のカスタマイズコミットを受け取り、必要な成果物を再ビルドして、再ビルドしたものをマニフェストに記録します。出力は <source.root_path>/bsp_sources/ 内に保持されます。 jetson-promote-image は Deploy 時にマニフェストを読み取り、再ビルドした各成果物を <bsp_image.root_path>/Linux_for_Tegra/ 以下の対応するパスにコピーします。

オーバーレイのみの編集（nvpmodel.conf、nvfancontrol.conf、BPMP DTB）では Build をスキップします。customize-* ステージがこれらをオーバーレイトラッカーに直接反映します。BPMP DTB には ../../references/bsp-customization-bpmp-dtb.md に記載された dtc による逆コンパイル → 編集 → 再コンパイルのループを使用します。

カスタムオーバーレイスロットの所有権。 すべての customize-* スキルによるカーネル DT のカスタマイズは、アクティブな各ターゲットにつき 1 つの複合 tegra<soc>-<carrier-id-sku>+<module-id>-xxxx-custom.dts に集約されます。ファイル名／場所／追記プロトコルについては ../../references/bsp-customization-kernel-dtb.md を参照してください。このスキルが、複合ファイルのディレクトリごとの Makefile 登録（dtbo-y += <name>.dtbo）と、キャリアのフラッシュ設定ファイルにある OVERLAY_DTB_FILE+= 行（「Register composite custom overlay」ステップ）の唯一の管理者です。

ダーティーリポジトリのプロファイルに対応する 4 つのビルドモード：

モード	ビルド対象	自動選択される条件
dt	NVIDIA DTB のみ	hardware/nvidia/* または kernel-devicetree のみが変更されている
oot	OOT モジュール（6 つのリポジトリ）	OOT リポジトリのみが変更されている
kernel	カーネルの Image + ツリー内の全 .ko セット + カーネル側の DTB	kernel/$KERNEL_SRC_DIR のみが変更されている
full	上記すべて + 任意のインストール統合	複数の種類が混在して変更されている

モードの選択：auto（デフォルト。引数なしで /jetson-build-source を呼び出します）では、ダーティーリポジトリのセットを確認します。スキルの引数に指定すると、特定のモードを強制できます。

設計原則：アップストリームに委譲する。 すべてのビルドプリミティブは、すでに <bsp_image.root_path>/Linux_for_Tegra/source/ に用意されています（環境ファイル、トップレベル Makefile の nvidia-dtbs／modules／modules_install、カーネル Makefile の kernel／install）。このスキルは、シェル内でロジックを重複実装することなく、<source.root_path>/bsp_sources/ に対してこれらのプリミティブを実行します。

呼び出すタイミング

• Customize の customize-* 呼び出しでカーネル側のソースリポジトリにコミットが作成された場合、Customize の最後に自動で連続実行されます。
• /jetson-build-source [<mode>] で手動再実行します。次のような場合に使用します。
  • 自動連続実行されたビルドが中断された場合。
  • 他のユーザーから git pull でソースコミットを取り込んだ場合。
  • 新たな編集をせずに再ビルドを強制したい場合。
  • 特定のモードを指定したい場合（たとえば、DUT への手動 scp デプロイ用にインストールを統合する場合）。

手順

アクティブなターゲット、パス、アップストリーム環境の解決

../../context/target-platform-contract.md に従ってアクティブなプロファイルを解決します。 次の場合は処理を拒否し、指定先にルーティングします。

条件	ルーティング先
アクティブなプロファイルがない、または active: NA	/jetson-set-target または /jetson-init-target
プロファイルに bsp_image: がない	/jetson-init-image
プロファイルに source.toolchain: がない	/jetson-init-source
<source.root_path>/bsp_sources/ がない、または空	/jetson-init-source
<bsp_image.root_path>/Linux_for_Tegra/source/kernel_src_build_env.sh がない	/jetson-init-image（BSP が適切に展開されていません）

バインドします。

WORKSPACE=<parent of target-platform/>
BSP_SRC=<bsp_image.root_path>/Linux_for_Tegra/source   # NVIDIA's build primitives
KS=<source.root_path>/bsp_sources                      # our kernel-side checkout
KOUT=<source.root_path>/.build/kernel-out              # DT-mode out-of-tree build dir
STAGE=<source.root_path>/.build/install-stage          # install consolidation (full mode / opt-in)
STATE=<source.root_path>/.build-state.yaml             # per-repo watermark
MANIFEST=<source.root_path>/.build-manifest.yaml       # rebuilt-artifact list for jetson-promote-image

NVIDIA ビルド環境を読み込み、正規の名前を継承します。kernel-noble、OOT モジュールリスト、KERNEL_DEF_CONFIG をハードコードしないでください。

source "$BSP_SRC/kernel_src_build_env.sh"
# Now in scope: KERNEL_SRC_DIR (e.g. kernel-noble), KERNEL_DEF_CONFIG,
# OOT_SOURCE_LIST, kernel_name (e.g. noble), KERNEL_MODULAR_BUILD

$KS/kernel/$KERNEL_SRC_DIR/ がない場合、または $OOT_SOURCE_LIST 内の名前が $KS/ 以下に存在しない場合は処理を拒否します。 /jetson-init-source にルーティングします。

ツールチェーンの解決（読み取り専用）

アクティブなプロファイルから source.toolchain（jetson-init-source が作成）を読み取ります。次を検証します。

export ARCH=arm64
export CROSS_COMPILE=<source.toolchain>   # trailing dash mandatory
[ -f "${CROSS_COMPILE}gcc" ] || refuse \
  "source.toolchain points at ${CROSS_COMPILE}gcc which does not exist. Re-run /jetson-init-source."

CROSS_COMPILE の末尾のダッシュは必須です。kbuild はこれをプレフィックス（${CROSS_COMPILE}gcc）として扱うため、ダッシュがないと command not found で失敗します。[ -f ] チェックにより、make の実行前に検出できます。

このスキルではツールチェーンについてプロンプトを表示せず、不足しているツールチェーンの解決も試みません。これは jetson-init-source のみが担当します。フィールドがない場合はセットアップの不足として、そこにルーティングします。

ビルドホストの前提条件を一度確認します。

for p in flex bison libssl-dev; do
  dpkg -s "$p" >/dev/null 2>&1 || refuse "host package missing: $p"
done
for p in git build-essential bc zstd; do
  dpkg -s "$p" >/dev/null 2>&1 || warn "host package missing: $p"
done

ソースリポジトリの変更検出

ウォーターマークファイル $STATE には、カーネル側のリポジトリごとに、最後に正常にビルドしたコミットが記録されます。リポジトリのリストは、実行時に OOT_SOURCE_LIST と kernel/$KERNEL_SRC_DIR から導出されます。各リポジトリについて、HEAD ≠ ウォーターマークなら変更ありと判定します。コミットされていない編集（git diff --quiet がゼロ以外を返す場合）も変更ありと判定します。

Branch-A に関する注記：bsp_sources/ が .git を1つだけ持つ単一のモノリポジトリの場合、すべての正規サブパスは同じ HEAD を共有します。ウォーターマークのスキーマは引き続きサブパスごとにキーを持ち、変更セットも機能します（どこかに変更があれば、すべてのサブパスの HEAD が変わります）。

STATE がない（初回ビルド）場合、自動チェーンのコンテキストに「Customize just committed」と示されていない限り、すべてのリポジトリをクリーンとして扱います。DIRTY が空でモード引数も渡されていない場合は、「ビルド対象なし」と報告して終了します。

ビルドモードの選択

変更セットからモードをマッピングする（自動）か、モード引数に従います。

変更されたリポジトリ（自動）	モード
hardware/nvidia/* または kernel-devicetree のみ	dt
$OOT_SOURCE_LIST の OOT サブセットのみ	oot
kernel/$KERNEL_SRC_DIR のみ	kernel
上記にまたがる組み合わせ	full

モードは組み合わせ可能です。full は kernel → oot → dt の順に実行します（カーネルは OOT が必要とするヘッダーを生成し、nvidia-dtbs は同じ生成済みヘッダーを使用します）。手動でモード引数を渡した場合、自動検出はスキップされます。

ビルドの実行

共通セットアップとモード別ビルドスニペット

共通セットアップ（オーケストレーターの Makefile を検証し、cd $KS を実行）と、各モード（dt、oot、kernel、full）の正確な make 呼び出し、および任意のインストール統合パスは、references/build-modes.md に記載されています。「アクティブなターゲット、パス、アップストリーム環境の解決」ステップでバインドした値を使用して、該当するモードのスニペットを実行します。

複合カスタムオーバーレイを登録する（dt + full のみ）

選択したモードが dt または full の場合を除き、スキップしてください。複合オーバーレイスロットについては ../../references/bsp-customization-kernel-dtb.md に記載されています。このサブステップでは、そのビルド／Makefile／flash-conf 側を担当します。

アクティブなターゲットに対する複合パス（$COMPOSITE_BASE、 $COMPOSITE_DTS、$COMPOSITE_MK）を、アクティブなプロファイルの チップファミリー、キャリア ID／SKU、モジュール ID を使って解決します。完全なスニペットは references/composite-registration.md を参照してください。

ゲート（対称）。 $COMPOSITE_DTS が両方の方向を決定します。 存在する場合 → 以下の 2 つの冪等パッチを適用します。存在しない場合 → 以前の実行で残った dtbo-y +=／OVERLAY_DTB_FILE+= 行を削除する クリーンアップパス を実行します。どちらの経路でも、OVERLAY_DTB_FILE+= がビルドされていない .dtbo を参照しないようにします。これは、 ツリー内の DT を直接編集しないルール をビルド時に適用するものです。

1. ディレクトリごとの Makefile — 最後の リテラル名 の dtbo-y += エントリーの後に dtbo-y += <name>.dtbo を追加します。 $(old-dtbo) のマージバック行の後に挿入すると、$(addprefix makefile-path/,…) のプレフィックス処理をスキップし、ビルド時に複合オーバーレイが 何も通知されずに除外されます。bsp_sources/ モノレポにコミットします。完全な スニペットと理由は次を参照してください。 references/composite-registration.md。
2. キャリアの flash conf — オーバーレイトラッカーに初回の pristine インポートを行い、 OVERLAY_DTB_FILE+=",<name>.dtbo" を追加します。新しいワークスペースではトラッカーは空の git-init 状態です。bsp_image から conf をインポートし、カスタマイズコミットの 前に pristine: としてコミットします （ワークフローの契約）。完全なスニペットは次を参照してください。 references/composite-registration.md。

customize-* の追加中に複合オーバーレイの親サブリポジトリが HEAD を切り替えることを、 「ダーティなソースリポジトリを検出する」ステップのダーティ検出で利用します。ここで追加の 記録管理を行う必要はありません。

nvidia-dtbs を実行する前のセルフチェック：

grep -qxF "dtbo-y += ${COMPOSITE_BASE}.dtbo" "$COMPOSITE_MK" \
  || refuse "Composite Makefile registration missing after patch."
grep -qxF "$line" "$FLASH_CONF" \
  || refuse "Composite flash-conf registration missing after patch."

ビルドマニフェストを書き込む

DIRTY セットを調べ、ダーティへの追跡ポリシーに従って、該当する成果物ごとにマニフェストエントリーを出力します。ダーティなソースリポジトリまで追跡可能な成果物のみを対象とします。ベースラインの差異によるノイズを昇格させると、カスタマイズの監査証跡に誤って帰属させることになるため、禁止されています。

ソース → kbuild → 出力先の完全なマッピング、YAML スキーマ、フィルタールールについては、 references/manifest-schema.md を参照してください。

アトミック書き込み：${MANIFEST}.tmp にステージングしてから、mv -f を実行します。

ウォーターマークとサマリーを更新する

成功したら、新しいリポジトリごとの HEAD、ツールチェーン、 bsp_image.version、最終実行モードで $STATE を書き換えます（スキーマについては references/manifest-schema.md を参照してください）。

以下を報告します。

• ツールチェーン（source.toolchain から取得）。
• ビルドモード：<dt|oot|kernel|full>（自動選択、またはスキル引数で指定）。
• ダーティなリポジトリと、それぞれの新しい HEAD。
• ビルドした成果物：種類ごとの数（.dtb、ツリー内の .ko、OOT の .ko、Image）。
• マニフェストのパスとエントリー数。
• 統合インストールステージのパス（「インストールの統合」ステップを実行した場合）。
• 次のステップ：/jetson-promote-image。

Customize スキルによってこの実行が開始された場合は、元のリクエストをもう一度送信するようユーザーに促します。

制限事項

最優先の項目 — ビルドを妨げたり、誤った成果物をひそかに生成したりする失敗要因です。不変条件、デプロイパターン、パフォーマンスのヒントについては、 references/long-tail-gotchas.md を参照してください。

• ツールチェーンの解決は jetson-init-source の役割です。 この スキルは source.toolchain を読み取り、CROSS_COMPILE をエクスポートするだけです。 フィールドがない場合は拒否して振り分け、スキル内では決して解決しません。
• R36.x Branch-A の $KS/Makefile 衝突。 R36.x の public_sources.tbz2 により、dGPU/OpenRM のプロプライエタリな Makefile が Tegra オーケストレーターではなく $KS/Makefile に残ることがあります。 その modules ターゲットは kernel-open/ と src/nvidia/ に再帰し、 ホスト側の /lib/modules ヘッダーを取り込むため、arm64 クロスビルドが '-mlittle-endian' unrecognized で失敗します。R38 以降の展開には 影響しません。/jetson-init-source の手順 3a が主な対策（展開時）で、 ここにある「共通セットアップ」のチェックはセーフティネットです。 正規表現を緩めないでください。
• カーネル DT の変更：複合オーバーレイのみ、所有権は分割されています。 bsp_sources/ 配下のツリー内 .dts／.dtsi ファイルを直接編集することは、 customize-* スキルでは禁止されています。カーネル DT の変更はすべて、 複合オーバーレイスロットのフラグメントとして追加します （ルールと根拠）。 複合 .dts の内容は各 customize-* スキルが担当し、 ビルド／Makefile／flash-conf への登録はこのスキルが担当します （複合 .dts が存在する場合に限って登録します。そのため、 OVERLAY_DTB_FILE+= が未ビルドの .dtbo を参照することはありません）。
• 「複合カスタムオーバーレイを登録する」手順では、Makefile への挿入位置が重要です。 最後にあるリテラル名の dtbo-y += エントリーの後に挿入してください。 $(old-dtbo) の後に挿入すると、$(addprefix makefile-path/,…) の プレフィックス処理を通らず、ビルド時に .dtbo がひそかに除外されます。 正規表現 ^dtbo-y *+= *[a-zA-Z0-9] は適切に絞り込むため、緩めないでください。
• 「複合カスタムオーバーレイを登録する」手順の初回処理には、未変更のインポートが必要です。 新規ワークスペースでは、オーバーレイトラッカーは空の git-init 状態です。 キャリアの flash conf は bsp_image からインポートされ、カスタマイズの コミット前に pristine: としてコミットされます。どちらのコミットも ワークフローの受け入れゲートを通ります。
• この SKILL.md 内のシェルスニペットで、単独の $0 を使わないでください。 引数付きで呼び出されると、モデルにレンダリング済みプロンプトを渡す前に、 ハーネスがスキル本文内の $0 を呼び出し元の $0 で展開します。 sed による行の挿入、または awk -v ROW="$0" を使用してください。 詳しくは references/composite-registration.md を参照してください。
• オーバーレイのステージングはしません。 ビルド出力はビルドによって配置された場所に残します。マニフェストが jetson-promote-image との契約です。 これは元のオーバーレイからプロモートへの間接処理とは意図的に異なり、 ビルド出力一式がオーバーレイトラッカーの Git 履歴に入るのを防ぎます。
• DT モードでの KERNEL_HEADERS と KERNEL_OUTPUT。 意味が異なります（srctree と objtree）。「DT のみ」手順のスニペットは記載どおりで正しいため、統合しないでください。
• OOT モードの前提条件：カーネルヘッダーが事前にビルドされていること。 一度もビルドされていないツリーに対して手動で oot を呼び出すと、わかりにくいビルドエラーを出すのではなく、「先に kernel（または full）を実行してください」と表示して拒否します。

例

変更のあるソースツリーからモードを自動検出します（通常の呼び出し）：

/jetson-build-source

単一のモードを強制します（自動検出をスキップ）：

/jetson-build-source dt       # rebuild NVIDIA DTBs only
/jetson-build-source oot      # rebuild OOT modules only
/jetson-build-source kernel   # rebuild kernel Image + in-tree modules
/jetson-build-source full     # rebuild everything + install consolidation

customize-* スキルがカーネル側のリポジトリにコミットした後の通常の連鎖（customize-* スキルが自動的に呼び出します）：

/jetson-customize-pcie ...   # commits to hardware/nvidia/.../nv-public
   ↓
/jetson-build-source         # auto-picks `dt` from the dirty set
   ↓
/jetson-promote-image        # reads .build-manifest.yaml, stages into bsp_image
   ↓
/jetson-flash-image          # flashes

トラブルシューティング

エラー	原因	解決方法
source.toolchain points at <...>gcc which does not exist	ツールチェーンのフィールドが古い（パスが移動した、またはインストールされていない）	/jetson-init-source を再実行して、解決し直してください。このスキル自体はツールチェーンを解決しません。
No rule to make target '$KOUT/scripts/Makefile.compiler'	KERNEL_HEADERS が $KS/kernel/$KERNEL_SRC_DIR ではなく $KOUT に設定されている	references/build-modes.md の DT モードのスニペットをそのまま使用してください。srctree と objtree を統合してはいけません。
make modules 中の '-mlittle-endian' unrecognized	R36.x Branch-A の $KS/Makefile の衝突。Tegra オーケストレーターの代わりに dGPU/OpenRM の Makefile が配置されている	通常は共通セットアップのセーフティネットが修復します。修復されない場合は、git checkout HEAD -- Makefile を実行してから、/jetson-init-source の手順 3a を再実行してください。
oot の手動実行時に run kernel (or full) first	カーネルソースツリーが準備されていない	/jetson-build-source kernel（または full）を一度実行してから、oot を実行してください。
編集内容が未コミットなのに nothing to build と表示される	サブリポジトリ内の編集が未コミットだが、.build-state.yaml のウォーターマークがすでに HEAD と一致している	編集内容をコミットするか、モード引数を明示して再実行してください（例：/jetson-build-source dt）。
複合 .dtbo が出力セットにひそかに含まれない	ディレクトリごとの Makefile への挿入が、$(old-dtbo) のマージバック行の後に行われた	references/composite-registration.md を参照してください。最後の リテラル名付き dtbo-y += エントリーの後に挿入してください。
Promote 手順で古いベースラインのアーティファクトがコピーされる	$KS への手動 cp の後に、トレースから変更ファイルへのフィルターがスキップされた	customize-* スキルまたは git 経由でのみ編集してください。変更検出はファイルの mtime ではなく、git HEAD を基準にします。
host package missing: <pkg>	flex／bison／libssl-dev がない場合はエラーになり、その他は警告される	references/upstream-recipe.md に従って sudo apt install <pkg> を実行してください。

関連項目

• references/build-modes.md — モードごとの make スニペットと、インストールの統合。
• references/manifest-schema.md — .build-manifest.yaml と .build-state.yaml のスキーマ。
• references/composite-registration.md — 「複合カスタムオーバーレイの登録」手順の全スニペットと根拠。
• references/long-tail-gotchas.md — 不変条件、デプロイパターン、パフォーマンスのヒント。
• references/upstream-recipe.md — NVIDIA のレシピ全文、相違点、仕様のステータス。
• ../../context/bsp-customization-workflow.md — ワークスペース編集プロトコル。
• ../../references/bsp-customization-kernel-dtb.md — 複合カスタムオーバーレイの契約。
• ../../references/bsp-customization-bpmp-dtb.md — BPMP-DTB 編集の契約（このスキルを経由しない経路）。
• ../jetson-init-source/SKILL.md — セットアップ。source.toolchain を作成します。
• ../jetson-promote-image/SKILL.md — デプロイプロモーター。このスキルのマニフェストを読み取ります。