再現可能な Buildroot システム納品：起動イメージからリリース一式へ

Buildroot イメージが納品物として成立するのは、別のエンジニアが再ビルドし、内容を正確に特定し、元の開発者のワークステーションに頼らず対象機器を復旧できるようになったときです。ゲートウェイや操作端末では、ソース、設定、ビルド環境、イメージ構成、受入試験の証拠を一つのリリースとして扱う必要があります。起動する SD カードは、その工程の成果物の一つにすぎません。

納品条件で「再現可能」の意味を定義する

受入条件を二つに分けます。再ビルド可能なリリースには、保存した入力から意図した機能を作り出せる完全な手順があります。バイト単位で再現可能なリリースでは、それに加えて、明示した成果物群のバイト列が一致します。後者は Reproducible Builds の定義に沿うもので、設定項目を有効にするだけでなく、比較の証拠が必要です。

対象成果物を列挙します。カーネル、デバイスツリー、ルートファイルシステム、ブートローダー、必要に応じてディスク全体のイメージです。署名付きコンテナーや製造時の個別設定を比較範囲に含めるかも明記します。機器固有の識別情報は汎用イメージとは別に書き込むべきです。そうしなければ、機器ごとのバイト列が異なるのは当然です。秘密署名鍵はソースの納品パッケージやビルドログに含めません。

入力一式を固定する

製造用イメージを生成する前に、リリースマニフェストを作成します。Buildroot と製品設定のリビジョン、アプリケーションのコミット、カーネルとブートローダーのリビジョン、外部ツールチェーンを使う場合のダイジェスト、すべてのベンダーパッチを特定できるようにします。基板リビジョンと実装されたストレージ構成も含めます。同じファイル名のアーカイブが複数存在する場合、「ベンダー SDK」という記載では不十分です。

製品固有の変更は、バージョン管理した BR2_EXTERNAL ツリーに保存します。対象は defconfig、カーネル設定、デバイスツリー変更、オーバーレイ、パッケージレシピ、イメージ生成スクリプトです。解決済みの .config もリリース証拠として保存します。納品には output/images の生成物を使います。中間生成物の target ツリーは、最終的な権限やデバイスファイルの処理を備えた配備用ルートファイルシステムではありません。これらの仕組みは Buildroot マニュアルに記載されています。

独自バイナリーごとに、供給元、バージョン、チェックサム、対象 ABI、再配布条件を記録します。再配布可能なバイナリーはソースを入手できなくても固定入力にできますが、その境界を納品説明に明記する必要があります。上流 URL が製品の保守期間を通じて存続すると仮定せず、ダウンロードの継続利用を管理する担当者を決めます。

環境とソースを再構築できるようにする

Linux ビルド環境、コンテナーまたは VM イメージのダイジェスト、ホスト側パッケージ、アーキテクチャ、必要リソースを記録します。ソースと出力には安定した絶対パスを使います。Buildroot の BR2_REPRODUCIBLE は実験的機能のままであり、設定ヘルプにはパスに関する制約と、再現可能にならない場合があるパッケージについて説明があります。新しいブランチも同じ動作をすると考えず、固定したリリースのヘルプを確認してください。

承認済みのソースキャッシュを保持し、ダウンロードのハッシュを検証します。キャッシュは再ビルドを容易にしますが、それだけでソースの真正性を証明しません。依存関係を取得した後、外向きネットワークを無効にして別途再ビルドします。失敗した場合は、不足した入力を具体的に記録し、コンパイル中に未記録の依存物を黙ってダウンロードさせないようにします。

以下はリリースジョブの例です。パスと product_defconfig はプロジェクトで定義し、コミット済みの defconfig で再現可能ビルドを有効にします。クリーンな環境で、非特権のビルドユーザーとして実行します。

export BR=/work/buildroot
export EXT=/work/product
export OUT=/work/out
export LC_ALL=C TZ=UTC
export SOURCE_DATE_EPOCH="$(git -C "$EXT" log -1 --format=%ct)"
make -C "$BR" O="$OUT" BR2_EXTERNAL="$EXT" product_defconfig
make -C "$BR" O="$OUT" source
make -C "$BR" O="$OUT"
make -C "$BR" O="$OUT" legal-info

SOURCE_DATE_EPOCH は、対応ツールに対してソースに関連する安定したタイムスタンプを提供します。任意のビルドスクリプトを決定論的にするものではありません。選定した Buildroot リリースがこの値をどう伝搬するか確認し、独自スクリプトが現在時刻を使っていないか調べます。意味は SOURCE_DATE_EPOCH の文書で定義されています。

独立した二つのクリーンビルドを比較する

記録した同じパスを使い、二つの新しい環境で同じ手順を実行します。次のジョブを始める前に両方の出力を保管します。まず正確な成果物一覧とチェックサムを比較します。次の二つのファイルを生成する製品を例にすると、以下のようになります。

cd /work/out/images
sha256sum Image rootfs.squashfs > /work/release/SHA256SUMS

あらかじめ /work/release を作成し、このファイル一覧をデバイスツリーや起動部品を含む実際のリリースマニフェストに置き換えます。rootfs の一致だけでは、ディスク全体のイメージの一致を証明できません。チェックサムが異なる場合は diffoscope で内包ファイル、メタデータ、アーカイブの差を調べ、比較レポートを保存します。

フラグを変更する前に差異を分類します。カーネルのビルド時刻、ユーザー名とホスト名、デバッグパス、自動生成されるモジュール署名鍵は、カーネル再現可能ビルドのガイドに記載された変動要因です。そのほか、ファイルシステム UUID、イメージ生成時刻、未ソートのファイル一覧、アプリケーションのバージョンスクリプトも調査対象になります。署名工程を分離して定義・試験する場合も、安全要件は維持します。

コンパイル結果だけでなくリリースを試験する

この表とともに、起動時間の測定終点、最大メモリー使用量、ストレージ余裕、ネットワーク動作、ウォッチドッグ復旧など、測定できる製品の限界値を定義します。数値は実際の要件から設定します。本文は検証計画の説明であり、特定基板の実測結果ではありません。

よくある引き継ぎ不良と切り分け

• クリーンビルドは失敗するが開発者のビルドは成功する：ローカルソースの上書き、未コミットのパッチ、ホストにインストールされたツールを確認します。依存関係を変更する前に、保存した環境で再現します。
• 外したパッケージがイメージに残る：新しい出力ツリーで再ビルドします。設定変更後の増分開発出力は、リリース基準として不適切です。
• アプリケーションが一枚の基板でしか起動しない：Buildroot を疑う前に、基板リビジョン、デバイスツリー、ファームウェアバイナリー、ストレージ構成を比較します。
• イメージは一致するが復旧できない：起動選択、パーティションオフセット、復旧手順を調べます。再現可能性は書き込み手順の検証にはなりません。
• ライセンス資料が一式そろって見える：legal-info/README の警告と不足資料を確認します。Buildroot の収集物はコンプライアンス確認の入力であり、法的な承認を自動で与えるものではありません。

別の担当者が使えるリリース一式を渡す

README にサポート対象のビルド開始手順を一つ示し、マニフェスト、チェックサム、ソース取得方法、設定、イメージ、リリースノート、試験証拠、復旧手順をまとめます。既知の制約、更新互換性、今後のセキュリティ修正の責任も記録します。元のワークステーションにアクセスできない状態で引き継ぎ演習を実施し、納品物を検証します。

作業範囲の相談には、起動、カーネル、rootfs の統合に関係する Obeita のファームウェア・BSP 診断サービスを参照できます。RK3566 組み込み端末の納入事例は、関連するプラットフォームの背景を提供します。この事例は、本文の再現可能ビルド工程をそのプラットフォームで実装または検証した証拠ではありません。