WebAssembly とは何ですか？どこから来たのですか？で、本日は、現在の WebAssembly に至るまでの経緯について説明しました。この記事では、既存の C プログラム mkbitmap を WebAssembly にコンパイルする方法について説明します。ファイルの操作、WebAssembly と JavaScript 間の通信、キャンバスへの描画が含まれるため、hello world の例よりも複雑ですが、複雑すぎない程度に管理できます。
この記事は、WebAssembly を学習したいウェブ デベロッパーを対象としており、mkbitmap のようなものを WebAssembly にコンパイルする場合の手順を説明しています。なお、アプリやライブラリが初回実行時にコンパイルされないのはごく普通のことです。そのため、以下の手順の一部が機能しなかったため、後戻りして別の方法でやり直す必要がありました。この記事では、空から降ってきたかのように魔法のような最終的なコンパイル コマンドを示すのではなく、実際の進捗状況と、いくつかの不満点について説明しています。
mkbitmap について
mkbitmap C プログラムは、画像を読み取り、反転、高周波フィルタリング、スケーリング、しきい値設定のいずれか 1 つ以上のオペレーションを順番に適用します。各オペレーションは個別に制御でき、オンまたはオフにできます。mkbitmap の主な用途は、カラー画像またはグレースケール画像を、他のプログラム（特に、SVGcode の基盤となるトレース プログラム potrace）の入力に適した形式に変換することです。mkbitmap は、前処理ツールとして、スキャンされた線画（漫画や手書きテキストなど）を高解像度の 2 値画像に変換する場合に特に便利です。
mkbitmap を使用するには、複数のオプションと 1 つ以上のファイル名を渡します。詳細については、ツールの man ページをご覧ください。
$ mkbitmap [options] [filename...]
mkbitmap -f 2 -s 2 -t 0.48（ソース）。コードを取得する
最初のステップは、mkbitmap のソースコードを取得することです。プロジェクトのウェブサイトで確認できます。執筆時点では、potrace-1.16.tar.gz が最新バージョンです。
ローカルでコンパイルしてインストールする
次のステップでは、ツールをローカルでコンパイルしてインストールし、動作を確認します。INSTALL ファイルには、次の手順が含まれています。
cdをパッケージのソースコードを含むディレクトリに移動し、./configureと入力してシステム用にパッケージを構成します。configureの実行には時間がかかることがあります。実行中は、チェック対象の機能に関するメッセージがいくつか出力されます。makeと入力してパッケージをコンパイルします。必要に応じて、
make checkと入力して、パッケージに付属のセルフテストを実行します。通常は、ビルドしたばかりの未インストールのバイナリを使用します。make installと入力して、プログラム、データファイル、ドキュメントをインストールします。root が所有するプレフィックスにインストールする場合は、パッケージを通常のユーザーとして構成してビルドし、make installフェーズのみを root 権限で実行することをおすすめします。
これらの手順を完了すると、potrace と mkbitmap の 2 つの実行可能ファイルが作成されます。この記事では、後者のファイルについて説明します。mkbitmap --version を実行して、正しく機能していることを確認できます。以下は、私のマシンで実行した 4 つのステップの出力です。簡潔にするために大幅に切り詰めています。
ステップ 1、./configure:
$ ./configure
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
checking for a thread-safe mkdir -p... ./install-sh -c -d
checking for gawk... no
checking for mawk... no
checking for nawk... no
checking for awk... awk
checking whether make sets $(MAKE)... yes
[…]
config.status: executing libtool commands
ステップ 2、make:
$ make
/Applications/Xcode.app/Contents/Developer/usr/bin/make all-recursive
Making all in src
clang -DHAVE_CONFIG_H -I. -I.. -g -O2 -MT main.o -MD -MP -MF .deps/main.Tpo -c -o main.o main.c
mv -f .deps/main.Tpo .deps/main.Po
[…]
make[2]: Nothing to be done for `all-am'.
ステップ 3、make check:
$ make check
Making check in src
make[1]: Nothing to be done for `check'.
Making check in doc
make[1]: Nothing to be done for `check'.
[…]
============================================================================
Testsuite summary for potrace 1.16
============================================================================
# TOTAL: 8
# PASS: 8
# SKIP: 0
# XFAIL: 0
# FAIL: 0
# XPASS: 0
# ERROR: 0
============================================================================
make[1]: Nothing to be done for `check-am'.
ステップ 4、sudo make install:
$ sudo make install
Password:
Making install in src
.././install-sh -c -d '/usr/local/bin'
/bin/sh ../libtool --mode=install /usr/bin/install -c potrace mkbitmap '/usr/local/bin'
[…]
make[2]: Nothing to be done for `install-data-am'.
正常に動作しているかどうかを確認するには、mkbitmap --version を実行します。
$ mkbitmap --version
mkbitmap 1.16. Copyright (C) 2001-2019 Peter Selinger.
バージョンの詳細が表示されたら、mkbitmap が正常にコンパイルされ、インストールされています。次に、これらの手順と同等の処理を WebAssembly で実行できるようにします。
mkbitmap を WebAssembly にコンパイルする
Emscripten は、C/C++ プログラムを WebAssembly にコンパイルするためのツールです。Emscripten のプロジェクトのビルドに関するドキュメントには、次のように記載されています。
Emscripten で大規模なプロジェクトをビルドするのは非常に簡単です。Emscripten には、
gccのドロップイン リプレースメントとしてemccを使用するように makefile を構成する 2 つのシンプルなスクリプトが用意されています。ほとんどの場合、プロジェクトの現在のビルドシステムの残りの部分は変更されません。
ドキュメントは次のように続きます（簡潔にするために一部編集しています）。
通常、次のコマンドを使用してビルドする場合を考えてみましょう。
./configure
make
Emscripten でビルドするには、代わりに次のコマンドを使用します。
emconfigure ./configure
emmake make
つまり、基本的に ./configure は emconfigure ./configure に、make は emmake make になります。次の例は、mkbitmap を使用してこの処理を行う方法を示しています。
ステップ 0、make clean:
$ make clean
Making clean in src
rm -f potrace mkbitmap
test -z "" || rm -f
rm -rf .libs _libs
[…]
rm -f *.lo
ステップ 1、emconfigure ./configure:
$ emconfigure ./configure
configure: ./configure
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
checking for a thread-safe mkdir -p... ./install-sh -c -d
checking for gawk... no
checking for mawk... no
checking for nawk... no
checking for awk... awk
[…]
config.status: executing libtool commands
ステップ 2、emmake make:
$ emmake make
make: make
/Applications/Xcode.app/Contents/Developer/usr/bin/make all-recursive
Making all in src
/opt/homebrew/Cellar/emscripten/3.1.36/libexec/emcc -DHAVE_CONFIG_H -I. -I.. -g -O2 -MT main.o -MD -MP -MF .deps/main.Tpo -c -o main.o main.c
mv -f .deps/main.Tpo .deps/main.Po
[…]
make[2]: Nothing to be done for `all'.
問題がなければ、ディレクトリのどこかに .wasm ファイルが作成されているはずです。find . -name "*.wasm" を実行すると確認できます。
$ find . -name "*.wasm"
./a.wasm
./src/mkbitmap.wasm
./src/potrace.wasm
最後の 2 つは有望なため、cd を src/ ディレクトリに移動します。また、対応する新しいファイルが 2 つ（mkbitmap と potrace）追加されています。この記事では、mkbitmap のみが関連します。拡張子が .js ではないのは少し混乱しますが、実際には JavaScript ファイルです。これは、簡単な head 呼び出しで確認できます。
$ cd src/
$ head -n 20 mkbitmap
// include: shell.js
// The Module object: Our interface to the outside world. We import
// and export values on it. There are various ways Module can be used:
// 1. Not defined. We create it here
// 2. A function parameter, function(Module) { ..generated code.. }
// 3. pre-run appended it, var Module = {}; ..generated code..
// 4. External script tag defines var Module.
// We need to check if Module already exists (e.g. case 3 above).
// Substitution will be replaced with actual code on later stage of the build,
// this way Closure Compiler will not mangle it (e.g. case 4. above).
// Note that if you want to run closure, and also to use Module
// after the generated code, you will need to define var Module = {};
// before the code. Then that object will be used in the code, and you
// can continue to use Module afterwards as well.
var Module = typeof Module != 'undefined' ? Module : {};
// --pre-jses are emitted after the Module integration code, so that they can
// refer to Module (if they choose; they can also define Module)
mv mkbitmap mkbitmap.js を呼び出して JavaScript ファイルの名前を mkbitmap.js に変更します（必要に応じて mv potrace potrace.js も呼び出します）。次に、node mkbitmap.js --version を実行してコマンドラインで Node.js を使用してファイルを実行し、正常に動作するかどうかを確認します。
$ node mkbitmap.js --version
mkbitmap 1.16. Copyright (C) 2001-2019 Peter Selinger.
mkbitmap が WebAssembly に正常にコンパイルされました。次のステップは、ブラウザで動作するようにすることです。
mkbitmap（ブラウザ内の WebAssembly を使用）
mkbitmap.js ファイルと mkbitmap.wasm ファイルを mkbitmap という新しいディレクトリにコピーし、mkbitmap.js JavaScript ファイルを読み込む index.html HTML ボイラープレート ファイルを作成します。
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>mkbitmap</title>
</head>
<body>
<script src="mkbitmap.js"></script>
</body>
</html>
mkbitmap ディレクトリを提供するローカル サーバーを起動し、ブラウザで開きます。入力を求めるメッセージが表示されます。これは想定どおりです。ツールのマニュアル ページによると、「[i]ファイル名引数を指定しない場合、mkbitmap はフィルタとして動作し、標準入力から読み取る」ためです。Emscripten では、デフォルトで prompt() です。
自動実行を防止する
mkbitmap の即時実行を停止し、代わりにユーザー入力を待機させるには、Emscripten の Module オブジェクトを理解する必要があります。Module は、実行のさまざまなポイントで Emscripten 生成コードが呼び出す属性を持つグローバル JavaScript オブジェクトです。Module の実装を提供して、コードの実行を制御できます。Emscripten アプリケーションの起動時に、Module オブジェクトの値が確認され、適用されます。
mkbitmap の場合は、Module.noInitialRun を true に設定して、プロンプトの表示を招く最初の実行を回避します。script.js というスクリプトを作成し、index.html の <script src="mkbitmap.js"></script> の前に追加し、script.js に次のコードを追加します。アプリを再読み込みすると、プロンプトは表示されなくなります。
var Module = {
// Don't run main() at page load
noInitialRun: true,
};
その他のビルドフラグを使用してモジュラー ビルドを作成する
アプリに入力を提供する場合は、Module.FS で Emscripten のファイル システム サポートを使用できます。ドキュメントのファイル システムのサポートの追加セクションには、次のように記載されています。
Emscripten は、ファイル システムのサポートを含めるかどうかを自動的に決定します。多くのプログラムではファイルは必要ありません。また、ファイル システムのサポートはサイズが軽視できないため、Emscripten では、理由がない場合はファイル システムを組み込みません。つまり、C/C++ コードがファイルにアクセスしない場合、
FSオブジェクトやその他のファイル システム API は出力に含まれません。一方、C/C++ コードでファイルを使用している場合は、ファイル システムのサポートが自動的に含まれます。
残念ながら、mkbitmap は Emscripten がファイル システムのサポートを自動的に含めないケースの一つであるため、明示的に指示する必要があります。つまり、前述の emconfigure と emmake の手順に沿って、CFLAGS 引数でさらにいくつかのフラグを設定する必要があります。次のフラグは、他のプロジェクトでも役立つ場合があります。
- ファイル システムのサポートが含まれるように
-sFILESYSTEM=1を設定します。 Module.FSとModule.callMainがエクスポートされるように-sEXPORTED_RUNTIME_METHODS=FS,callMainを設定します。-sMODULARIZE=1と-sEXPORT_ES6を設定して、最新の ES6 モジュールを生成します。- プロンプトの表示を招く最初の実行を防ぐには、
-sINVOKE_RUN=0を設定します。
また、この場合は、WebAssembly 用にコンパイルしていることを configure スクリプトに伝えるために、--host フラグを wasm32 に設定する必要があります。
最終的な emconfigure コマンドは次のようになります。
$ emconfigure ./configure --host=wasm32 CFLAGS='-sFILESYSTEM=1 -sEXPORTED_RUNTIME_METHODS=FS,callMain -sMODULARIZE=1 -sEXPORT_ES6 -sINVOKE_RUN=0'
emmake make を再度実行し、新しく作成したファイルを mkbitmap フォルダにコピーしてください。
ES モジュール script.js のみを読み込むように index.html を変更し、そこから mkbitmap.js モジュールをインポートします。
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>mkbitmap</title>
</head>
<body>
<!-- No longer load `mkbitmap.js` here -->
<script src="script.js" type="module"></script>
</body>
</html>
// This is `script.js`.
import loadWASM from './mkbitmap.js';
const run = async () => {
const Module = await loadWASM();
console.log(Module);
};
run();
ブラウザでアプリを開くと、Module オブジェクトが DevTools コンソールにログに記録され、プロンプトは表示されなくなります。これは、mkbitmap の main() 関数が起動時に呼び出されなくなったためです。
メイン関数を手動で実行する
次のステップでは、Module.callMain() を実行して mkbitmap の main() 関数を手動で呼び出します。callMain() 関数は、コマンドラインから渡す引数と 1 つずつ一致する引数の配列を受け取ります。コマンドラインで mkbitmap -v を実行する場合は、ブラウザで Module.callMain(['-v']) を呼び出します。これにより、mkbitmap のバージョン番号が DevTools コンソールに記録されます。
// This is `script.js`.
import loadWASM from './mkbitmap.js';
const run = async () => {
const Module = await loadWASM();
Module.callMain(['-v']);
};
run();
標準出力をリダイレクトする
デフォルトの標準出力（stdout）はコンソールです。ただし、出力を変数に格納する関数など、他の場所にリダイレクトできます。つまり、Module.print プロパティを設定することで、出力を HTML に追加できます。
// This is `script.js`.
import loadWASM from './mkbitmap.js';
const run = async () => {
let consoleOutput = 'Powered by ';
const Module = await loadWASM({
print: (text) => (consoleOutput += text),
});
Module.callMain(['-v']);
document.body.textContent = consoleOutput;
};
run();
入力ファイルをメモリ ファイル システムに取得する
入力ファイルをメモリ ファイル システムに取得するには、コマンドラインで mkbitmap filename と同等のものが使用されている必要があります。解決方法を理解するには、まず mkbitmap が入力を想定し、出力を生成する仕組みについて説明します。
mkbitmap でサポートされている入力形式は、PNM（PBM、PGM、PPM）と BMP です。出力形式は、ビットマップの場合は PBM、グレーマップの場合は PGM です。filename 引数が指定されている場合、mkbitmap はデフォルトで、入力ファイル名のサフィックスを .pbm に変更して、その名前を取得した出力ファイルを作成します。たとえば、入力ファイル名が example.bmp の場合、出力ファイル名は example.pbm になります。
Emscripten は、ローカル ファイル システムをシミュレートする仮想ファイル システムを提供します。これにより、同期ファイル API を使用するネイティブ コードをほとんど変更せずにコンパイルして実行できます。mkbitmap が filename コマンドライン引数として渡されたかのように入力ファイルを読み取るには、Emscripten が提供する FS オブジェクトを使用する必要があります。
FS オブジェクトはインメモリ ファイル システム（一般に MEMFS と呼ばれます）を基盤としており、仮想ファイル システムにファイルを書き込むために使用する writeFile() 関数があります。writeFile() は、次のコードサンプルに示すように使用します。
ファイル書き込みオペレーションが正常に完了したことを確認するには、FS オブジェクトの readdir() 関数をパラメータ '/' を指定して実行します。example.bmp と、常に自動的に作成されるデフォルトのファイルがいくつか表示されます。
バージョン番号を出力するための Module.callMain(['-v']) の呼び出しは削除されています。これは、Module.callMain() は通常 1 回だけ実行されることが想定される関数であるためです。
// This is `script.js`.
import loadWASM from './mkbitmap.js';
const run = async () => {
const Module = await loadWASM();
const buffer = await fetch('https://example.com/example.bmp').then((res) => res.arrayBuffer());
Module.FS.writeFile('example.bmp', new Uint8Array(buffer));
console.log(Module.FS.readdir('/'));
};
run();
最初の実際の実行
準備ができたら、Module.callMain(['example.bmp']) を実行して mkbitmap を実行します。MEMFS の '/' フォルダの内容をログに記録すると、example.bmp 入力ファイルの横に新しく作成された example.pbm 出力ファイルが表示されます。
// This is `script.js`.
import loadWASM from './mkbitmap.js';
const run = async () => {
const Module = await loadWASM();
const buffer = await fetch('https://example.com/example.bmp').then((res) => res.arrayBuffer());
Module.FS.writeFile('example.bmp', new Uint8Array(buffer));
Module.callMain(['example.bmp']);
console.log(Module.FS.readdir('/'));
};
run();
出力ファイルをメモリ ファイル システムから取得する
FS オブジェクトの readFile() 関数を使用すると、前の手順でメモリ ファイル システムに作成した example.pbm を取得できます。ブラウザでは通常、ブラウザ内で直接表示するための PBM ファイルがサポートされていないため、この関数は Uint8Array を返します。この Uint8Array は File オブジェクトに変換してディスクに保存します。（ファイルを保存するより優雅な方法もありますが、動的に作成された <a download> を使用する方法が最も広くサポートされています）。ファイルが保存されたら、お気に入りの画像ビューアーで開くことができます。
// This is `script.js`.
import loadWASM from './mkbitmap.js';
const run = async () => {
const Module = await loadWASM();
const buffer = await fetch('https://example.com/example.bmp').then((res) => res.arrayBuffer());
Module.FS.writeFile('example.bmp', new Uint8Array(buffer));
Module.callMain(['example.bmp']);
const output = Module.FS.readFile('example.pbm', { encoding: 'binary' });
const file = new File([output], 'example.pbm', {
type: 'image/x-portable-bitmap',
});
const a = document.createElement('a');
a.href = URL.createObjectURL(file);
a.download = file.name;
a.click();
};
run();
インタラクティブな UI を追加する
ここまでは、入力ファイルはハードコードされ、mkbitmap はデフォルトのパラメータで実行されます。最後のステップでは、ユーザーが入力ファイルを動的に選択し、mkbitmap パラメータを調整して、選択したオプションでツールを実行できるようにします。
// Corresponds to `mkbitmap -o output.pbm input.bmp -s 8 -3 -f 4 -t 0.45`.
Module.callMain(['-o', 'output.pbm', 'input.bmp', '-s', '8', '-3', '-f', '4', '-t', '0.45']);
PBM 画像形式は解析が特に難しいわけではないため、JavaScript コードを使って出力画像のプレビューを表示することもできます。方法の一つについては、以下の埋め込みデモのソースコードをご覧ください。
まとめ
これで、mkbitmap を WebAssembly にコンパイルし、ブラウザで動作させることができました。行き詰まりがあり、動作するまでツールを複数回コンパイルする必要がありましたが、上記に書いたように、それは経験の一部です。行き詰まった場合は、StackOverflow の webassembly タグも参照してください。コンパイルをお楽しみください。
謝辞
この記事は、Sam Clegg と Rachel Andrew が確認しました。