AtomVM: AtomGL を使うためのイメージをビルドする（2025年12月）

はじめに

AtomVM でディスプレイ描画をしたかったので、AtomVM 側が提供している AtomGL（ESP32 コンポーネント）を使うことにしました。ところが現時点では AtomGL を含んだ AtomVM の事前ビルド済みイメージが見当たらず、自分でソースからビルドしてカスタムイメージを作る必要がありました。

以前、AtomVM をソースコードからビルドする手順をまとめましたが、今回は用途にあわせた独自イメージ作成の一例として、AtomGL コンポーネントを追加してビルドする方法を備忘録としてまとめます。

対象環境

今回試したときの環境は次のとおりです。

• マイコン
  • Seeed Studio XIAO ESP32-S3
• ホスト PC
  • Debian 系 Linux（LMDE7）
• 主なソフトウェア
  • Elixir 1.17（Erlang/OTP 27）
  • AtomVM 0.7.0-dev
  • AtomGL 7ae82b8
  • Python 3.14
  • ESP-IDF v5.5

手順の全体像

やることをざっくり並べると、以下のとおりです。

• AtomVM・ESP-IDF の準備
• Elixir コアライブラリ生成（Generic UNIX 版 AtomVM）
• AtomVM をビルド
  • ESP32-S3 向け
  • AtomGL コンポーネント追加
  • sdkconfig.defaults で必要な設定を有効化
    • CONFIG_LWIP_IPV6 有効化
    • Elixir 用パーティション設定
• Release イメージ（.img）を生成
• ESP32-S3 に書き込み（消去 -> 書き込み）

順に見ていきます。

AtomVM と ESP-IDF の準備

ホスト環境に必要なツールをインストール

まずは、AtomVM のビルドや ESP32-S3 への書き込みに必要なツールを揃えます。

# Elixir と Python は任意の方法でインストールされている前提
elixir --version
python --version

sudo apt install git wget flex bison gperf cmake ninja-build \
  ccache libffi-dev libssl-dev dfu-util libusb-1.0-0

AtomVM で必要なツールのバージョンについては以下の資料で確認してください。

ESP-IDF を使うために必要なツールについては以下の資料を確認してください。

AtomVM のソースコードを取得

# AtomVM のソースコードの保存場所は任意
ATOMVM_REPO_DIR="$HOME/atomvm/AtomVM"
mkdir -p "$(dirname "$ATOMVM_REPO_DIR")"

git clone https://github.com/atomvm/AtomVM.git "$ATOMVM_REPO_DIR"

以降は、$ATOMVM_REPO_DIR をAtomVM のソースコードのルートディレクトリとします。

ESP-IDF（ESP32-S3 用）をインストール

mkdir -p $HOME/esp
cd $HOME/esp

git clone --branch v5.5 --recursive https://github.com/espressif/esp-idf.git
cd esp-idf

# esp32s3 向けツール群をインストール
./install.sh esp32s3

インストールされたか確認

source $HOME/esp/esp-idf/export.sh
idf.py --version

詳しくは公式ドキュメントを参照してください。

esptool のインストール

色んなインストールの方法があるようです。

pipでインストールする方法

pip install esptool

私は最近は mise を使ってインストールしています。

インストールされたか確認

esptool version

詳しくは公式ドキュメントを参照してください。

Elixir コアライブラリ生成

ESP32 用の完全なイメージを作るためには、先にホスト PC 上で Generic UNIX 版 AtomVM をビルドしておく必要があります。

cd "$ATOMVM_REPO_DIR"

mkdir -p build
cd build

cmake ..
make -j"$(nproc)"

ビルド完了後、次のようなファイルが生成されているはずです。

ls "$ATOMVM_REPO_DIR/build/libs/esp32boot"
# esp32boot.avm
# elixir_esp32boot.avm
# ...

この elixir_esp32boot.avm は後ほど mkimage.sh で Release イメージ（.img）を生成するときに使います。

詳しくは公式ドキュメントを参照してください。

ESP32-S3 向け AtomVM をビルド

ESP32 プラットフォーム用ディレクトリに移動

cd $ATOMVM_REPO_DIR/src/platforms/esp32

ESP-IDF 環境を読み込む

source $HOME/esp/esp-idf/export.sh

以降の idf.py / esptool.py / mkimage.sh / flashimage.sh は、この環境を読み込んだ状態で実行します。

AtomGL コンポーネント追加

AtomGL は ESP32 プラットフォームの components 配下に配置してビルドします。

cd $ATOMVM_REPO_DIR/src/platforms/esp32

mkdir -p components

git clone https://github.com/atomvm/atomgl.git components/atomgl

sdkconfig.defaults を設定

src/platforms/esp32/sdkconfig.defaults に必要な設定を追加します。

• IPv6 を有効化
• Elixir 用のパーティションレイアウトを指定

$ATOMVM_REPO_DIR/src/platforms/esp32/sdkconfig.defaults

- CONFIG_LWIP_IPV6=n
+ CONFIG_LWIP_IPV6=y
+ CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions-elixir.csv"

これで boot.avm / main.avm などが Elixir 向けの構成になります。

IPv6 の有効化については、単にこれがないとビルドが落ちたためです。ビルド時にの何かが IPv6 関連のコードを必要としているようです。

IPv6 の有効化については、AtomGL で IPv6 を使うためというより、ESP-IDF で CONFIG_LWIP_IPV6 を無効化のままだと、依存関係の都合でビルドが通らなかったためです。詳しくはよくわかってません。

ESP32-S3 向けにビルド

ESP-IDF は機種ごとに target 名が異なります。
AtomVM のドキュメントでは esp32 を例にしていますが、ESP32-S3 を使う場合は esp32s3 を指定してください。

cd $ATOMVM_REPO_DIR/src/platforms/esp32

idf.py set-target esp32s3
idf.py reconfigure
idf.py build

ここまでで

• ESP32-S3 向け AtomVM 本体
• Elixir / Erlang コアライブラリを含むビルド成果物
• 各種補助スクリプト（mkimage.sh / flashimage.sh など）

がそろった状態になります。

Release イメージを生成

ESP32-S3 に書き込むための「ひとまとめのイメージ」を mkimage.sh で作成します。

cd $ATOMVM_REPO_DIR/src/platforms/esp32

bash ./build/mkimage.sh --boot ../../../build/libs/esp32boot/elixir_esp32boot.avm

elixir_esp32boot.avm を取り込んだ、Elixir 対応の Release イメージが生成されます。

ls -lh build/atomvm-esp32*
# build/atomvm-esp32s3-xxxxxx.img  のようなファイルができているはず

ESP32-S3 に AtomVM を書き込み

フラッシュ全消去

cd $ATOMVM_REPO_DIR/src/platforms/esp32

esptool.py --chip auto --port /dev/ttyACM0 erase_flash

Release イメージを書き込む

mkimage.sh が生成したイメージを、flashimage.sh でまとめて書き込みます。

cd $ATOMVM_REPO_DIR/src/platforms/esp32

bash ./build/flashimage.sh -p /dev/ttyACM0

flashimage.sh の中では esptool.py が呼ばれ、適切なオフセットに bootloader / パーティションテーブル / AtomVM 本体 / Elixir コアライブラリが書き込まれます。

ここまで終わると、XIAO ESP32-S3 上に AtomVM 本体と Elixir 標準ライブラリ入りの boot.avm がそろった状態になっています。

おわりに

AtomVM をソースコードから AtomGL を使えるイメージとしてビルドする手順をまとめました。

AtomGL をみんなで楽しんだ結果できたコードを共有させていただきます。