Skip to content

Commit 01897f8

Browse files
authored
Docs: Mention float/double differences between asm.js/wasm (#6872) [ci skip]
Also add a missing comma to the module doc page (fixes #6852)
1 parent 664afac commit 01897f8

File tree

2 files changed

+2
-1
lines changed

2 files changed

+2
-1
lines changed

site/source/docs/api_reference/module.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ When generating only JavaScript (as opposed to HTML), no ``Module`` object is cr
2727
::
2828

2929
var Module = {
30-
'print': function(text) { alert('stdout: ' + text) }
30+
'print': function(text) { alert('stdout: ' + text) },
3131
'printErr': function(text) { alert('stderr: ' + text) }
3232
};
3333

site/source/docs/compiling/WebAssembly.rst

+1
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,7 @@ asm.js support is considered very stable now, and you can change between it and
9797
- Timing issues - wasm might run faster or slower. To some extent you can mitigate that by building with ``-s DETERMINISTIC=1``.
9898
- Trap mode. As mentioned above, we can generate wasm that traps or that avoids traps. Make sure the trap mode is ``"js"`` when comparing builds. The ``"js"`` trap mode is also useful in a single build, as otherwise operations like division or float-to-int may trap, and the optimizer may happen to change whether a trap occurs or not, which can be confusing (for example, enabling ``SAFE_HEAP`` may prevent some optimizations, and a trap may start to occur). Instead, in the ``"js"`` trap mode there are no traps and all operations are deterministically defined as identical to JavaScript.
9999
- Minor libc and runtime differences. To eliminate any possible difference due to that, use builds that support both, i.e. use the same runtime etc. for both approaches, using e.g. ``-s "BINARYEN_METHOD='native-wasm,asmjs'"`` for a build that can do both, but defaults to wasm, and ``-s "BINARYEN_METHOD='asmjs,native-wasm'"`` for what is an identical build that does asm.js first. (In fact, since the builds are identical, you can make one and edit the native-wasm,asmjs string manually in the generated JS, to switch between asm.js and wasm.) Note: Such builds disable some optimizations, as mentioned above, so it's not a good idea in general.
100+
- Floating-point behavior: WebAssembly uses 32-bit floats in a standard way, while asm.js by default implements floats using doubles. That can lead to differences in the precision of results. You can force 32-bit float behavior in asm.js with ``-s PRECISE_F32=1``, in which case it should be identical to wasm.
100101
- Browser instability: It's worth testing multiple browsers, as one might have a wasm bug that another doesn't. You can also test the Binaryen interpreter (e.g. using the ``interpret-binary`` method, as discussed above).
101102

102103
If you find that an asm.js build has the same behavior as a wasm one, then it is currently easier to debug the asm.js build: you can edit the source easily (add debug printouts, etc.), there is debug info and source maps support, etc.

0 commit comments

Comments
 (0)