WebAssembly is a binary format for executing code on the web, allowing fast start times (smaller download and much faster parsing in browsers when compared to JS or asm.js). Emscripten compiles to WebAssembly by default, but you can also compile to JS for older browsers.
For some historical background, see
WebAssembly is emitted by default, without the need for any special flags.
If you don’t want WebAssembly, you can disable it with something like
emcc [..args..] -s WASM=0
Emscripten’s WebAssembly support depends on Binaryen, which is provided by the emsdk (if you don’t use the emsdk, you need to build it and set it up in your
Deciding to compile to wasm or JS can be done at the linking stage: it doesn’t affect the object files.
Emscripten emits WebAssembly using the upstream LLVM wasm backend, since
1.39.0 (October 2019). Previously emscripten also supported the
old fastcomp backend which was removed in
2.0.0 (August 2020).
There are some differences you may notice between the two backends, if you upgrade from fastcomp to upstream:
WASM=0behaves differently in the two backends. In fastcomp we emit asm.js, while in upstream we emit JS (since not all wasm constructs can be expressed in asm.js). Also, the JS support implements the same external
WebAssembly.*API, so in particular startup will be async just like wasm by default, and you can control that with
DISABLE_EXCEPTION_CATCHING. Such flags must be passed during codegen. The simple and safe thing is to pass all
-sflags at both compile and link time.
-flto=thin, at both compile and link times). These flags will make the wasm backend behave more like fastcomp.
--llvm-lto 1. With the llvm backend LTO passes will be run on any object files that are in bitcode format.
RESERVED_FUNCTION_POINTERSsetting exists there to work around the fact that we can’t grow the table. In the upstream backend table growth is easy, and you can just enable
float unrepresentable in integer range,
integer result unrepresentable,
integer overflow, or
Out of bounds Trunc operation.
The LLVM wasm backend avoids traps by adding more code around each possible trap (basically clamping the value if it would trap). This can increase code size and decrease speed, if you don’t need that extra code. The proper solution for this is to use newer wasm instructions that do not trap, by calling emcc or clang with
-mnontrapping-fptoint. That code may not run in older VMs, though.
emcc to build to WebAssembly, you will see a
.wasm file containing that code, as well as the usual
.js file that is the main target of compilation. Those two are built to work together: run the
.html, if that’s what you asked for) file, and it will load and set up the WebAssembly code for you, properly setting up imports and exports for it, etc. Basically, you don’t need to care about whether the compiled code is asm.js or WebAssembly, it’s just a compiler flag, and otherwise everything should just work (except the WebAssembly should be faster).
.wasmfile is not standalone - it’s not easy to manually run it without that
.jscode, as it depends on getting the proper imports that integrate with JS. For example, it receives imports for syscalls so that it can do things like print to the console. There is work in progress towards ways to create standalone
.wasmfiles, see the WebAssembly Standalone page.
You may also see additional files generated, like a
.data file if you are preloading files into the virtual filesystem. All that is exactly the same as when building to asm.js. One difference you may notice is the lack of a
.mem file, which for asm.js contains the static memory initialization data, which in WebAssembly we can pack more efficiently into the WebAssembly binary itself.
.wasmfiles and compilation¶
WebAssembly code is prepared somewhat differently than asm.js. asm.js can be bundled inside the main JS file, while as mentioned earlier WebAssembly is a binary file on the side, so you will have more than one file to distribute.
Another noticeable effect is that WebAssembly is compiled asynchronously by default, which means you must wait for compilation to complete before calling compiled code (by waiting for
main(), or the
onRuntimeInitialized callback, etc., which you also need to do when you have anything else that makes startup async, like a
.mem file for asm.js, or preloaded file data, etc.). You can turn off async compilation by setting
WASM_ASYNC_COMPILATION=0, but that may not work in Chrome due to current limitations there.
Module['wasmBinary']and it will be used from there, and then (with async compilation off) compilation should be synchronous.
To serve wasm in the most efficient way over the network, make sure your web server has the proper MIME time for
.wasm files, which is application/wasm. That will allow streaming compilation, where the browser can start to compile code as it downloads.
In Apache, you can do this with
AddType application/wasm .wasm
Also make sure that gzip is enabled:
AddOutputFilterByType DEFLATE application/wasm
If you serve large
.wasm files, the webserver will consume CPU compressing them on the fly at each request.
Instead you can pre-compress them to
.wasm.gz and use content negotiation:
Options Multiviews RemoveType .gz AddEncoding x-gzip .gz AddType application/wasm .wasm