この記事の目的

WindowsでQMK Firmware(以下、QMK)のビルド環境がうまく構築できない、ファームウェアのビルドに失敗する、以前はファームウェアがビルドできたが最新化しようとしたら失敗する、うまくファームウェアがビルドできなければビルド環境を捨てて作り直せばいいと思っている、といった人向けに、2021/9/30現在におけるビルド環境構築時のポイントやビルド環境の最新化方法についてまとめた。
なお、QMKの更新状況によってはこの記事の内容は陳腐化するので注意。

QMKのビルド環境の概要

自作キーボードにはAVRやARMなどのMCUが使用されることが多いが、これらのMCU向けのファームウェアをビルドするにはクロスコンパイラを準備する必要がある。Windowsでは、MSYS(MSYS2)とMSYSで利用できるパッケージ群から必要なパッケージをインストールすることで、これらのクロスコンパイラやその他のツールを簡単に準備することができる。

WindowsでQMKのファームウェアをビルドする場合、このMSYSを利用したビルド環境を作るのが公式の推奨手順になっている。また、QMKのビルド環境には、MSYSのほかにQMK CLIというコマンドラインツールが必要で、これはpythonで作成されている。QMK CLIはPython Package Index(PyPI)で公開されているいくつかのパッケージを使用しているため、pythonの他にこれらのパッケージのインストールも必要である。なお、QMK CLI自身もPyPIで公開されているパッケージである。

このように、QMKのビルド環境ではMSYSとpythonのパッケージを利用しているため、これらのパッケージのインストールや更新が正しく行われていないと、ファームウェアのビルドに失敗する原因となる。また、QMK FirmwareのソースコードはGitHubで公開されているため、ソースコードを取得するにはGitコマンドによる操作が必要になっている。

QMK MSYS

QMKの公式のビルド環境構築手順では、QMK MSYSというものを導入するのが推奨されているが、これは標準のMSYSにクロスコンパイラ、ファームウェアの書き込みツール、QMK CLI、ターミナルアプリであるConEmuなどを追加してアイコンなどをQMK用にカスタマイズしたものである。標準のMSYSとQMK MSYSの一番の違いは、起動するとminttyの代わりにConEmuが使用されることと、ホームディレクトリのパスがWindowsのホームディレクトリになっていること(これは /etc/nsswitch.conf を少し修正すれば戻せる)、標準のMSYSの起動スクリプトやバイナリなどが存在しないことくらいで大した違いはなく、後は必要なパッケージがあらかじめインストールされているかどうかである。

従って、MSYSをQMKのためだけに導入する場合はもちろん、MSYSをQMK以外に使用する場合でもQMK MSYSをインストールするのが最も簡単である。もちろん、公式ドキュメントにMSYS単体からのビルド環境構築手順も書かれていて、手順も短いのでMSYS単体から構築しても良い。ただし、現在のところ1つ致命的な問題があるため後述の対策が必要である。

GitHub/Git

自作キーボード界隈でビルド環境構築の次に難しいと思われているものがGitHubやGitの操作だろう。とりあえずmasterブランチには公式リポジトリと同期する以外の変更を加えなければ、決まりきったコマンドをいくつか実行するだけで最新のソースコードを取得することができるので、その方法を真似するだけで良い。

QMKビルド環境の構築

QMK MSYSまたはMSYSのインストール手順(QMKのソースコードの取得も含む)は、公式のインストール手順を参照。ただし、いくつか触れられていない分かりにくいことがあるので、ここではその点について補足する。

64bit版のWindowsがインストールされていない

QMKは64bit環境向けのインストールスクリプトしか用意されていないため、64bit版のWindowsをインストールしておく必要がある。64bitに対応していないようなCPUの場合はまず新しいPCを買うべし。

Windowsのアカウント名に半角英数・半角ハイフン・半角アンダーバー以外の文字を含んでいる

これは必須ではなく推奨だが、Windowsのアカウント名に半角英数・半角ハイフン・半角アンダーバー以外の文字を含んでいる場合は、無用なトラブルを避けるため半角英文字で始まるアカウントを新規に作成してそのアカウントに切り替える。なお、アカウント名には半角英数・半角ハイフン・半角アンダーバー以外の文字を含めないこと。
アカウント名を変更したくない場合は、リポジトリのクローン先フォルダを変更し、半角英数・半角ハイフン・半角アンダーバー以外の文字(ドライブレターの直後のコロンとパスの区切り文字である\マークは除く)を含まないパスにする。

QMK MSYS/MSYSのインストールパスに半角英数・半角ハイフン・半角アンダーバー以外の文字を含んでいる

QMK MSYS/MSYSのインストールパスに半角英数・半角ハイフン・半角アンダーバー以外の文字を含んでいる場合は、無用なトラブルを避けるため一度アンインストールして半角英数・半角ハイフン・半角アンダーバー以外の文字(ドライブレターの直後のコロンとパスの区切り文字である\マークは除く)を含まないパスにインストールし直す。また、各フォルダ名の先頭はハイフンで始まっていないこと。

`qmk setup` コマンド実行中にQMK MSYS/MSYSが勝手に終了してしまう

MSYSの主要なパッケージ(パッケージ管理用のコマンドである pacman や、MSYSのターミナルアプリである mintty など)の更新があると、MSYSが勝手に終了してしまう(通常はY/Nで終了確認を求められるが、自動的にYを応えるオプションで実行されるため終了してしまう)。この場合はQMK MSYS/MSYSを起動し直してもう一度 qmk setup を実行する。

セットアップが進まない

qmk setup コマンド実行中にドライバのインストールが行われるが、この時Windowsの権限昇格の許可を求められる。このダイアログが前面に表示されないため、許可を求められていることに気づかずずっと待っている可能性がある。セットアップが進んでないように感じたらタスクバーで許可を求められていないか確認する。

リポジトリのクローン先フォルダパスを変更したい

公式インストール手順にも説明があるが、qmk setup -H <path> と引数にクローン先フォルダパスを指定することで変更できる。

クローンするリポジトリを自分のアカウントのリポジトリ(forkしたリポジトリ)にしたい

公式インストール手順にも説明があるが、qmk setup <github_username>/qmk_firmware と引数にクローンするリポジトリ名を指定することで変更できる。

MSYSでビルド環境を構築したがファームウェアのビルドができない

QMKに登録されたキーボードやキーマップが増えすぎてビルドできなくなっているため、https://github.com/qmk/qmk_firmware/issues/13416#issuecomment-874362327 のコメント中にあるリンクから make.exe をダウンロードし、MSYSの /usr/bin (デフォルトだと C:\msys64\usr\bin)に上書きコピーする。
ちなみに、QMK MSYSは同様の対策版が既にインストールされているためこの対応は不要。

なお、make.exe を更新するようなMSYSのパッケージ更新があった場合は、Visual Studioをインストールして

editbin.exe /stack:134217728 C:\msys64\usr\bin\make.exe

というコマンドを実行する(パスは環境に合わせて適宜修正)。これは make.exe のスタックサイズを大きくするコマンドで、上述のリンクの make.exe も同様にスタックサイズを大きくしたものである。

QMKビルド環境の最新化

構築済みのQMKビルド環境を最新化する方法について、QMKソースコードの最新化、QMK MSYS/MSYSの最新化、QMK CLIの最新化の3つに分けて説明する。

QMKソースコードの最新化

QMK MSYS/MSYSを起動して以下のようにコマンドを実行すると、QMKとQMKのライブラリ群のソースコードを最新化できる。

QMK公式リポジトリをクローンしている場合(`qmk setup` を実行した場合)

cd <qmk_firmwareフォルダ>
git fetch
git merge
make git-submodule

make git-submodule コマンド実行時にQMK CLIに関するメッセージが表示されることがあるが、ここでは無視して良い。

自分のアカウントのQMKリポジトリをクローンしている場合(`qmk setup <github_username>/qmk_firmware` を実行した場合)

あらかじめ以下のコマンドを実行して公式リポジトリを参照できるように設定しておく。

cd <qmk_firmwareフォルダ>
git remote add upstream https://github.com/qmk/qmk_firmware
git fetch --all

この設定がされている前提で、以下のコマンドを実行する。

cd <qmk_firmwareフォルダ>
git fetch --all
git merge upstream/master
make git-submodule

make git-submodule コマンド実行時にQMK CLIに関するメッセージが表示されることがあるが、ここでは無視して良い。

QMK MSYS/MSYSの最新化

以下のコマンドを実行することでQMK MSYS/MSYSを最新化できる。

pacman -Syu

MSYSのパッケージ管理ツールである pacman 自体に更新がある場合、一度終了するかどうか確認されるため、終了後に再度QMK MSYS/MSYSを起動してもう一度コマンドを実行する。

ここで何らかのエラーが出た場合は、インターネット接続の問題かMSYS側の更新によるトラブルだと考えられるため、表示されたエラーメッセージに従って対処するしかない。

QMK CLIの最新化

QMK MSYS/MSYSを起動して以下のようにコマンドを実行することでQMK CLIを最新化できる。

python3 -m pip install -U qmk

QMK CLI以外のpythonパッケージを最新化する場合は以下のコマンドを実行する。

python3 -m pip install -U -r requirements.txt

トラブルシューティング

ファームウェアのビルドができない場合、QMK CLIやpythonパッケージが問題になっているケースが多い。この場合、QMK CLIとpythonパッケージをアンインストールしてから再度インストールし直すと問題が解決する可能性が高い。

QMK MSYS/MSYSを起動して以下のようにコマンドを実行する。

cd <qmk_firmwareフォルダ>
python3 -m pip uninstall qmk
python3 -m pip uninstall -r requirements.txt
python3 -m pip install qmk