WebAssembly Standalone

By default emcc creates a combination of JS files and WebAssembly, where the JS loads the WebAssembly which contains the compiled code. This is necessary in many cases as WebAssembly currently depends on a JavaScript runtime for features like longjmp, C++ exceptions, check the date or time, as well as to print to the console or use an API like WebGL. However, if your WebAssembly only contains pure computational code, it may require almost no JavaScript - perhaps just a little loading code. In that case, the WebAssembly may be essentially standalone - useful and usable by itself, without deep dependencies on a JavaScript runtime. In that case, you can either use the loading code from emcc or you can write your own.

There are two main ways to generate such standalone WebAssembly from Emscripten: letting the optimizer remove the runtime, or creating a dynamic library. We'll go over each on this page.

Note: You will still need a little JavaScript to load the WebAssembly, at least on the Web and with current APIs.

Let the optimizer remove the runtime

As of 1.37.29, emcc's optimizer is powerful enough to remove all runtime elements that are not used (it does this using meta-dce, dead code elimination that crosses the JavaScript/WebAssembly boundary). To try this, simply build with something like

emcc source.cpp -Os -s WASM=1

-Os is needed to make the optimizer work at full power (you can also use -Oz or -O3). The result will be two files, JavaScript and WebAssembly as usual. You can then inspect the WebAssembly file and see what it imports: if you are only doing pure computation, it should import little or nothing, in which case it is easy to write your own loading code to use it.

Create a dynamic library

Dynamic libraries have a formal definition, and are designed to be loadable in a standard way. That is a benefit over the previous approach, however, dynamic libraries also have downsides, such as having relocations for memory and function pointers, which add overhead that may be unnecessary if you are only using one module (and not linking several together).

To build a dynamic library, use

emcc source.cpp -s WASM=1 -s SIDE_MODULE=1 -o target.wasm

That will emit the output dynamic library as target.wasm.

To use a side module, see loadWebAssemblyModule in src/runtime.js for some example loading code.

• The conventions for a wasm dynamic library are here.
• Note that there is no special handling of a C stack. A module can have one internally if it wants one (it needs to ask for the memory for it, then handle it however it wants).
• Full example.