Yoctoレイヤーの作成と管理ガイド

Yoctoのレイヤーって結局何？ meta-xxxというディレクトリがたくさんあって意味がわからない——。

Yoctoレイヤーとは、関連するレシピ・設定・パッチをまとめた再利用可能なモジュールだ。 レイヤーを積み重ねることで、アップストリームのPokyソースを一切触らずにカスタムLinuxイメージを構築できる。この記事ではレイヤーモデルの仕組みを解説し、カスタムレイヤーの作成から外部BSPレイヤーの追加、よくあるエラーのデバッグまでを実践的に紹介する。

Yoctoレイヤーとは

レイヤー（Layer） とは、関連するレシピ・設定・パッチをまとめた「モジュール」だ。

Yoctoのビルドシステムは、複数のレイヤーを 積み重ねる（Stack） ことで動作する。これにより、ベースを壊さずにカスタマイズできる。

上のレイヤーは下のレイヤーを「上書き」できる。同じレシピが複数のレイヤーに存在する場合、優先度が高いレイヤーのレシピが使われる。

なぜレイヤーが必要なのか

• 再利用性 ：同じレイヤーを複数プロジェクトで使い回せる
• 保守性 ：アップストリームとの分離。Pokyをアップデートしても自分の変更が消えない
• コラボレーション ：チームで分担しやすい。BSP担当・アプリ担当など
• バージョン管理 ：レイヤーごとにGitリポジトリを分けられる

レイヤーの種類と構造

レイヤーの種類

プロジェクトでは必ず カスタムレイヤー を作成して、自分のレシピや設定をそこに置こう。

ディレクトリ構造

すべてのレイヤーは同じ基本構造を持っている。

meta-mylayer/
├── conf/
│   └── layer.conf          # レイヤーの設定ファイル（必須）
├── COPYING.MIT             # ライセンスファイル
├── README                  # レイヤーの説明
├── recipes-bsp/            # BSP関連レシピ
├── recipes-core/           # コア機能のレシピ
├── recipes-example/        # サンプルレシピ
│   └── myapp/
│       ├── myapp_1.0.bb
│       └── files/
├── recipes-kernel/         # カーネル関連
├── recipes-graphics/       # グラフィック関連
└── classes/                # 共通クラス（.bbclass）

recipes-* というディレクトリ名は慣習で、BitBakeが自動的に中のレシピを検索する。

layer.confの中身

conf/layer.conf はレイヤーの「身分証明書」だ。このファイルがあって初めてYoctoがそのディレクトリをレイヤーとして認識する。

# conf/layer.conf

# レイヤーのパスをBBPATHに追加
BBPATH .= ":${LAYERDIR}"

# レシピを検索するパス
BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
            ${LAYERDIR}/recipes-*/*/*.bbappend"

# このレイヤーのコレクション名（一意である必要がある）
BBFILE_COLLECTIONS += "meta-mylayer"
BBFILE_PATTERN_meta-mylayer = "^${LAYERDIR}/"

# レイヤーの優先度（高いほど優先される。6〜10が一般的）
BBFILE_PRIORITY_meta-mylayer = "6"

# レイヤーの互換性（対応するYoctoバージョン）
LAYERSERIES_COMPAT_meta-mylayer = "scarthgap"

# 依存レイヤー
LAYERDEPENDS_meta-mylayer = "core"

カスタムレイヤーを作成する

bitbake-layersコマンドを使う（推奨）

bitbake-layers コマンドを使うのが一番簡単で確実だ。

# ビルド環境に入る
cd ~/yocto/poky
source oe-init-build-env build

# Pokyの親ディレクトリに移動してレイヤーを作成
cd ..
bitbake-layers create-layer meta-myproject

# 作成されたファイルを確認
ls meta-myproject/
conf  COPYING.MIT  README  recipes-example

cat meta-myproject/conf/layer.conf

手動で作成する

layer.confの内容を理解したい場合は手動で作ると勉強になる。

# ディレクトリ構造を作成
mkdir -p meta-myproject/conf
mkdir -p meta-myproject/recipes-example/myapp

# layer.confを作成
cat > meta-myproject/conf/layer.conf << 'EOF'
BBPATH .= ":${LAYERDIR}"
BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
            ${LAYERDIR}/recipes-*/*/*.bbappend"
BBFILE_COLLECTIONS += "meta-myproject"
BBFILE_PATTERN_meta-myproject = "^${LAYERDIR}/"
BBFILE_PRIORITY_meta-myproject = "6"
LAYERSERIES_COMPAT_meta-myproject = "scarthgap"
EOF

レイヤーをビルドに追加する

bblayers.confの編集

# コマンドで追加（推奨）
cd ~/yocto/poky
source oe-init-build-env build
bitbake-layers add-layer ../meta-myproject

# 直接編集する場合
nano conf/bblayers.conf

conf/bblayers.conf の例：

BBLAYERS ?= " \
  /home/user/yocto/poky/meta \
  /home/user/yocto/poky/meta-poky \
  /home/user/yocto/poky/meta-yocto-bsp \
  /home/user/yocto/meta-myproject \
  "

絶対パスで記述するのが一般的だ。bitbake-layers add-layer も絶対パスを挿入する。

レイヤーの確認と削除

# 現在のレイヤー一覧を確認
bitbake-layers show-layers

layer                 path                                      priority
==========================================================================
meta                  /home/user/yocto/poky/meta                 5
meta-poky             /home/user/yocto/poky/meta-poky            5
meta-yocto-bsp        /home/user/yocto/poky/meta-yocto-bsp       5
meta-myproject        /home/user/yocto/meta-myproject            6

# レイヤーをビルドから削除（ファイル自体は削除しない）
bitbake-layers remove-layer meta-myproject

既存レシピのカスタマイズ

既存のレシピを変更したい場合、元のファイルを編集せずに .bbappend を使う。bbappendはYoctoの「非破壊カスタマイズ」の核心だ。詳しい使い方はbbappend実践ガイドを参照してほしい。

外部BSPレイヤーを追加する

Raspberry Pi用のBSPレイヤー「meta-raspberrypi」を追加する例だ。

レイヤーをダウンロード

# Pokyと同じディレクトリにクローン
cd ~/yocto
git clone -b scarthgap git://git.yoctoproject.org/meta-raspberrypi

# meta-openembeddedも必要（meta-raspberrypiが依存）
git clone -b scarthgap git://git.openembedded.org/meta-openembedded

レイヤーを追加して設定

cd ~/yocto/poky
source oe-init-build-env build

# meta-oe（meta-openembeddedの基本レイヤー）を追加
bitbake-layers add-layer ../meta-openembedded/meta-oe

# meta-raspberrypiを追加
bitbake-layers add-layer ../meta-raspberrypi

# 追加されたか確認
bitbake-layers show-layers

conf/local.conf でターゲットマシンを設定：

MACHINE = "raspberrypi4-64"

Raspberry Piでのビルド手順の全体像はRPiビルドガイドを参照してほしい。

OpenEmbedded Layer Index

公開されているレイヤーは OpenEmbedded Layer Index で検索できる。

ここで「raspberrypi」「qt5」「nodejs」など検索すると、対応レイヤーが見つかる。Yoctoのリリースブランチ（Scarthgap、Kirkstone等）でフィルタリングできるので、互換性のあるレイヤーだけを探せる。何か追加したいパッケージがあれば、まずここを確認してみよう。

よく使われるレイヤー

よくあるエラーと解決方法

Layer 'xxx' is not compatible

ERROR: Layer xxx is not compatible with the current version

原因： LAYERSERIES_COMPAT が現在のYoctoバージョンと一致しない。

解決： layer.conf の LAYERSERIES_COMPAT を現在のYoctoブランチ名に更新する。

LAYERSERIES_COMPAT_meta-mylayer = "scarthgap"

Layer depends on 'xxx'

ERROR: Layer xxx depends on layer xxx

原因： 依存レイヤーが追加されていない。

解決： 依存レイヤーを先に bitbake-layers add-layer で追加する。

bbappendに対応するレシピがない

WARNING: No bb files in default matched BBFILE_PATTERN

原因： .bbappend ファイルがあるのに、対応する .bb レシピがどのレイヤーにも存在しない。Yoctoのバージョンアップ後にレシピ名が変わった場合に起きやすい。

解決： 新しいリリースで正しいレシピ名を確認する。レシピが意図的に削除されたなら、孤立した .bbappend も削除する。マイグレーション中に一時的に警告に留めたい場合は local.conf に BB_DANGLINGAPPENDS_WARNONLY = "1" を設定する。

優先度の競合をデバッグする

同じレシピが複数レイヤーに存在する場合、BBFILE_PRIORITY が最も高いレイヤーのレシピが使われる。意図しないオーバーライドが起きていないか確認する方法がある。

# オーバーレイされているレシピを一覧表示
bitbake-layers show-overlayed

# 特定レシピがどのレイヤーから来ているか確認
bitbake-layers show-recipes "busybox"

「自分のレシピが無視されている」という場面で show-overlayed は最強のデバッグツールだ。カスタムレイヤーのレシピが反映されない場合、より高い優先度のレイヤーが上書きしていないか確認しよう。

FAQ

レイヤーとレシピの違いは？

レシピ（.bb ファイル）は1つのパッケージのビルド手順だ——ソースの取得先、コンパイル方法、インストール先を定義する。レイヤー は複数の関連レシピ・設定・パッチをまとめたディレクトリで、再利用可能なモジュールとして機能する。レシピが個別の指示書、レイヤーがそれを整理するフォルダだと考えるとわかりやすい。

カスタムレイヤーは1つにまとめていい？

技術的にはOKだが、プロジェクトが大きくなると分けたほうがいい。BSPカスタマイズ用、アプリケーション用、ディストロ設定用と分離するのが一般的だ。プロトタイピングや小規模プロジェクトなら meta-myproject 1つで十分。

BBFILE_PRIORITYは何番にすべき？

bitbake-layers create-layer のデフォルトは6だ。カスタムレイヤーは6〜10が一般的。重要なのは、オーバーライドしたいレイヤーより高い数値にすること。Pokyの基本レイヤー（meta, meta-poky）は優先度5なので、6以上にすれば自分のカスタマイズが優先される。

別のレイヤーのレシピを上書きするには？

自分のレイヤーに .bbappendファイル を作成する。.bbappend は元のレシピの特定部分だけを変更・拡張できる。元のファイルを直接編集する必要はない。自分のレイヤーの優先度が元のレイヤー以上であること。

LAYERSERIES_COMPATは必須？

必須だ。Yocto 2.4（Rocko）以降、BBFILE_COLLECTIONS が設定されているレイヤー（＝すべてのレイヤー）では LAYERSERIES_COMPAT が必要になった。設定しないとBitBakeが互換性エラーを出す。ターゲットのリリースブランチ名（例: scarthgap）を設定しよう。

特定パッケージやボードのレイヤーを探すには？

OpenEmbedded Layer Index で検索するのが一番早い。レイヤー名、レシピ名、マシン名で検索でき、Yoctoリリースでフィルタリングできる。コミュニティメンテナンスのレイヤーが網羅的にリストされている。

異なるYoctoリリースのレイヤーを混ぜて使える？

基本的にはNGだ。異なるリリースのレイヤーを混在させると（例: KirkstoneのレイヤーをScarthgapビルドで使う）、デバッグ困難なエラーが頻発する。必ずYoctoリリースブランチに合ったレイヤーを使おう。レイヤーが更新されていない場合は、互換フォークを探すかマイグレーションガイドを確認する。

まとめ

• 自作レシピは必ずカスタムレイヤーに置く （Pokyを直接編集しない）
• 既存レシピの変更は .bbappend を使う
• レイヤー名は「meta-」で始める （慣習）
• LAYERSERIES_COMPAT を適切に設定する
• レイヤーごとにGitリポジトリを分ける （チーム開発時）

レイヤーの基礎を押さえたら、次のステップに進もう。

• レシピの書き方 — 自作アプリをイメージに追加する
• bbappend実践ガイド — 既存レシピのカスタマイズパターン
• Raspberry PiでカスタムLinuxをビルドする — 実機で動かす

組み込みLinuxの世界をもっと深く学びたい人には、以下の書籍がおすすめだ。

関連記事:

• Yoctoレシピの書き方完全ガイド
• Yocto bbappendの書き方と実践パターン5選
• Yocto Getting Started完全ガイド
• Yoctoビルド速度最適化完全ガイド
• Raspberry PiでカスタムLinuxをビルドする
• KirkstoneからScarthgapへの移行ガイド