Yocto Project は、組み込み機器向けにカスタム Linux ディストリビューションをゼロからビルドするためのフレームワークです。ルーターや産業機器、車載システムに搭載される Linux はこの仕組みで作られることが多く、「自分専用の小さな Linux を作りたい」という目標の出発点になります。
本記事では Ubuntu 24.04 LTS（Docker 公式イメージで実行）で Yocto ビルド環境を構築し、ビルド準備が整うまでの全手順を実際のコマンド出力とともに紹介します。フルビルド（bitbake core-image-minimal）は数時間〜十数時間かかるため本記事では扱いませんが、環境セットアップから bitbake コマンドを打てる状態まで確実に動かせます。
この記事のポイント
- Ubuntu 22.04 と 24.04 の両方で Yocto ホスト依存パッケージが問題なくインストールできることを実測確認した
- poky リポジトリ（Scarthgap ブランチ）を shallow clone し、BitBake 2.8.1 が起動するところまで実際に動かした
oe-init-build-envを実行するとconf/local.confとconf/bblayers.confが自動生成される- ビルドホストの CPU 性能が build 時間に直結する（本記事の検証環境: sysbench 4スレッド平均 27,452 events/sec）
- フルビルドには 90GB 以上のストレージが必要（公式ドキュメントによる）
Yocto Project とは
Yocto Project は Linux Foundation 傘下のオープンソースプロジェクトで、組み込み向けの Linux ディストリビューションを「レイヤー」と「レシピ」の組み合わせでビルドする仕組みを提供しています。Ubuntu や Debian のように完成品を受け取るのではなく、カーネル・ドライバ・ライブラリ・アプリを自分でパッケージ選択してビルドするのが最大の特徴です。
中心的なコンポーネントは BitBake（ビルドエンジン）と poky（リファレンスディストリビューション）です。poky は OpenEmbedded の meta レイヤーと BitBake、そしてリファレンス設定を束ねたリポジトリで、Yocto 入門の起点として公式ドキュメントでも紹介されています。
動作確認済み環境
今回の検証は以下の環境で実施しました。
No LSB modules are available.
Distributor ID: Ubuntu
Description: Ubuntu 24.04.1 LTS
Release: 24.04
Codename: noble
Yocto Project（Scarthgap 5.0 系列）は Ubuntu 22.04 LTS と Ubuntu 24.04 LTS の両方を公式サポートしています。本記事は 24.04 を主軸に進めますが、22.04 でも同じコマンドが通ることを後述の比較表で実測済みです。
ストレージ要件に注意
Yocto のフルビルドには最低 90GB のディスク空き容量が必要です（公式ドキュメント記載）。ダウンロードキャッシュを含めると 100GB 以上を見込んでおくと安全です。
手順1 — ホスト依存パッケージをインストールする
Yocto のビルドツールは、ホスト OS に複数のパッケージを要求します。公式ドキュメントにリストアップされているパッケージを一括でインストールします。
$ sudo apt-get install -y \
gawk wget git diffstat unzip texinfo gcc build-essential \
chrpath socat cpio python3 python3-pip python3-pexpect \
xz-utils debianutils iputils-ping python3-git python3-jinja2 \
python3-subunit mesa-common-dev zstd liblz4-tool file \
locales libacl1 make
Docker 公式イメージ ubuntu:24.04 で実際に実行したところ、エラーゼロで完了しました。Ubuntu 22.04 でも同じコマンドで問題なく完了することを確認しています。
①インストール後のバージョン確認
インストール後、主要ツールのバージョンを確認します。Yocto の公式最低要件を満たしているかチェックできます。
git version 2.43.0
Python 3.12.3
gcc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0
GNU Make 4.3
以下は Ubuntu 22.04 と 24.04 のバージョン比較です。どちらも Yocto の最低要件を満たしています。
手順2 — poky リポジトリをクローンする
Yocto のリファレンス実装 poky を取得します。今回は最新の長期サポートリリースである Scarthgap（5.0 系列）を使います。
Cloning into ‘poky’…
remote: Counting objects: …
Receiving objects: 100% (xxxxxx/xxxxxx), done.
$ ls poky/
LICENSE README.md bitbake contrib documentation
meta meta-poky meta-selftest meta-skeleton meta-yocto-bsp
oe-init-build-env scripts
クローン完了後のディレクトリ構造はこのようになります。meta/ がコアレイヤー、bitbake/ がビルドエンジン本体です。時間を節約したいときは --depth 1 を付けて shallow clone できます（実際に depth 1 でのクローンを確認済み）。
安定版ブランチを指定すること
--branch を省略すると master（開発版）が取得されます。本番利用や学習には Scarthgap（--branch scarthgap）など名前付きリリースブランチを指定してください。
手順3 — ビルド環境を初期化する
oe-init-build-env は BitBake を使える状態にシェル環境を設定するスクリプトです。source で呼び出すことが必須です（直接実行するとエラーになります）。
You had no conf/local.conf file. This configuration file has therefore been
created for you from meta-poky/conf/templates/default/local.conf.sample
You had no conf/bblayers.conf file. This configuration file has therefore been
created for you from meta-poky/conf/templates/default/bblayers.conf.sample
### Shell environment set up for builds. ###
Common targets are:
core-image-minimal
core-image-full-cmdline
core-image-sato
You can now run ‘bitbake <target>’
$ ls conf/ && bitbake –version
bblayers.conf local.conf templateconf.cfg
BitBake Build Tool Core version 2.8.1
実際に実行したところ、conf/local.conf と conf/bblayers.conf が自動生成され、BitBake Build Tool Core version 2.8.1 が起動しました。引数 ../build はビルドディレクトリのパスです。省略するとカレントディレクトリに build/ が作られます。
手順4 — local.conf でビルドターゲットを設定する
conf/local.conf の中で特に最初に確認したいのは MACHINE の設定です。デフォルトはコメントアウトされた状態で qemux86-64（QEMU 仮想マシン向け x86_64）が使われます。
#MACHINE ?= “qemuarm”
#MACHINE ?= “qemuarm64”
#MACHINE ?= “qemumips”
#MACHINE ?= “qemumips64”
#MACHINE ?= “qemuppc”
#MACHINE ?= “qemux86”
#MACHINE ?= “qemux86-64”
MACHINE ??= “qemux86-64”
実際の組み込みターゲット（Raspberry Pi や特定の SoC）を使う場合は、対応する BSP レイヤーを追加してから MACHINE を書き換えます。QEMU で動作を試すだけなら変更不要です。
②ビルドスレッド数の最適化
Yocto は make -j$(nproc) と同様にマルチスレッドビルドに対応しています。local.conf に以下を追記すると、CPU コア数に合わせて並列ジョブ数を設定できます。
$ echo “PARALLEL_MAKE = \”-j$(nproc)\”” >> conf/local.conf
$ grep “BB_NUMBER_THREADS\|PARALLEL_MAKE” conf/local.conf
BB_NUMBER_THREADS = “8”
PARALLEL_MAKE = “-j8”
CPU コア数が多いほどビルドが速くなりますが、RAM の消費も増えます。コア数×1.5GB 程度を目安にしてください（公式ドキュメントの推奨値）。本記事の検証環境では sysbench 4スレッドで平均 27,452 events/sec を記録しており、物理コアが 8 本あれば実用的なビルド速度を得られます。
ビルドを実行する（bitbake）
環境が整ったら以下のコマンドでビルドを開始します。core-image-minimal はカーネルと最小限のユーザーランドだけを含む最軽量のターゲットです。
Loading cache: 100% |##########| Time: 0:00:01
Loaded 1827 entries from dependency cache.
Parsing recipes: 100% |##########| Time: 0:02:34
NOTE: Resolving any missing task queue dependencies
NOTE: Executing RunQueue Tasks
NOTE: Tasks Summary: Attempted 4289 tasks of which …
フルビルドは数時間かかります
bitbake core-image-minimal は初回実行時にすべてのパッケージをソースからビルドするため、8 コアのマシンでも 2〜6 時間かかります（ネットワーク速度とストレージ性能にも依存）。2 回目以降はキャッシュが効くため大幅に短縮されます。上のターミナル出力は Yocto ドキュメントを参考にした実行例で、本記事ではフルビルドは未実施です。
ビルド完了後は tmp/deploy/images/qemux86-64/ に .wic または .rootfs.ext4 ファイルが生成されます。QEMU で起動するには以下のコマンドです。
runqemu – INFO – Running MACHINE=qemux86-64 bitbake task
Poky (Yocto Project Reference Distro) 5.0.7 qemux86-64 /dev/ttyS0
qemux86-64 login:
ログインプロンプトが出れば成功です（デフォルトユーザー: root、パスワードなし）。
よくあるエラーと解決策
①locale: en_US.UTF-8 が設定されていない
bitbake 実行時に Please make sure locale 'en_US.UTF-8' is available と表示された場合は、ロケールを生成します。
$ sudo update-locale LANG=en_US.UTF-8
$ source /etc/default/locale
Docker コンテナ内では locales パッケージのインストールと locale-gen を追加で実行する必要があります。
②oe-init-build-env を source せずに実行してしまう
bash oe-init-build-env ではなく source oe-init-build-env が正しいです。直接実行すると「This script needs to be sourced」というエラーになります。実際に検証中に踏みました。
③ディスク容量不足で途中停止
ビルド途中でディスクが埋まると BitBake が異常終了します。df -h で確認し、/tmp や不要な Docker イメージを削除してから再実行してください。ダウンロード済みのソースは DL_DIR（デフォルト build/downloads/）に残るので、再実行時に再ダウンロードは不要です。
④python3-git が入っていない
一部のレシピが git-python バインディングを使います。インストールリストに python3-git が含まれていないと ModuleNotFoundError: No module named 'git' が出ます。手順1 のコマンドをそのままコピーすれば含まれます。
まとめ
今回実測した範囲をまとめます。
- Ubuntu 22.04 / 24.04 の両方で Yocto 公式推奨パッケージが問題なくインストールできた（returncode 0）
- poky Scarthgap を shallow clone し、BitBake 2.8.1 が起動することを確認した
source oe-init-build-envでconf/local.confとconf/bblayers.confが自動生成される- フルビルド（
bitbake core-image-minimal）は本記事では未実施。公式ドキュメントに基づき 90GB 以上のストレージと 2〜6 時間のビルド時間を見込むこと
Yocto はセットアップさえ済めば、あとは local.conf を書き換えるだけで様々な組み込みターゲット向けのカスタム Linux を作れます。まず QEMU ターゲットでビルドを完走させ、その後 Raspberry Pi BSP レイヤーを追加するという進め方が無難です。
本格的な開発環境を VPS で整えたい場合は、コア数と RAM が多いプランを選ぶとビルド時間を大幅に短縮できます。
Docker の基本操作に不安がある方はこちらも参考にしてください。Ubuntu に Docker をインストールする手順
コメント