Keyball のファームウェアを Docker でローカルで簡単にビルドする

QMK の機能のひとつである、コンボキーを Keyball に設定しようとすると、Keyball のファームウェアを自前でビルドしなければいけませんが、本家リポジトリでは GitHub Actions でビルドするようになっており、

コードの変更 → push → Actions の実行を待つ → 生成物のダウンロード

と結構手順が煩雑です。一方でローカルでビルドしようとすると、Windows の場合は QMK MSYS をインストールしろ、と公式ドキュメントに書かれていたりします。QMK のためにそんなのインストールしたくないなと思っていたところ、普通に Docker でビルドすることができたのでその手順について書きます。
なお記載する手順は、Keyball リポジトリの Actions の処理内容を Docker で実行する、というものなので、不明な点がある場合は Actions の定義をみるといいでしょう。

前提

Keyball のリポジトリをフォークして、Keyball39 の via キーマップのソースコードを編集している前提で記事を書きます。
Keyball のサイズ、キーマップなどの部分は各自で適宜読みかえてください。

手順

Dockerfile の作成

以下のような Dockerfile を作成します。

FROM ghcr.io/qmk/qmk_cli:latest
WORKDIR /usr/src

RUN git clone --recursive --branch 0.22.14 https://github.com/qmk/qmk_firmware.git __qmk__
RUN qmk setup --home __qmk__ --yes
RUN /usr/bin/python3 -m pip install -r __qmk__/requirements.txt

QMK のバージョンが 0.22.14 に固定になっていますが、私が本家 Actions の定義を確認したときのバージョンをそのまま記述しただけなので、最新の Keyball リポジトリをフォークした場合はここが変わっている場合があるかもしれません。

ビルドスクリプトの作成

同じくリポジトリ直下に以下のようなシェルスクリプトファイル (build.sh) を作成します。

ln -s $(pwd)/qmk_firmware/keyboards/keyball ../__qmk__/keyboards/keyball
qmk compile -j <論理コア数> -kb keyball/keyball39 -km via
mkdir -p tmp
cp ../__qmk__/keyball_keyball39_via.hex tmp/keyball39.hex

qmk compile コマンドの j オプションはビルド時に CPU を何コア使うかのオプションです。$(nproc) と書くと後述の docker compose run のときにエラーが出たので、私は開発マシンの論理コア数をベタ書きしていますｗ

compose.yml の作成

さらにリポジトリ直下に以下の compose.yml を作成します。

version: '3.8'
services:
  build:
    build:
      context: .
    container_name: keyball-build-container
    volumes:
      - .:/usr/src/app
    working_dir: /usr/src/app
    command: bash build.sh

ビルドの実行

ここまでできたら以下のコマンドを実行すると、ファームウェアのビルドが実行され、tmp/ ディレクトリに .hex ファイルが作成されます。お疲れさまでした。

docker compose run --rm build

おわりに

ファームウェアを編集できるとかなりカスタムの幅が広がって楽しいです。
コンボキーがかなり便利で、コンボキー前提で結構キーマップが固まってきたので、キーマップの記事も書いていきたいですね。