WEB GDEXTENSION ビルド環境構築及びエクスポートテンプレートのビルド
本稿は GDEXTENSION の WEB エクスポートを試した際のメモの共有を意図した、一連の記事の２番目。１番目から順に読まれていくことを想定している。
対象としている Godot エンジンのバージョンは 4.2.1。
前稿では、Godot エンジンのGDEXTENSION を用いていない簡単なサンプルを作成し、WEB（HTML5） エクスポートを行い、実際に WEB ブラウザ（Windows の Chrome）で動作することを確認した。
本稿では emscripten をインストールし WEB（HTML5）用ビルド環境を構築する。また、Godot エンジンの WEB（HTML5）向けエクスポートテンプレートのビルドを試す。
今回構築する開発環境
WEB（HTML5）向けに開発環境を構築する。WEB 向けはクロスコンパイル環境となり、コンパイラは emscripten を用いる。emscripten は LLVM/Clang ベースの WebAssembly ターゲットのコンパイラで、Windows 10/11 のコマンドプロンプトでも利用することができる。
emscripten はビルドツールチェーンとして LLVM/Clang に依存している。また make や objdump といった幾つかのツールが欠けている。更に、Godot エンジン（GDEXTENSION）や C++ ライブラリをビルドするのに必要な、scons/cmake といったビルドシステムは別途必要。本稿ではこれらを含めて emscripten 用の開発環境を Windows11 用に構築する。
Godot GDEXTENSION build 環境構築のまとめ（その１）で Windows 環境で Windows プラットフォームターゲット用のビルド環境を構築した。WEB 用ターゲットは emscripten を用いるが、他のツールはまるごと Windows プラットフォームターゲットのものを流用する。なので、Godot GDEXTENSION build 環境構築のまとめ（その１）でのインストールが完了している前提とする。この前提であれば、追加で必要なインストールは少ない。
ディレクトリ構造計画
Godot GDEXTENSION build 環境構築のまとめ（その１） で行ったように Godot GDEXTENSION 関連のソフトウェア開発を行うにあたり、c:\dev ディレクトリを作成しその下にできるだけ開発環境を纏めてゆく。
そして、build に必要なツール類は c:\dev\tools ディレクトリを作成し、その下にできるだけまとめてゆく。
ツール類
curl, 7-zip, tar, git, Cmake, Python3, scons
Godot GDEXTENSION build 環境構築のまとめ（その１） の各項目参照。
emscripten
emscripten は WebAssembly ターゲットの C/C++ コンパイラを含むビルドツールチェーン。Windows/macOS/Linux などで動作するが、意味的にいずれのプラットフォームでもブラウザで実行するバイトコードを吐き出すクロスコンパイラとして機能する。
emscripten の配布サイトは以下。
https://emscripten.org/
変化が激しい WEB ブラウザがターゲットであるだけあって、emscripten 自身も変化が激しく、バージョンによって大きく挙動が異なる。よってemscripten のインストールにあたって、バージョン指定は最新の注意を払う必要がある。
Windows 向けインストール手順として、しばしば以下のようなコマンド例が示される。
git clone https://github.com/emscripten-core/emsdk.git cd emsdk .\emsdk install latest .\emsdk activate latest .\emsdk_env
これは emscripten の最新バージョンをインストールするものであるが、ビルドは大抵うまくいかない。理由はビルド対象の想定より現状の emscripten のバージョンが進みすぎていて、ミスマッチとなることが多いことによる。ビルド対象プロジェクトが使っている emscripten のバージョンを確認して、同じバージョンをインストールすると余計なトラブルに遭う機会が減る。
Godot Engine 4.2 documentation の “Compiling for the Web” の項を見ると以下の記載がある。
Requirements¶ To compile export templates for the Web, the following is required: Emscripten 1.39.9+. Python 3.6+. SCons 3.0+ build system.
これを見ると emscripten 1.39.9 をインストールすれば良いように見えるが、これもうまくいかない。emscripten 1.39.9 は2020/05 リリースであり古すぎてミスマッチとなる。どうもこの部分の記述は数年間メンテナンスされていないようだ。
では、どのバージョンを選べばよいか、であるが以下の議論を踏まえて、Godot エンジン 4.2.1 の断面ではemscripten 3.1.39 を選択するのが安全。
https://github.com/godotengine/godot/issues/80010
https://github.com/godotengine/godot/issues/82865
https://github.com/godotengine/godot/issues/84008
いずれにしろ、Godot4 GDEXTENSION での emscripten の使用可能バージョンの範囲は酷く狭い。
バージョンを指定しての emscripten のインストールは以下のようになる。
c:\dev\tools>git clone https://github.com/emscripten-core/emsdk.git c:\dev\tools>cd emsdk c:\dev\tools\emsdk>.\emsdk install 3.1.39 c:\dev\tools\emsdk>.\emsdk activate 3.1.39 c:\dev\tools\emsdk>.\emsdk_env
最後の emsdk_env.bat の実行は環境変数を整えるもの。これを実行することにより 環境変数 PATH が設定され、emcc などのビルドツールチェーンが使えるようになる。以下のように emcc コマンドが実行できればインストールは成功。
c:\dev\tools\emsdk>emcc --version emcc (Emscripten gcc/clang-like replacement + linker emulating GNU ld) 3.1.39 (36f871819b566281d160470a1ec4515f379e9f77) Copyright (C) 2014 the Emscripten authors (see AUTHORS.txt) This is free and open source software under the MIT license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. c:\dev\tools\emsdk>
なお、 emsdk_env.bat は一時的に環境変数を設定するもので、設定の不揮発化はしない。コマンドプロンプトを閉じると設定は消え、新たなコマンドプロンプトには引き継がれないことに注意。
%HOMEPATH%\emsdk.bat ファイルに以下を追加することにより、毎回設定すると簡便である。
CALL c:\dev\tools\emsdk\emsdk_env.bat
MinGW-w64
emscripten は make コマンドを提供しない。Godot GDEXTENSION build 環境構築のまとめ（その１） でMinGW-w64 をインストールしているので、含まれる mingw32-make を流用する。
LLVM
LLVM のインストールは必須ではない。emscripten は LLVM/Clang に依存しているが、emscripten のインストールでパッケージの一部として LLVM のサブセットが同時にインストールされる。よってコンパイルしてリンクして、実行するといった用途だけであれば LLVM の個別インストールは不要。ただし clang-format や llvm-objdump など、良く使われるツール類が欠けている。これらが必要な場合、LLVM をインストールすれば良い。
インストールする LLVM のバージョンであるが clang-format や llvm-objdump といったツールを使いたいだけであればあまり気にせず、新しめのものをインストールすれば良い。もしバージョンを気にするのならば、emscripten が同梱している LLVM に合わせると良いかもしれない。
前項で emscripten 3.1.39 をインストールしたが、以下のようにすると LLVM のバージョンが 17.0.0 であることが分かる。
c:\dev\tools\emsdk>emar --version LLVM (http://llvm.org/): LLVM version 17.0.0git Optimized build. c:\dev\tools\emsdk>
これは emar が llvm-ar のラッパーであることを利用したもの。
ライブラリ管理
C++ ライブラリをビルドした際の格納先
ビルド済み C++ ライブラリはビルドに用いたビルドツールチェーンに紐づく。特に GDEXTENSION の場合、mingw64, mingw32, android, web といったクロス開発環境での開発になることが予想されるので、ビルド済みライブラリの格納先を決める必要がある。
ここではビルドツールのインストールルートディレクトリ c:\dev\tools\emsdk 配下に local というディレクトリを作成し、その中に opencv-4.8 などのディレクトリを作成し、ビルド済みライブラリを格納することを提案する。
以下のように Cmake 用の環境変数 CMAKE_PREFIX_PATH を通しておけば、ビルド済のライブラリを Cmake で find_package を行う際の検索対象にするので、find_package ライブラリが見つけやすくなる効果が期待できる。
SET CMAKE_PREFIX_PATH=C:\dev\tools\emsdk\local
PATH 設定用 バッチファイルの設置
コマンドプロンプトを起動した際のディレクトリである %HOMEPATH% のディレクトリに以下のバッチファイルを設置しておく。（このファイルは記事が進むにつれて成長してゆく。
%HOMEPATH%\emsdk.bat
SET PATH=%PATH%;"C:\Program Files\7-Zip" SET PATH=%PATH%;C:\dev\tools\pkg-config\bin SET PATH=C:\dev\tools\Python\Python312\Scripts;C:\dev\tools\Python\Python312;%PATH% SET PATH=C:\dev\tools\mingw64\bin;%PATH% SET PATH=C:\dev\godot-4.2.1-stable\bin;%PATH% SET PKG_CONFIG_EXE_DIR=C:\dev\tools\pkg-config\bin CALL c:\dev\tools\emsdk\emsdk_env.bat SET PKG_CONFIG_PATH="" cd c:\dev
GODOT エンジンの カスタムWEB エクスポートテンプレートのビルド
Godot 4.2.1 の WEB エクスポートテンプレートはデフォルト状態で、GDEXTENSION をサポートしている。従って単に WEB 向け GDESTENSION を試したいだけであるのならば、カスタムWEB エクスポートテンプレートのビルドを行う必要はない。
カスタムWEB エクスポートテンプレートのビルドは、不要な機能を省いてWEB エクスポートテンプレートのファイルサイズを小さくする場合等に有効。
WEB エクスポートテンプレートのビルド
前項までで、emscripten 用の環境構築が完了した。次に GODOT エンジンの カスタムWEB エクスポートテンプレートのビルドを試みる。カスタムと言っても野良ビルドするだけで、特に改造は行わない。C:\dev\godot-4.2.1-stable に Godot 4.2.1 のソースコード一式を取得しているものとする。取得していない場合は以下のようにして取得する。
Microsoft Windows [Version 10.0.22631.3007] (c) Microsoft Corporation. All rights reserved. C:\Users\user>.\emsdk.bat c:\dev>git clone --depth 1 https://github.com/godotengine/godot.git -b 4.2.1-stable godot-4.2.1-stable c:\dev> c:\dev>cd godot-4.2.1-stable c:\dev\godot-4.2.1-stable>
Godot 4.2.1 のemscripten でのビルドは コンパイラバージョンの取得処理で不具合箇所があるので修正する。具体的には以下のように修正する。
C:\dev\godot-4.2.1-stable\methods.py
if not env.msvc:
# Not using -dumpversion as some GCC distros only return major, and
# Clang used to return hardcoded 4.2.1: # https://reviews.llvm.org/D56803
try:
- version = subprocess.check_output([env.subst(env["CXX"]), "--version"]).strip().decode("utf-8")
+ if os.name == 'nt':
+ version = subprocess.check_output([env.subst(env["CXX"]), "--version"],shell=True).strip().decode("utf-8")
+ else:
+ version = subprocess.check_output([env.subst(env["CXX"]), "--version"]).strip().decode("utf-8")
except (subprocess.CalledProcessError, OSError):
print("Couldn't parse CXX environment variable to infer compiler version.")
return ret
一応説明しておくと、以下の処理は “emcc –version” というコマンドを subprocess.check_output() を用いて発行しようとしている。
version = subprocess.check_output([env.subst(env["CXX"]), "--version"]).strip().decode("utf-8")
しかし、”C:\dev\tools\emsdk\upstream\emscripten” ディレクトリにある emcc というコマンドは シェルスクリプトであり、Windows のコマンドプロンプトでは実行ファイルとして認められない。よって subprocess.check_output() はemcc を実行することができず例外を発生させる。Windows のコマンドプロンプトで emcc というコマンドで実行されるファイルの実態は “C:\dev\tools\emsdk\upstream\emscripten\emcc.bat” というバッチファイル。emcc というコマンドを実行したときに emcc.bat や emcc.exe といったサフィックスの省略を許して実行可能としているのはコマンドプロンプトなどのシェルの機能であることに注意。なので、以下のように subprocess.check_output() の実行では “shell=True” を付与する必要がある。
version = subprocess.check_output([env.subst(env["CXX"]), "--version"],shell=True).strip().decode("utf-8")
上記を修正するとビルドは比較的スムースに実行できる。
GDEXTENSION 非サポートのデバッグビルド
GDEXTENSION 非サポートのデバッグビルドは以下のコマンドを実行する。
c:\dev\godot-4.2.1-stable>scons platform=web target=template_debug javascript_eval=no
これを実行すると、以下のファイルが生成される。
C:\dev\godot-4.2.1-stable\bin\godot.web.template_debug.wasm32.zip
サイズは約9.5MB。
GDEXTENSION 非サポートのリリースビルド
GDEXTENSION 非サポートのリリースビルドは以下のコマンドを実行する。
c:\dev\godot-4.2.1-stable>scons platform=web target=template_release javascript_eval=no
これを実行すると、以下のファイルが生成される。
C:\dev\godot-4.2.1-stable\bin\godot.web.template_release.wasm32.zip
サイズは約7.9MB。
GDEXTENSION サポートのデバッグビルド
GDEXTENSION サポートのデバッグビルドは以下のコマンドを実行する。
c:\dev\godot-4.2.1-stable>scons platform=web dlink_enabled=yes target=template_debug javascript_eval=no
これを実行すると、以下のファイルが生成される。
C:\dev\godot-4.2.1-stable\bin\godot.web.template_debug.wasm32.dlink.zip
サイズは約11.2MB。
GDEXTENSION サポートのリリースビルド
GDEXTENSION サポートのリリースビルドは以下のコマンドを実行する。
c:\dev\godot-4.2.1-stable>scons platform=web dlink_enabled=yes target=template_release javascript_eval=no
これを実行すると、以下のファイルが生成される。
C:\dev\godot-4.2.1-stable\bin\godot.web.template_release.wasm32.dlink.zip
サイズは約11.2MB。
カスタムWEB エクスポートテンプレートを用いたエクスポート
上部メニュー「プロジェクト」の「エクスポート」を選択すると「エクスポート」ダイアログが開く。ここで「バリアント」の項目で GDEXTENSION をサポートするか否かを、「Extension Support」の項で選択する。そして、「カスタムテンプレート」の項でデバッグ用とリリース用のカスタムテンプレートを設定することにより任意のカスタムエクスポートテンプレートを指定することができる。
本稿の振り返りと次稿について
Windows 用（MinGW-w64）の環境構築ができていれば、WEB（HTML5）用の環境構築は比較的簡単であった。GODOT エンジンの カスタムWEB エクスポートテンプレートのビルド環境も良く整備されている印象をうける。生成される、カスタムWEB エクスポートテンプレートのファイルサイズも、デバッグビルドで約11MBと非常に小さい。
次稿では、GDEXTENSION の公式サンプルのビルドと設置を試みる。
コメント