Raspberry Pi 3向けYocto開発環境をWSL2上に構築する
はじめに
個人開発用にRaspberry Pi 3向けのYocto開発環境を構築したので、その手順をまとめます。
本記事では以下の構成について記載します。
メモリ高騰により現時点最新のRaspberry Pi 5が高騰していたため、手持ちのRaspberry Pi 3を使用しました。
構築した開発環境はkernelモジュールやアプリケーション開発等に利用予定です。
- OS：Ubuntu 24.04 LTS（WSL2）（scarthgapがサポートしているUbuntuの最新バージョン）
- Yocto：scarthgap（5.0系LTSブランチ）最新版でない理由は後述
- ターゲット：Raspberry Pi 3
また、Windows環境特有のWSL2セットアップ時のエラーなど、躓きやすいポイントも合わせて記載しています。
1. WSLセットアップ
PowerShellを管理者権限で起動し、インストール可能なディストリビューション一覧を確認します。
wsl --list --online
NAME FRIENDLY NAME
Ubuntu Ubuntu
Ubuntu-24.04 Ubuntu 24.04 LTS
Ubuntu-22.04 Ubuntu 22.04 LTS
Ubuntu-20.04 Ubuntu 20.04 LTS
今回はUbuntu 24.04をインストールします。
wsl --install -d Ubuntu-24.04
インストール後、再起動を求められるので再起動してください。
トラブルシューティング：BIOSエラーが発生した場合
スタートメニューからUbuntuを起動した際に下記エラーが出ることがあります。
Installing, this may take a few minutes...
WslRegisterDistribution failed with error: 0x80370102
Please enable the Virtual Machine Platform Windows feature and ensure virtualization is enabled in the BIOS.
For information please visit https://aka.ms/enablevirtualization
Press any key to continue...
対処1：Virtual Machine PlatformをWindowsで有効化
PowerShellで以下を実行します。
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
対処2：BIOS設定で仮想化を有効化
ASUSマザーボードの場合の手順は以下のとおりです。
- PC起動時に
Deleteキーを押してBIOSメニューを開く -
F7キーでAdvanced Modeに切り替える - 「詳細」タブ →「CPU設定」を開く
- Intel Virtualization Technology を「有効」に変更
-
F10で保存して再起動
2. Ubuntu初期セットアップ
WSLを起動すると初回はユーザー名とパスワードの設定を求められます。指示に従って設定してください。
設定後、パッケージを最新化します。
sudo apt update && sudo apt upgrade -y
3. Yocto基本セットアップ
必要パッケージのインストール
Yocto公式ドキュメント（scarthgap版 System Requirements）を参照し、必要なパッケージをインストールします。
なお、このページの「Supported Linux Distributions」セクションにてUbuntu 24.04 LTSがサポート対象であることも確認できます。
（ページ上部のセレクタからYoctoバージョンを切り替えると、対応する必須パッケージも変わります）
sudo apt-get install build-essential chrpath cpio debianutils diffstat file gawk gcc git \
iputils-ping libacl1 locales python3 python3-git python3-jinja2 python3-pexpect \
python3-pip python3-subunit socat texinfo unzip wget xz-utils zstd
ロケール設定
en_US.UTF-8 ロケールが有効になっているか確認します。
locale --all-locales | grep en_US.utf8
何も表示されない場合は有効になっていないため、以下で設定します。
sudo dpkg-reconfigure locales
設定画面が表示されるので、↓キーで en_US.UTF-8 を探し、スペースキーで選択（[*]）します。
タブキーでOKに移動してEnterを押し、次の画面でも en_US.UTF-8 を選択してOKを押します。
設定後、再度確認して en_US.utf8 が表示されればOKです。
$ locale --all-locales | grep en_US.utf8
en_US.utf8
4. Yocto開発環境セットアップ
以下の手順は、任意のワークスペースディレクトリに移動してから実施してください。
①pokyのクローン
pokyはYoctoでビルドするための基盤（メタデータ・ツール群）です。
今回はYocto 5.0系の scarthgap ブランチを使用します。
scarthgapを選択する理由は主に以下の2点です。
- meta-raspberrypiがscarthgapブランチを持ち、対応している
- Yocto 5.3（whinlatter）以降はpokyリポジトリのリリースブランチが廃止され、
git clone -b <branch>による従来のセットアップ手順が使えなくなっている。scarthgapは従来手順が使える最新のブランチ
whinlatterにて作成できない、という意味ではないのですが、当記事ではscarthgapにて構築したいと思います。
git clone -b scarthgap https://git.yoctoproject.org/poky
②meta-raspberrypiのクローン
Raspberry Pi向けのBSPレイヤーをpoky配下に追加します。
cd poky
git clone -b scarthgap https://github.com/agherzan/meta-raspberrypi
（参考）対応するMACHINE名の確認
ls meta-raspberrypi/conf/machine/
raspberrypi.conf
...
raspberrypi3-64.conf
raspberrypi4.conf
raspberrypi4-64.conf
-64 なしのMACHINE名は32bitビルドです。今回は raspberrypi3-64（64bit）を使用します。
③ビルド環境の初期化
source oe-init-build-env build
このコマンドで以下が行われます。
- 環境変数のセットアップ
-
buildディレクトリの生成 -
conf/local.confおよびconf/bblayers.confのひな形生成
実行後は自動的に build ディレクトリに移動します。
複数ターゲット向けのビルドを分けて管理したい場合は、末尾の
buildを任意の名前に変更するとビルドディレクトリを分けられます。
次に conf/local.conf のターゲットマシン設定を変更します。
sed -i 's/MACHINE ??= "qemux86-64"/MACHINE ??= "raspberrypi3-64"/' conf/local.conf
確認します。
$ grep "^MACHINE" conf/local.conf
MACHINE ??= "raspberrypi3-64"
④meta-raspberrypiレイヤーの追加
Yoctoはイラストソフトのレイヤー構造のように、レシピやパッチを重ねてビルドを構成します。
以下のコマンドでmeta-raspberrypiを追加します。
bitbake-layers add-layer ../meta-raspberrypi
追加されたレイヤーは以下で確認できます。
$ bitbake-layers show-layers
NOTE: Starting bitbake server...
layer path priority
====================================================
core .../poky/meta 5
yocto .../poky/meta-poky 5
yoctobsp .../poky/meta-yocto-bsp 5
raspberrypi .../poky/meta-raspberrypi 9
⑤ビルド実行
最小構成イメージをビルドします。初回は数時間かかります。気長にお待ちください。
bitbake core-image-minimal
以下のようなメッセージが表示され実行完了すれば、ビルド成功しています。
NOTE: Tasks Summary: Attempted 3716 tasks of which 3716 didn't need to be rerun and all succeeded.
生成されたバイナリは下記に格納されます。
build/tmp/deploy/images/raspberrypi3-64/
⑥SDカードへの書き込み
今回はWSL2からddコマンドを使ってSDカードに直接書き込みます。
そのためにWSL2にSDカードを認識させる必要があり、usbipd-winを使用します。
usbipd-winのインストール（Windows側）
最新の .msi ファイルをダウンロードしてインストールしてください。
SDカードをWSL2に接続
PowerShell（管理者）でSDカードリーダーのBUSIDを確認します。
usbipd list
BUSID VID:PID DEVICE STATE
1-14 2537:1081 USB 大容量記憶装置 Not shared
BUSIDを指定してWSL2に接続します。
usbipd bind --busid 1-14
usbipd attach --wsl --busid 1-14
BUSIDはSDカードの抜き差しで変わることがあるため、毎回
usbipd listで確認してください。
WSL2側でデバイスを確認
lsblk
sdf のようなデバイスが増えていればSDカードが認識されています。
（デバイス名は環境によって異なります）
イメージを展開してコピー
wic.bz2 は圧縮ファイルのため、先に /tmp に実体ファイルをコピーしてから展開します。
シンボリックリンクのままだと展開に失敗するため注意してください。
cp build/tmp/deploy/images/raspberrypi3-64/core-image-minimal-raspberrypi3-64.rootfs-<タイムスタンプ>.wic.bz2 /tmp/
cd /tmp/
bzip2 -dk core-image-minimal-raspberrypi3-64.rootfs-<タイムスタンプ>.wic.bz2
ddで書き込み
sudo dd if=/tmp/core-image-minimal-raspberrypi3-64.rootfs-<タイムスタンプ>.wic of=/dev/sdf bs=4M status=progress && sync
of=/dev/sdfのデバイス名はlsblkで確認したSDカードのデバイス名に合わせてください。誤ったデバイスを指定するとデータが消えます。
WSL2からSDカードを切り離す
WSL2のターミナルで：
sync
PowerShell（管理者）で：
usbipd detach --busid 1-14
Raspberry PiにSDカードをセットし電源投入すると、コンソールが起動します。
ユーザ名:root
パスワード:空白(入力なし)
にてログインできます。
当該環境ではSSHがあると開発に役立ちますが、
この環境にSSHは入っていないため、別途ビルド環境にて追加します。
(本記事では起動までで以降は省略します)
5. （参考）VSCode + WSL連携
WSLで起動したUbuntuはCUI環境ですが、以下の手順でWindows側のVSCodeから編集できます。
導入した拡張機能
- WSL
- Remote Explorer
- Yocto Project Bitbake（任意：
.bbファイルのシンタックスハイライト）
接続方法
- VSCode左下の「><」ボタンをクリック
- 「Connect to WSL」を選択
- 接続後、「Open Folder」からUbuntu側のパスでフォルダを指定（pokyフォルダなど）
以降はWindows側でコード編集 → Ubuntu側でビルドという作業が可能になります。
6. （参考）WSLのメモリ不足対策
bitbakeのビルド中にメモリ不足が発生する場合は、WSLのリソース制限を設定します。
PowerShellで以下を実行して設定ファイルを開きます。
notepad $env:USERPROFILE\.wslconfig
以下の内容を記載して保存します。値はホストPCのRAMと物理コア数の半分程度を目安にしてください。
[wsl2]
memory=8GB
processors=4
swap=8GB
設定反映にはWSLの再起動が必要です。
wsl --shutdown
まとめ
WSL2 + Ubuntu 24.04 + YoctoのscarthgapブランチでRaspberry Pi 3向けのビルド環境が構築できました。
whinlatter以降のブランチでの構築も今後別記事にて試行したいと思います。