Yocto：レイヤーの追加方法

# 1. はじめに #

本ページでは、Yoctoのビルド環境にレイヤーを追加する方法について紹介します。
Yoctoは、様々なレイヤー(meta, meta-poky, meta-yocto-bsp, etc...)を組み合わせて構成されています。レイヤー毎にレシピ(\*.bbや*.bbappend)が格納されており、ビルド環境にレイヤーを追加することで、そのレイヤーに含まれるレシピを使うことができるようになります。
多くのレイヤーは、githubなどで公開されています。自身のビルド環境に、使いたいパッケージが含まれていないときは、必要なレイヤーを取得&ビルド環境に追加することで、追加したレイヤーに含まれるパッケージも使えるようになります。また、一般的に、Yocto環境に変更を加える場合、github等で取得したレシピには直接変更を加えず、カスタマイズ用のレイヤーを追加し、そこに変更用のレシピを作成していきます。
この記事は、上記のようなシチュエーションを想定した、レイヤーの追加、作成方法について紹介します。
なお、公式のYoctoマニュアルにおけるレイヤー作成についての説明は、以下から参照することができます。
https://docs.yoctoproject.org/dev/dev-manual/layers.html

# 2. 既存のビルド環境確認 #

レイヤー構成に変更を加える前に、まずビルド環境のレイヤー構成がどうなっているか確認してみましょう。
以降は、pokyのzeus-nextブランチのソース環境にて確認しながら説明を行います。独自のビルド環境をお持ちの方は、適宜読み替えお願いします。

まず、ビルド用環境変数設定コマンド(pokyだと"source oe-init-build-env")を実行して、ビルドディレクトリに移動してください。この状態で以下コマンドを実行すると、ビルド環境に登録されているレイヤー一覧を確認することができます。
~~~
$ bitbake-layers show-layers
NOTE: Starting bitbake server...
layer                 path                        priority
==============================================================
meta                  /yocto_research/poky/meta  5
meta-poky             /yocto_research/poky/meta-poky  5
meta-yocto-bsp        /yocto_research/poky/meta-yocto-bsp  5
~~~
上記より、現在、meta、meta-poky、meta-yocto-bspの3つのレイヤーによって、ビルド環境が構成されていることが確認できます。bitbake実行時も、上記3レイヤーに含まれるレシピが使用される状態になっています。

# 3. レイヤーの作成方法 #
本章では、新規にレイヤーを作成する方法や、作成したレイヤーの設定値について紹介していきます。
既存のレイヤーをビルド環境に追加したいと考えている方は、本章は読み飛ばしても構いません。

ビルド用環境変数設定コマンド実行後に、以下のコマンドを実行することで、新規レイヤーを作成することができます。
~~~
(相対パスで記述) $ bitbake-layers create-layer ../meta-customize
(絶対パスで記述) $ bitbake-layers create-layer /yocto_research/poky/meta-customize
~~~
上記の例では、meta-customizeという名前のレイヤーを作成していますが、任意の名前のレイヤーを作成することが可能です。

また、作成したレイヤーには、以下のファイルが含まれます。
~~~
$ tree meta-customize/
meta-customize/
├── COPYING.MIT
├── README
├── conf
│   └── layer.conf
└── recipes-example
    └── example
        └── example_0.1.bb
~~~
各ファイルについて簡単に説明します。
| ファイル | 概要 |
| ---- | ---- |
| COPYING.MIT | レイヤーのライセンスファイル<br> 変更不要 <br> ※Yoctoマニュアルにて、レイヤー作成用スクリプトは、ほとんどのレイヤーで一般的なMITライセンスを想定して作成していると説明あり|
| README | このレイヤーのREADME<br> 変更しなくてもビルドには影響ないが、自身の運用方針等に合わせて記載内容を更新するべき|
| layer.conf | このレイヤーのコンフィグファイル<br> 記載内容の詳細については後述 |
| example_0.1.bb | サンプルレシピのため、不要なファイル<br> ディレクトリごと削除するか、カスタマイズするレシピ向けに変更する必要あり |

### layer.confの設定値について ###
layer.confは、このレイヤー全体に影響する設定ファイルのため、各設定値の意味を理解して設定値を決定する必要があります。多くの場合、自動作成されたファイルのままでも動作しますが、最低限、layer.confでどのような設定を行っているのか理解しておきましょう。以下の表で、layer.confで設定している各設定値の意味について説明します。


| 変数名 | 初期値 | 設定内容および変更要否 |
| ---- | ---- | ---- |
| BBPATH | ":${LAYERDIR}"| bitbake実行時に参照するパスを示す<br> 初期値から変更不要 |
| BBFILES | "\${LAYERDIR}/recipes-\*/\*/\*.bb \ <br> \\${LAYERDIR}/recipes-\*/\*/\*.bbappend"| bitbake実行時に参照するファイルを示す<br> 基本的に初期値から変更不要<br> "${LAYERDIR}/recipes-\*/\*/\*.bb"を削除することで、このレイヤーに含まれる*.bbを参照させないようにすることも可能|
| BBFILE_COLLECTIONS | "meta-customize"| レイヤー名<br> 他のレイヤーと重複しない名前である必要がある<br> 初期値から変更不要 |
| BBFILE_PATTERN_meta-customize | "^${LAYERDIR}/"| 特定のレイヤー内のBBFILESのファイルと一致するように展開される変数<br> 初期値から変更不要 |
| BBFILE_PRIORITY_meta-customize | "6"| レイヤーの優先度<br>他のレイヤーのレシピと競合した際の動作に影響する<br>また、\*.bbと\*.bbappendで影響が若干異なる<br> \*.bb：同じパッケージ名の\*.bbが、複数ビルド環境に含まれる場合、最も高い優先度のレイヤーに含まれるものが使用される<br> \*.bbappend：全ての\*.bbappendが参照され、\*.bbappend間で重複する変数や関数の記述については、優先度が高いレイヤーの記述が優先される<br> 一般的に、カスタマイズ用にレイヤーを追加する場合、既存のレイヤーより高い優先度を設定する |
| LAYERDEPENDS_meta-customize | "core"| このレイヤーが依存しているレイヤー情報<br> 例えば、pythonを使うためにmeta-pythonが必要な場合、"core meta-python"となる<br>特定の版数のレイヤーが必要な場合、LAYERVERSIONを明示的に指定することも可能<br> 指定されたレイヤーがビルド環境に含まれていなかった場合、ビルドエラーする |
| LAYERSERIES_COMPAT_meta-customize | "warrior zeus" | 互換性のあるOpenEmbedded-Coreのバージョン<br> create-layerコマンドでレイヤーを作ったのであれば、ビルド環境に合わせた初期値となるため、変更不要<br> 別のビルド環境に組み込む場合、互換性の確認が必要 |
| LAYERVERSION(任意) | 記載なし| このレイヤーのバージョンを指定する<br> LAYERDEPENDSで明示的に版数を指定するときに利用されるパラメータ<br>任意パラメータのため、特定の目的が無ければ記載不要 |

# 4. ビルド環境へのレイヤー登録 #
以下のコマンドで、ビルド環境にレイヤーを追加できます。
~~~
(相対パスで記述) $ bitbake-layers add-layer ../meta-customize
(絶対パスで記述) $ bitbake-layers add-layer /yocto_research/poky/meta-customize
~~~
レイヤー追加後にshow-layersコマンドを実行することで、レイヤーが追加できていることを確認できます。
~~~
$ bitbake-layers show-layers
NOTE: Starting bitbake server...
layer                 path                        priority
==============================================================
meta                  /yocto_research/poky/meta  5
meta-poky             /yocto_research/poky/meta-poky  5
meta-yocto-bsp        /yocto_research/poky/meta-yocto-bsp  5
meta-customize        /yocto_research/poky/meta-customize  6
~~~

上記のレイヤー追加処理は、ビルドディレクトリ内のファイル(build/conf/bblayers.conf)に対して変更が適用されるだけなので、新しくビルドディレクトリを作り直した場合は、変更が引き継がれません。
恒久的な追加をしたい場合、ビルド環境削除後に、"poky/meta-poky/conf/bblayers.conf.sample"に記述を追加します。そうすることで、以降はビルド用環境変数設定コマンドを実行した時点で、meta-customizeがレイヤー一覧に追加されています。

~~~diff_c
$ cat meta-poky/conf/bblayers.conf.sample
# POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf
# changes incompatibly
POKY_BBLAYERS_CONF_VERSION = "2"

BBPATH = "${TOPDIR}"
BBFILES ?= ""

BBLAYERS ?= " \
  ##OEROOT##/meta \
  ##OEROOT##/meta-poky \
  ##OEROOT##/meta-yocto-bsp \
+  ##OEROOT##/meta-customize \
  "
~~~

# 5. まとめ #
この記事を書くに当たり、普段、あまり深く気にせずに使っていたレイヤー設定について改めて調べました。調べてみると、今まで知らなかった、知っていると役立つ話がいくつもありました。
そんな気づきを含めて記事にまとめたので、ぜひ参考にしてみてください。