Skip to content

emscripten.md

Latest commit

 

History

History
105 lines (68 loc) · 5.36 KB

emscripten.md

File metadata and controls

105 lines (68 loc) · 5.36 KB

Emscripten

LLVM-to-JavaScript compiler capable of targeting WebAssembly.

Installation

Emscripten has the following prerequisites:

  • Git: version control.
  • CMake: cross-platform build environment. Once installed, be sure to the environment PATH.
  • Python general purpose language (version 2.7.x).
  • Compiler toolchain, such as gcc (Linux), Xcode (Mac; version >=8.3.1), or Visual Studio 2010 (Windows).

To install the Emscripten SDK, run

$ make install-deps-emsdk

from the top-level project directory. Note that the SDK consumes considerable resources and hard-disk space, and installation times may be significant.

Commands

Compilation

To compile a source file (C/C++) to asm.js,

$ ./path/to/emsdk/emscripten/<version>/emcc -s ASM_JS=1 -O3 -s EXPORTED_FUNCTIONS="['_foo']" -s STRICT=1 --memory-init-file 0 -I ../include -o out.asm.js <file>

To compile a source file (C/C++) to WebAssembly,

$ ./path/to/emsdk/emscripten/<version>/emcc -s WASM=1 -O3 -s EXPORTED_FUNCTIONS="['_foo']" -s STRICT=1 -s BINARYEN_ASYNC_COMPILATION=0 -s "BINARYEN_METHOD='native-wasm'" -I ../include -o out.js <file>

The command options are as follows:

  • -s WASM=1: generate WebAssembly.
  • -s ASM_JS=1: generate asm.js.
  • -O0: no optimization. Suitable for initial development.
  • -O3: aggressive optimization. Note that this option increases compilation time and may lead to larger code sizes. Suitable for release.
  • --memory-init-file <on>: specifies whether to emit a memory initialization file. If 0, static initialization is inlined in the generated JavaScript. If 1, a separate file is generated for memory initialization. This file should be loaded prior to running compiled output. Note that this option only applies for asm.js. For wasm, static memory initialization data is more efficiently included within the WebAssembly binary.
  • -s EXPORTED_FUNCTIONS="['_foo','_bar']": list of exported functions. Each function should be prefixed with an underscore; e.g., foo => _foo. Functions referred to in the list are not marked for dead code elimination and will be present in the compiled output.
  • -s EXPORTED_RUNTIME_METHODS="['cwrap','setValue','getValue]": runtime methods exported on Module. Many methods are exported by default and can be safely removed from the export list.
  • -s STRICT=1: do not support deprecated build options.
  • -s NO_FILESYSTEM=1: disable bundling of filesystem support. During optimization, the compiler should remove filesystem support if the filesystem is not used, but may not always succeed.
  • -s ERROR_ON_UNDEFINED_SYMBOLS=1: generate a compile-time error upon encountering any undefined symbols.
  • -s ERROR_ON_MISSING_LIBRARIES=1: generate a linker error if any -l<lib> directives cannot be resolved.
  • -s NODEJS_CATCH_EXIT=0: disable trapping uncaught exceptions.
  • -s TOTAL_STACK=<number>: total stack size. Must be less than TOTAL_MEMORY, but large enough for program requirements.
  • -s TOTAL_MEMORY=<number>: total memory. Default: ~16MB.
  • -s ALLOW_MEMORY_GROWTH=1: enable growing memories at runtime. Enabling dynamic allocation entails a performance cost.
  • -s ABORTING_MALLOC=0: disable aborting if a memory allocation fails (e.g., due to exceeding maximum memory limits).
  • -s MODULARIZE=1: wrap compiled JavaScript code in a closure. Doing so allows delaying Module instantiation.
  • -s BINARYEN_ASYNC_COMPILATION=0: disable compiling WebAssembly asynchronously. Disabling is necessary in Node.js in order to allow synchronous Module resolution and export.
  • -s "BINARYEN_METHOD='native-wasm'": run WebAssembly natively (as opposed to via an interpreter or other means).
  • --pre-js <file>: insert file contents into the beginning of JavaScript compiled output. Useful for setting initial state and overriding internal variables.
  • --shell-file <file>: path to a skeleton HTML file for inserting generated output. The file must contain the token {{{ SCRIPT }}}.

In addition to the above flags, emcc should act as a drop-in replacement for gcc, and, thus, standard C flags should be supported.

Resources