開発者ガイド¶

この記事は、Emscriptenへの貢献を希望する方にとって関連性の高い情報を提供しています。ご協力いただける方からの貢献を歓迎しています！

ヒント

Emscriptenを使用するだけの場合、この情報はそれほど関連性はありませんが、それでも興味深い可能性があります。

設定¶

emcc.pyなど、Emscriptenコアコードへの貢献には、emcc.pyがPythonで記述されており、コアJS生成がJavaScriptで行われているため、バイナリをビルドする必要はありません。ただし、LLVMとBinaryenのバイナリは必要であり、emsdkを使用して取得できます。

emsdk install tot
emsdk activate tot

これにより、Emscriptenを実行するために必要な最新の「tip-of-tree」バイナリがインストールされます。これらのemsdk提供のバイナリをEmscriptenリポジトリのgitチェックアウトで使用できます。これを行うには、ローカルの.emscripten設定ファイルの編集、または環境変数EM_CONFIG=/path/to/emsdk/.emscriptenの設定のいずれかを行うことができます。

LLVMまたはBinaryenに貢献したい場合、またはそれらに対する変更をテストしたい場合は、ソースからビルドすることができます。

パッチの提出¶

パッチは、通常の方法でGitHubでプルリクエストとして提出する必要があります。

パッチを提出する際には、以下の点にご注意ください。

新しい機能を追加したり、バグを修正したりする場合は、自動テストを追加してください。test/*.pyで関連するテストを検索してください。多くの場合、既存のテストに追加するのが最も簡単な方法です。コードのテスト方法がわからない場合は、お気軽にお問い合わせください。
.clang-formatで指定されているコーディングスタイルに注意してください。
通常、PRは圧縮してマージします。つまり、PRはターゲットブランチで単一のコミットになります。そのため、PR自体にマージコミットがあっても問題ありません（削除されます）。PRの説明に最終コミットの良い説明を入れてください。圧縮時にそれを使用します。

コードレビュー¶

コア開発者の1人が、プルリクエストをマージする前にレビューします。数日経ってもPRにコメントがない場合は、PRにコメントして開発者に通知してください。（そのようなことがあった場合は申し訳ありません！時々、見逃してしまうことがあります。）

コンパイラの概要¶

Emscriptenコンパイラフロントエンド（emcc）は、コンパイルプロセス全体を管理するPythonスクリプトです。

**emcc**は、C++のコンパイルにClangを、リンクにwasm-ldを呼び出します。コンパイル済みライブラリとJSで実装されたライブラリの両方を含むEmscriptenシステムライブラリをビルドして統合します。
次に、**emcc**はemscripten.pyを呼び出し、最終的なWasmへの変換（Binaryenの**wasm-emscripten-finalize**の呼び出しを含む）を実行し、JSコンパイラを呼び出します（src/compiler.mjsおよび関連ファイルを参照）。
Wasmを最適化する場合は、**emcc**は**wasm-opt**を呼び出し、メタDCE、その他便利な処理を実行します。また、Wasmとともに生成されたJSについてもJS最適化を実行します。

Emscriptenテストスイート¶

Emscriptenには、包括的なテストスイートがあり、事実上すべてのEmscripten機能をカバーしています。これらのテストは、プルリクエストを作成するときにCIで自動的に実行され、すべて合格する必要があります。テストの失敗を修正できない場合は、開発者に知らせてください。

バイセクション¶

回帰が見つかった場合、バイセクションは問題を特定する最も速い方法です。これは、Emscripten自体の実際の回帰を見つける場合だけでなく、アップグレード時にプロジェクトが動作しなくなった場合で、Emscriptenの回帰なのか、その他何かを調査する必要がある場合にも当てはまります。このセクションの残りの部分では、Emscripten自体のバイセクションについて説明します。Emscriptenを使用する人、Emscripten開発者の両方にとって役立つことを願っています。

バイセクション範囲が大きい場合（たとえば、複数のEmscriptenバージョンをカバーする場合）は、おそらく複数のリポジトリ（Emscripten、LLVM、Binaryen）にまたがる変更があります。その場合、最も簡単で速い方法は、**emsdkビルド**を使用してバイセクションを行うことです。バイセクションの各ステップで、emscriptenリリースビルダーによって生成されたビルドがダウンロードされます。この方法を使用すると、自分で何もコンパイルする必要がないため、非常に高速になります！

これを行うには、Emscriptenのリリースプロセスの基本的な理解が必要です。重要な考え方は、

emsdk install [HASH]

過去の任意の時点からのEmscriptenビルドをインストールできます（ビルドが成功した場合）。各ビルドはハッシュ（数字と文字の長い文字列）で識別され、これはreleasesリポジトリのコミットのハッシュです。Emscriptenリリース番号とこのようなハッシュのマッピングは、emsdkリポジトリのemscripten-releases-tags.jsonで追跡されています。

その背景を踏まえ、バイセクションプロセスは以下のようになります。

バイセクションを行うハッシュを見つけます。totビルドで問題を発見した場合、既に知っている可能性があります。Emscriptenのバージョン番号しかわからない場合は、emscripten-releases-tags.jsonを使用してハッシュを見つけます。
これらのハッシュを使用して、emscripten-releasesリポジトリで通常のgit bisectを実行します。
バイセクションの各ステップで、(バイセクション対象のemscripten-releasesリポジトリにある)現在のコミットハッシュのバイナリビルドをemsdk install HASHを使用してダウンロードします。次に、コードをテストし、それに応じてgit bisect goodまたはgit bisect badを実行し、最初のバッドコミットが見つかるまでバイセクションを続けます。

最初のバッドコミットは、releasesリポジトリの単一の変更です。そのコミットは通常、1つまたは複数の新しい変更を追加するために、単一のサブ・リポジトリ（Emscripten、LLVM、またはBinaryen）を更新します。多くの場合、そのリストは非常に短いか、あるいは単一のコミットでさえあり、問題の原因となった実際のコミットを確認できます。バグを報告する際には、このようなバイセクションの結果を記載すると、処理が大幅にスピードアップします（そのコミットに複数の変更が含まれている場合でも）。

そのコミットに複数の変更が含まれている場合は、必要に応じて特定のリポジトリでさらにバイセクションを行うことができます（すべての変更は通常、そのうちの1つにのみ含まれ、他のものは固定されたままです）。これを行うには、このセクションで説明したメインのバイセクションでは必要なかったローカルでの再構築が必要になります。

C構造体と定義の操作¶

JavaScriptライブラリファイルで使用されているC構造体のレイアウトを変更したり、C定義を変更したりする場合は、tools/struct_info.jsonを変更する必要がある場合があります。このファイルが変更されたり、構造体のレイアウトが変更されたりした場合は、./tools/gen_struct_info.pyを実行して、JavaScriptで使用される情報を再生成する必要があります。./tools/gen_struct_info.pyと./tools/gen_struct_info.py --wasm64の両方を実行する必要があることに注意してください。

これを忘れると、test_gen_struct_infoテストが失敗します。