はしくれエンジニアもどきのメモ

情報系技術・哲学・デザインなどの勉強メモ・備忘録です。

emscriptenでよくみるoption-flagをまとめる

emscriptenでよくみるoption-flagをまとめる

emcc --helpしても出てこないオプション(e.g. clang由来のものとか)もあってよくわからんとなったのでメモ。

環境・事前準備

今回はDocker上にemscriptenをインストールした状況を想定してる。

  • Windows10 64bit
    • WSL2
    • DockerDesktop 4.5.1 (74721)

困ったときのコマンド

ググる前にやっとくべきコマンド

$ emcc --help | grep -- -<option-flag>

またはLLVM/clang由来のオプションもあるので

$ clang --help | grep -- -<option-flag>

grepでハイフン付きoptionやflagの文字列を検索すると、grepのオプション扱いになってしまうので注意。対処としてハイフン2つ--をつけるとkeyword argumentの終了を表し、その後がposition argumentの指定になり 検索できる。これはgrep以外のUNIXコマンドでも大抵有効なTIPSである。

ref:shell - What does "--" (double-dash) mean? - Unix & Linux Stack Exchange

emscriptenコンパイラとリンカ

emccには.cソースコードを渡すとそのまま.jsとバイナリファイルの.wasmが生成されるのでわかりにくいが、 コンパイルとリンカが動作している。

  • コンパイラ名 emcc: code emcc -c <c source> -o <object code>.o
  • リンカ名 ld.wasm : code emcc -o <output js>.js <object code>.o

ちなみにリンカはJSで読みこみ実行するための.wasmファイルも生成してる。

コンパイラ用オプションとリンカ用オプション

コンパイラ用オプションとリンカ用オプションに分けられるので分類する。

コンパイラ用オプション

 "-c": [compile] Tells *emcc* to emit an object file which can then be linked with other object files to produce an executable.

リンク前のobjectファイル(.o)を生成するのに必要なオプション。

-I<include path>, -I <include path>

includeするファイルを検索したい場所を指定する。(clang由来のオプション) カレントディレクトリを追加する場合、-I. と指定する。

-fcolor-diagnostics: Enable colors in diagnostics

Warningを表示するときに黄色になるなど診断に色付けをする

-D_FILE_OFFSET_BITS=64

64bitでも取り扱えるというオプションのはずだが詳細不明(gcc/clamg由来)

-W<warning>: Enable the specified warning
 -W<warnings>: -Wall, -Werror,  -Wno-error= -Werror=
 -w: Suppress all warnings 全警告を伏せる

警告の表示を設定する。

-O0: incremental builds "-O0" is best, while for release you should link not include various runtime assertions in JS that *-O0* would do. with -O0 or -O1 link-time optimization flags.

-O1:  include LLVM "-O1" optimizations. During the link step this does [compile+link] Like "-O1", but enables more optimizations. During with -O0 or -O1 link-time optimization flags.

コンパイラの最適化を設定

"-g":   * When linking, this is equivalent to -g3.
  "-g3": When compiling to object files, keep debug info, (DWARF) if any (this is the same as -g).

objectファイルへのコンパイル時にデバッグ情報を残すか

-MD: Write a depfile containing user and system headers
-MQ <value>: Specify name of main file output to quote in depfile
-MF <file>: Write depfile output from -MMD, -MD, -MM, or -M to <file>

依存関係をまとめたファイルdepsfile(.d)の設定をする。出力する場合は-MF <output>.dとなる。

リンカ用オプション

基本的には-s OPTION[=VALUE]で設定できる。

一覧は以下のjsファイルにある。

emscripten/settings.js at main · emscripten-core/emscripten · GitHub

-s WASM=0:
-s WASM=1:
-s WASM=2:

Whether to use compile code to WebAssembly. 
Set this to 0 to compile to "JS" instead of wasm.

Specify "-s WASM=2" to target both WebAssembly and JavaScript at the same time.
In that build mode, two files a.wasm and a.wasm.js are produced, and at runtime the WebAssembly file is loaded if browser/shell supports it. 
Otherwise the .wasm.js fallback will be used.

If WASM=2 is enabled and the browser fails to compile the WebAssembly module, the page will be reloaded in Wasm2JS mode.
  • -s WASM=0: wasmでなくJSファイルのみ
  • -s WASM=1: wasmファイルとそれを読み込んで実行してくれるJS(基本的にこれ)
  • -s WASM=2: おそらく、wasmをサポートした環境であれば1のときと同じように実行、対応してなければ0のときと同じJSのみの実行
-s EXPORT_ALL=0
-s EXPORT_ALL=1
: If true, we export all the symbols that are present in JS onto the Module object.

おそらく、出力JSの中に存在するすべてのシンボルをModule.exports()でエクスポートする。

-s ERROR_ON_UNDEFINED_SYMBOLS=0
-s ERROR_ON_UNDEFINED_SYMBOLS=1

: If set to 1, we will give a link-time error on any undefined symbols (see WARN_ON_UNDEFINED_SYMBOLS). 
To allow undefined symbols at link time set this to 0, in which case if an undefined function is called a runtime error will occur.  
Any undefined symbols that are listed in EXPORTED_FUNCTIONS will also be reported.
[link]

未定義シンボルのエラーを出すか、基本的に1でいい。