From b69116774cd3450abd35f9c00b5336e212f33a72 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Mon, 26 Mar 2018 14:53:35 +0200 Subject: [PATCH] doc: a bit of Emscripten troubleshooting. --- doc/platforms-html5.dox | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/doc/platforms-html5.dox b/doc/platforms-html5.dox index da52612e1..8ecdb1ff5 100644 --- a/doc/platforms-html5.dox +++ b/doc/platforms-html5.dox @@ -112,6 +112,31 @@ cmake .. \ -DCMAKE_PREFIX_PATH=/usr/lib/emscripten/system/ \ -G Ninja @endcode + +@subsection platforms-html5-troubleshooting-loading-failed Application fails to load + +Depending on what's the exact error printed in the browser console, the +following scenarios are possible: + +- By default, the size of Emscripten heap is restricted to 16 MB. That might + not be enough if you have large compiled-in resources or allocate large + amount of memory. This can be solved either with: + - Adding `-s TOTAL_MEMORY=<bytes>` to compiler/linker flags, where + <bytes> is the new heap size + - Adding `-s ALLOW_MEMORY_GROWTH=1` to compiler/linker flags. This is + useful in case you don't know how much memory you need in advance and + [might disable some optimizations](https://kripken.github.io/emscripten-site/docs/optimizing/Optimizing-Code.html#memory-growth). + - Setting `Module { TOTAL_MEMORY: <bytes>; }` in the JavaScript + driver file +- Sometimes Chromium-based browsers refuse to create WebGL context on a + particular page, while on other sites it works and the same page works in + other browsers such as Firefox. This can be caused by Chromium running for + too long, restart it and try again. +- If you compile your application with a different set of compiler / linker + flags or a different Emscripten version than your dependencies, it can fail + to load for a variety of random reasons. Try to rebuild everything with the + same set of flags. + */ }