Emscriptenコンパイラフロントエンド (emcc)

Emscriptenコンパイラフロントエンド（emcc）は、コマンドラインからEmscriptenコンパイラを呼び出すために使用されます。これは、gccやclangなどの標準コンパイラのドロップイン置換として機能します。

コマンドライン構文

emcc [options] file...

(現在のディレクトリからemccを実行する場合は、./emccが必要になります。)

入力ファイルは、Clangが処理できるソースコードファイル（CまたはC++）、オブジェクトファイル（emcc -cによって生成）、またはLLVMアセンブリファイルのいずれかです。

引数

ほとんどのclangオプションとgccオプションが機能します。例えば

# Display this information
emcc --help

# Display compiler version information
emcc --version

Emscriptenで使用されているClangのバージョンのサポートされるClangオプションの完全なリストを表示するには、clang --helpを実行します。

emccで変更または追加されたオプションを以下に示します。

-O0

[コンパイル+リンク] 最適化なし（デフォルト）。これは、さまざまなアサーションが含まれているため、プロジェクトの移植を開始するための推奨設定です。

この最適化設定とその他の最適化設定は、コンパイル時とリンク時の両方で意味を持ちます。コンパイル時にはLLVMの最適化に影響し、リンク時にはBinaryenでのコードの最終的な最適化とJSの最適化にも影響します。（高速な増分ビルドには-O0が最適ですが、リリースビルドにはそれ以上のレベルでリンクする必要があります。）

-O1

[コンパイル+リンク] 単純な最適化。コンパイルステップでは、LLVM -O1最適化が含まれます。リンクステップでは、-O0で行うJSのさまざまなランタイムアサーションは含まれません。

-O2

[コンパイル+リンク] -O1と同様ですが、より多くの最適化が有効になります。リンク時には、さまざまなJavaScript最適化も有効になります。

注記

これらのJavaScript最適化により、コンパイラが使用されていないと認識しているものを削除することでコードサイズを削減できます。特に、Moduleオブジェクトにエクスポートされていない場合は、ランタイムの一部が削除される可能性があります。コンパイラは–pre-jsと–post-jsのコードを認識しているため、そこから安全にランタイムを使用できます。あるいは、EXPORTED_RUNTIME_METHODSを使用することもできます。src/settings.jsを参照してください。

-O3

[コンパイル+リンク] -O2と同様ですが、実行時間が長くなる可能性のある追加の最適化が含まれています。

注記

これはリリースビルドに適した設定です。

-Og

[コンパイル+リンク] -O1と同様です。将来のバージョンでは、デバッグ可能性を向上させるために、このオプションで異なる最適化が無効になる可能性があります。

-Os

[コンパイル+リンク] -O3と同様ですが、コードサイズに重点を置いています（速度とのトレードオフを行う場合があります）。これはWasmとJavaScriptの両方に影響を与える可能性があります。

-Oz

[コンパイル+リンク] -Osと同様ですが、コードサイズをさらに削減し、実行時間が長くなる可能性があります。これはWasmとJavaScriptの両方に影響を与える可能性があります。

注記

コードの最適化に関するその他のヒントについては、コードの最適化を参照してください。

-sOPTION[=VALUE]

[異なるOPTIONは異なる段階で影響を与え、ほとんどはリンク時に影響を与えます] Emscriptenビルドオプション。使用可能なオプションについては、src/settings.jsを参照してください。

注記

値を指定しない場合、1がデフォルトになります。

注記

ブール値のオプションでは、NO_プレフィックスを使用して意味を反転させることができます。例えば、-sEXIT_RUNTIME=0は-sNO_EXIT_RUNTIME=1と同じであり、その逆も同様です。これはほとんどの場合推奨されません。

注記

リストはカンマ区切りの文字列として指定できます。

-sEXPORTED_FUNCTIONS=foo,bar

注記

より多くの引用符を含む古いリスト形式もサポートしています。リストは、各要素の周りに引用符を付けるか、付けないか、リストの周りにブラケットを付けるか、付けないかを選択して指定できます。例えば、以下のすべては同等です。

-sEXPORTED_FUNCTIONS="foo","bar"
-sEXPORTED_FUNCTIONS=["foo","bar"]
-sEXPORTED_FUNCTIONS=[foo,bar]

注記

ブラケットまたは引用符を含むリストの場合、ほとんどのシェルではリストの周りに引用符（”）が必要です（エラーが発生するのを防ぐため）。2つの例を以下に示します。

-sEXPORTED_FUNCTIONS="['liblib.so']"
-s"EXPORTED_FUNCTIONS=['liblib.so']"

オプションの値をファイルから読み込むように指定することもできます。例えば、以下は**path/to/file**のファイルの内容に基づいてEXPORTED_FUNCTIONSを設定します。

-sEXPORTED_FUNCTIONS=@/path/to/file

注記

  • この場合、ファイルにはシンボルの一覧が1行ずつ含まれている必要があります。レガシーのユースケースでは、JSON形式のファイルもサポートされます。例：["_func1", "func2"]。

  • 指定されたファイルパスは絶対パスでなければならず、相対パスではありません。

  • ファイルには、行の先頭文字が'#'であるコメントを含めることができます。

注記

オプションは、-sとオプション名の間にスペースを入れるか入れないかを選択して、単一の引数として指定できます。例：-sFOOまたは-s FOO。スペースを入れない表記法を使用することを強くお勧めします。

-g

[コンパイル+リンク] デバッグ情報を保持します。

  • オブジェクトファイルにコンパイルする場合、これはClangとgccと同じで、オブジェクトファイルにDWARFデバッグ情報が追加されます。

  • リンクする場合、これは-g3と同等です。

-gseparate-dwarf[=FILENAME]

[コンパイル時に渡された場合は-g3と同じ、それ以外の場合はリンク時に適用されます] デバッグ情報を保持しますが、別々のファイルに保存します。これは-gと同じですが、メインファイルにはデバッグ情報は含まれません。代わりに、デバッグ情報は、指定されている場合はFILENAMEに、指定されていない場合はWasmファイルと同じですがサフィックス.debug.wasmのファイルに存在します。メインファイルにはデバッグ情報は含まれていませんが、デバッグファイルの場所を示すURLが含まれているため、開発者ツールで検出できます。-sSEPARATE_DWARF_URL=URLを使用して、その場所をカスタマイズできます（例えば、別のサーバーでホストする場合に便利です）。

-gsplit-dwarf

デバッグフィッションを有効にします。これにより、wasmオブジェクトファイルとともに分割されたDWARFオブジェクトファイルが作成されます。このオプションは-cと一緒に使用する必要があります。

-gsource-map

[リンク] LLVMデバッグ情報を使用してソースマップを生成します（オブジェクトファイルに存在する必要があります。つまり、-gでコンパイルされている必要があります）。このオプションが指定されている場合、.wasmファイルはsourceMappingURLセクションを持つように更新されます。結果のURLの形式は次のようになります。<base-url> + <wasm-file-name> + .map。<base-url>はデフォルトで空です（つまり、ソースマップはWasmファイルと同じディレクトリから提供されます）。–source-map-baseを使用して変更できます。

-g<level>

[コンパイル+リンク] デバッグレベルを制御します。各レベルは前のレベルを基に構築されます。

  • -g0: デバッグ可能なコードを維持するための努力を一切行いません。

  • -g1: リンク時に、JavaScript内の空白文字を保持します。

  • -g2: リンク時に、コンパイル済みコード内の関数名を保持します。

  • -g3: オブジェクトファイルへのコンパイル時に、JSの空白文字、関数名、LLVMデバッグ情報（DWARF）（存在する場合）を含むデバッグ情報を保持します（これは-gと同じです）。

--profiling

[コンパイル時に渡された場合は-g2と同じ、それ以外の場合はリンク時に適用] プロファイリングに役立つように、JavaScriptを出力する際に妥当なデフォルト値を使用し、ビルドを読みやすくします。これにより-g2（空白文字と関数名を保持）が設定され、パフォーマンスに影響を与える可能性のある最適化も有効になる場合があります（-g2では実行されない可能性があります）。

--profiling-funcs

[リンク] プロファイリングでは関数名を保持しますが、最適化されたビルドで通常行うように、空白文字と名前は最小化します。これは、関数名に基づいてプロファイラ結果を確認したいが、出力されたコードを読むつもりがない場合に役立ちます。

--tracing

[リンク] Emscripten Tracing APIを有効にします。

--reproduce=<file.tar>

[コンパイル+リンク] 呼び出しを再現するための入力とコマンドを含むtarファイルを書き込みます。このファイルを共有する際には、コンパイラに渡されたオブジェクトファイル、ソースファイル、ライブラリが含まれていることに注意してください。

--emit-symbol-map

[リンク] Wasmの関数インデックスと関数名の間のマップファイルを保存します。名前を別途ファイルに保存することで、名前の配布を避け、インデックスを名前に戻して意味のあるスタックトレースを再構築できます。

注記

-sWASM=2と共に使用すると、2つのシンボルファイルが作成されます。[name].js.symbols（WASMシンボル付き）と[name].wasm.js.symbols（ASM.jsシンボル付き）

--emit-minification-map <file>

[リンク] Emscriptenがインポート/エクスポートの縮小を行う場合、このオプションを使用して、縮小された名前を元の名前に戻すマップを出力するファイルを使用できます。このファイルの形式は、<minname>:<origname>の形式のインポート/エクスポートごとに1行です。

-flto

[コンパイル+リンク] リンク時最適化（LTO）を有効にします。

--closure 0|1|2

[リンク] Closure Compilerを実行します。可能な値は

  • 0: Closureコンパイラを使用しません（-O2以下ではデフォルト）。

  • 1: Closureコンパイラを実行します。これにより、サポートJavaScriptコード（WebAssemblyまたはasm.js以外のすべて）のサイズが大幅に削減されます。ただし、コンパイル時間が大幅に増加することに注意してください。

  • 2: **asm.js**モードで**asm.js**出力を含め、出力されたすべてのコードに対してClosureコンパイラを実行します。これによりコードサイズをさらに削減できますが、多くの**asm.js**最適化を妨げるため、コードサイズを何としても削減したい場合を除き、推奨されません。

注記

  • Closureを使用する場合は、-sMODULARIZEを使用することを検討してください。これは、グローバル変数をグローバルスコープ内の他の変数と競合する可能性のある名前に縮小します。MODULARIZEは、すべての出力を関数に入れます（src/settings.jsを参照）。

  • Closureは、デフォルトでModule自体の名前を縮小します！MODULARIZEを使用すると、それも解決されます。別の解決策としては、Closureでコンパイルされたコードの実行前にModuleというグローバル変数が既に存在するようにすることです。そうすれば、その変数が再利用されます。

  • Closureは、JavaScriptオプションが実行されている場合のみ実行されます（-O2以上）。

--closure-args=<args>

[リンク] Closure Compilerに引数を渡します。これはEMCC_CLOSURE_ARGSの代替手段です。

たとえば、--pre-jsまたは--post-jsファイルで定義されているJS関数の縮小を避けるために、externファイルを渡したい場合があります。externs.jsファイル（縮小してはならない公開APIを含む）をClosureに渡すには、次のフラグを追加します。--closure-args=--externs=path/to/externs.js

--pre-js <file>

[リンク] 出力されたコードの前に追加され、それと共に最適化されるファイルの内容を指定します。MODULARIZEが使用されている場合など、これはJS出力の最初のものとは限りません（src/settings.jsを参照）。それが必要な場合は、Emscriptenからの出力を単純に追加できます。--pre-jsの利点は、Emscriptenの出力の残りとコードを最適化できることであり、より優れたデッドコードの削除と縮小が可能です。そして、その目的でのみ使用されるべきです。特に、--pre-jsコードは、最適化を混乱させる可能性のある方法（--pre-js + --post-jsを使用してすべての出力を内部関数スコープに入れるなど）（MODULARIZEを参照）でEmscriptenからのメイン出力を変更するべきではありません。

–pre-js（–post-jsではない）は、Moduleオブジェクトにものを指定する場合にも役立ちます。これは、JSがModuleを参照する前に表示されるためです（たとえば、そこでModule['print']を定義できます）。

--post-js <file>

[リンク]--pre-jsに似ていますが、出力されたコードの後にファイルを生成します。

--extern-pre-js <file>

[リンク] 内容がJavaScript出力の先頭に追加されるファイルを指定します。このファイルは、最適化、オプションのMODULARIZE化、SAFE_HEAPなどのインストルメンテーションなど、他のすべての作業が完了した後に、最終的なJavaScript出力に追加されます。これは、emccの実行が完了した後にこのファイルを追加することと同じであり、単にそれを実行するための便利な方法です。（比較として、--pre-jsと--post-jsは、他のすべてとコードを一緒に最適化し、MODULARIZEを実行している場合は同じスコープに保持しますなど）。

--extern-post-js <file>

[リンク]--extern-pre-jsに似ていますが、最後に追加します。

--embed-file <file>

[リンク] 生成されたWebAssemblyモジュール内に埋め込むファイル（パス付き）を指定します。パスは、コンパイル時の現在のディレクトリを基準とした相対パスです。ここにディレクトリが渡された場合、その内容はすべて埋め込まれます。

たとえば、コマンドに--embed-file dir/file.datが含まれている場合、dir/file.datは、emccを実行したディレクトリを基準とした相対パスで存在する必要があります。

注記

ファイルの埋め込みは、一般的に実行時にファイルデータのコピーを回避するため、プリロードよりも効率的です。

--embed-fileオプションの詳細については、ファイルのパッケージ化を参照してください。

--preload-file <name>

[リンク] コンパイル済みコードを非同期に実行する前にプリロードするファイルを指定します。パスは、コンパイル時の現在のディレクトリを基準とした相対パスです。ここにディレクトリが渡された場合、その内容はすべて埋め込まれます。

プリロードされたファイルは、**filename.data**に格納されます。ここで、**filename.html**はコンパイル先のメインファイルです。コードを実行するには、**.html**と**.data**の両方が必要です。

注記

このオプションは–embed-fileに似ていますが、HTMLを生成する場合（非同期バイナリXHRを使用する）、またはWebページで使用されるJavaScriptの場合にのみ関連します。

emccは、埋め込みファイルとプリロードファイルの実際のパッケージ化を行うためにtools/file_packagerを実行します。必要に応じてファイルパッケージャーを自分で実行できます（ファイルパッケージャーツールを使用したパッケージ化を参照）。その後、ファイルパッケージャーの出力をemccの--pre-jsに配置して、メインのコンパイル済みコードの前に実行する必要があります。

--preload-fileオプションの詳細については、ファイルのパッケージ化を参照してください。

--exclude-file <name>

[リンク]–embed-fileと–preload-fileから除外するファイルとディレクトリ。ワイルドカード（*）がサポートされています。

--use-preload-plugins

[リンク] ファイルパッケージャーに、ファイルのロード時にプリロードプラグインを実行するように指示します。これにより、ブラウザのコーデックを使用して画像やオーディオのデコードなどのタスクを実行します。

--shell-file <path>

[リンク] HTML出力を生成する場合に使用されるスケルトンHTMLファイルのパス名。使用するシェルファイルには、{{{ SCRIPT }}}というトークンが含まれている必要があります。

注記

  • src/shell.htmlとsrc/shell_minimal.htmlに例があります。

  • -o オプションを使用してHTML以外のターゲットを指定した場合、この引数は無視されます。

--source-map-base <base-url>

[link] WebAssemblyソースマップが公開される場所のベースURLです。-gsource-map と共に使用しなければなりません。

--minify 0

[コンパイル時に渡された場合は-g1と同じ、それ以外の場合はリンク時に適用] -g1 と同じです。

--js-transform <cmd>

[link] 生成されたコードが最適化される前に呼び出される<cmd>を指定します。これにより、JavaScriptを変更することができます（例：コードの追加または削除）。これらの変更は、生成されたコードと共に最適化されます。

生成されたコードのファイル名がパラメーターとして<cmd>に渡されます。コードを変更するには、元のデータを読み取り、それに追加するか、変更されたデータで上書きします。

<cmd>は、スペースで区切られた引数のリストとして解釈されます。たとえば、<cmd>が**python processor.py**の場合、Pythonスクリプトが実行されます。

--bind

[link] embindライブラリにリンクします。非推奨：代わりに-lembindを使用してください。

--embind-emit-tsd <path>

[link] TypeScript定義ファイルを生成します。非推奨：代わりに--emit-tsdを使用してください。

--emit-tsd <path>

[link] EmscriptenモジュールのTypeScript定義ファイルを生成します。定義ファイルには、エクスポートされたWasm関数、ランタイムエクスポート、およびエクスポートされたembindバインディング（使用されている場合）が含まれます。embindからバインディングを生成するには、プログラムがインストルメント化され、node.jsで実行されます。

--ignore-dynamic-linking

[link] コンパイラに動的リンクを無視するように指示します（ユーザーは後で共有ライブラリを手動でリンクする必要があります）。

通常、emccは動的ライブラリのコードを静的にリンクされたかのようにリンクしますが、同じ動的ライブラリが複数回リンクされている場合は失敗します。このオプションを使用すると、動的リンクが無視されるため、ビルドシステムはエラーなしで続行できます。

--js-library <lib>

[link] Emscriptenのコアライブラリ（src/library_*）に追加して使用するJavaScriptライブラリです。

-v

[general] 詳細出力を有効にします。

これにより、Emscriptenによって実行される内部サブコマンドと、Clangへの-vが出力されます。

ヒント

emcc -vは、エラーの診断に役立つツールです。他の引数があってもなくても動作します。

--check

[general] Emscriptenの内部健全性チェックを実行し、現在の構成に関する問題を報告します。

--cache <directory>

[general] Emscriptenキャッシュとして使用するディレクトリを設定します。Emscriptenキャッシュは、libc、libcxx、その他のライブラリの事前にビルドされたバージョンを保存するために使用されます。

--clear-cacheと組み合わせて使用する場合は、この引数を先に指定してください。

Emscriptenキャッシュはデフォルトでemscripten/cacheですが、EM_CACHE環境変数またはCACHE設定を使用してオーバーライドできます。

--clear-cache

[general] コンパイル済みのEmscriptenシステムライブラリ（libc++、libc++abi、libc）のキャッシュを手動でクリアします。

これは通常自動的に処理されますが、LLVMをインプレースで更新する（新しいバージョンの異なるディレクトリを持たない）場合、キャッシングメカニズムが混乱する可能性があります。キャッシュをクリアすると、キャッシュの互換性の問題に関連する奇妙な問題（Clangがライブラリファイルとのリンクに失敗するなど）を解決できます。これにより、その他のキャッシュされたデータもクリアされます。キャッシュがクリアされると、このプロセスは終了します。

デフォルトでは、ポートディレクトリは通常キャッシュディレクトリ内にあるため、ダウンロードされたポートもクリアされます。

--use-port=<port>

[compile+link] 指定されたポートを使用します。複数のポートを使用する必要がある場合は、このオプションを複数回使用できます（例：--use-port=sdl2 --use-port=bzip2）。ポートには、:で区切られたオプションを含めることができます（例：--use-port=sdl2_image:formats=png,jpg）。外部ポートを使用するには、ポートへのパスを直接指定します（例：--use-port=/path/to/my_port.py）。ポートの詳細については、helpオプションを使用します（例：--use-port=sdl2_image:help）。使用可能なポートのリストを取得するには、--show-portsを使用します。

--clear-ports

[general] Emscripten Portsリポジトリ（sdl2など）からポートのローカルコピーを手動でクリアします。これにより、ビルドを削除するためにキャッシュもクリアされます。

これは、問題が発生し、使用するすべてのポートを最初からダウンロードしてビルドする必要がある場合にのみ必要です。この操作が完了すると、このプロセスは終了します。

--show-ports

[general] Emscripten Portsリポジトリで使用可能なプロジェクトのリストを表示します。この操作が完了すると、このプロセスは終了します。

-Wwarn-absolute-paths

[compile+link] -Iおよび-Lコマンドラインディレクティブでの絶対パスの使用に関する警告を有効にします。これは、意図しない絶対パスの使用（移植性のないローカルシステムヘッダーを参照する場合など、危険な場合がある）について警告するために使用されます。

--proxy-to-worker

[link] メインアプリケーションコードをワーカーで実行し、イベントと出力をプロキシします。HTMLを出力する場合、**.html**ファイルと、ワーカーで実行されるJavaScriptを含む別の**.js**ファイルが出力されます。JavaScriptを出力する場合、ターゲットファイル名にはメインスレッドで実行される部分が含まれ、サフィックス“.worker.js”が付いた2番目の**.js**ファイルにはワーカー部分が含まれます。

--emrun

[link] 生成された出力がemrunコマンドラインツールを認識できるようにします。これにより、生成されたアプリケーションをemrunで実行したときにstdout、stderr、exit(returncode)をキャプチャできます。（これによりEXIT_RUNTIME=1が有効になり、リターンコードの受け渡しによる通常のランタイムの終了が可能になります。）

--cpuprofiler

[link] 生成されたページにシンプルなCPUプロファイラを埋め込みます。これを使用して、概要的な対話型のパフォーマンスプロファイリングを実行します。

--memoryprofiler

[link] 生成されたページにメモリ割り当てトラッカーを埋め込みます。これを使用して、Emscripten HEAPのアプリケーション使用状況をプロファイリングします。

--threadprofiler

[link] 生成されたページにスレッドアクティビティプロファイラを埋め込みます。マルチスレッドビルド（-pthread）を対象とする場合、これを使用してpthreadsのアプリケーション使用状況をプロファイリングします。

--em-config <path>

[general] **.emscripten**設定ファイルの場所を指定します。指定しない場合、Emscriptenは最初にEmscriptenディレクトリ自体、次にユーザーのホームディレクトリ(~/.emscripten)で.emscriptenを検索します。これはEM_CONFIG環境変数を使用してオーバーライドできます。

--valid-abspath <path>

[compile+link] 許可された絶対パスをメモします。これについては警告しません（絶対インクルードパスは通常警告されます。クロスコンパイル時に避ける必要があるローカルシステムヘッダーなどを参照する場合があるためです）。

-o <target>

[link] 実行可能ファイルをリンクする場合、targetファイル名の拡張子は、生成する出力の種類を定義します。

  • <name> .js : JavaScript（WebAssemblyを出力する場合は、別々の<name>.wasmファイル）。（デフォルト）

  • <name> .mjs : ES6 JavaScriptモジュール（WebAssemblyを出力する場合は、別々の<name>.wasmファイル）。

  • <name> .html : HTMLと別のJavaScriptファイル（<name>.js；WebAssemblyを出力する場合は、別々の<name>.wasmファイル）。

  • <name> .wasm : JavaScriptサポートコードのないWebAssembly（「スタンドアロンWasm」；これによりSTANDALONE_WASMが有効になります）。

これらの規則は、リンク時のみ適用されます。オブジェクトコードにコンパイルする場合（下記の-cを参照）、出力ファイルの名前は関係ありません。

-c

[compile] emccに、他のオブジェクトファイルとリンクして実行可能ファイルを作成できるオブジェクトファイルを出力するように指示します。

--output_eol windows|linux

[link] 出力されるテキストファイルの改行コードを指定します。“–output_eol windows”が渡された場合、最終的な出力ファイルにはWindowsのrn改行コードが含まれます。“–output_eol linux”の場合、最終的に生成されたファイルにはUnixのn改行コードが書き込まれます。

--cflags

[other] ソースコードをオブジェクト形式にコンパイルするためにemccがclangに渡すフラグを出力します。これを使用してclangを自分で呼び出し、最終的なリンクとJSへの変換のためにemccをそれらの出力で実行することができます。

環境変数

emccは、以下に示すように、いくつかの環境変数の影響を受けます。

  • EMMAKEN_JUST_CONFIGURE [other]

  • EMCC_AUTODEBUG [compile+link]

  • EMCC_CFLAGS [compile+link]

  • EMCC_CORES [general]

  • EMCC_DEBUG [general]

  • EMCC_DEBUG_SAVE [general]

  • EMCC_FORCE_STDLIBS [link]

  • EMCC_ONLY_FORCED_STDLIBS [link]

  • EMCC_LOCAL_PORTS [compile+link]

  • EMCC_STDERR_FILE [general]

  • EMCC_CLOSURE_ARGS [link] Closure Compilerに渡される引数

  • EMCC_STRICT [general]

  • EMCC_SKIP_SANITY_CHECK [一般]

  • EM_IGNORE_SANITY [一般]

  • EM_CONFIG [一般]

  • EM_LLVM_ROOT [コンパイル＋リンク]

  • _EMCC_CCACHE [一般] emsdkがccacheコンパイラフロントエンドと統合する際に1に設定される内部設定です。

これらの使用方法については、emcc.pyで「os.environ」を検索してください。最も興味深いのはおそらくEMCC_DEBUGで、これによりコンパイラはビルドと一時ファイルを一時ディレクトリにダンプし、確認できるようになります。