Debugging web info, using wasmtime

htdocs/doc/web.adoc

@@ -89,7 +89,7 @@ So far, file-size tests are promising. Compilation of https://github.com/castle-
 +
 The gzipped size is really what matters — both web browsers and servers support gzip-(de)compression on the fly, you can also just put ready-gzipped version on the server and tell the browser to just decompress. So in all practical cases, users will download 3.4 MB, not 16 MB.
 +
-Note that above is for a _release_ build. The _debug_ build weights 51 MB, and gzipped 12 MB. How is the debug build actually useful on the web — I am not certain now :)
+Note that above is for a _release_ build. The _debug_ build weights 51 MB, and gzipped 12 MB. (Debug build contains https://wiki.freepascal.org/WebAssembly/Debugging[debugging symbols].)
 +
 We could also use https://en.wikipedia.org/wiki/Brotli[Brotli], a newer compression method also commonly supported by web browsers and servers.
 
@@ -170,8 +170,42 @@ Currently, the project executes, printing logs (using our cgeref:CastleLog[]) to
 
 == TODO: How to continue
 
-- Investigate next `Exception class:  object , message: indirect call to null` from `platformer.wasm` error cause.
-- Then make the rendering work, by routing calls to WebGL on the web.
+- The current code fails at `glGetString(GL_VERSION)`, because OpenGLES routines are `nil`, we eliminated other causes. So the situation is clear, making the rendering work using WebGL will eliminate this.
++
+```
+$ export WASMTIME_BACKTRACE_DETAILS=1
+$ wasmtime castle-engine-output/web/dist/platformer.wasm
+Log for "platformer".
+  Version: 1.5.1.
+  Started on 2024-11-17 at 01:01:31.
+  Castle Game Engine version: 7.0-alpha.3.snapshot.
+  Compiled with FPC 3.3.1.
+  Platform: Desktop, OS: Wasi, CPU: wasm32 (code compiled for 32-bit architecture).
+Error: failed to run main module `castle-engine-output/web/dist/platformer.wasm`
+
+Caused by:
+    0: failed to invoke command default
+    1: error while executing at wasm backtrace:
+           0: 0x81296e - GLINFORMATIONINITIALIZE
+                           at /home/michalis/sources/castle-engine/castle-engine/examples/platformer/../../src/base_rendering/castleglutils_features.inc:590:37
+           1: 0xa7ee3 - OPENUNPROTECTED
+                           at /home/michalis/sources/castle-engine/castle-engine/examples/platformer/../../src/window/castlewindow.pas:2667:5
+           2: 0xa793c - OPENCORE
+                           at /home/michalis/sources/castle-engine/castle-engine/examples/platformer/../../src/window/castlewindow.pas:2745:7
+           3: 0xa8587 - OPEN
+                           at /home/michalis/sources/castle-engine/castle-engine/examples/platformer/../../src/window/castlewindow.pas:2755:5
+           4: 0xa8732 - OPEN
+                           at /home/michalis/sources/castle-engine/castle-engine/examples/platformer/../../src/window/castlewindow.pas:2798:3
+           5: 0xab9fa - OPENANDRUN
+                           at /home/michalis/sources/castle-engine/castle-engine/examples/platformer/../../src/window/castlewindow.pas:3408:3
+           6: 0x261c8 - main
+                           at /home/michalis/sources/castle-engine/castle-engine/examples/platformer/platformer_standalone.dpr:69:3
+           7: 0x26104 - platformer_standalone.wasm!SI_PRC_$$__START_PASCAL
+           8: 0x260ed - platformer_standalone.wasm!SI_PRC_$$__START
+    2: wasm trap: uninitialized element
+```
+
+- Make the rendering work, by routing calls to WebGL on the web.
 +
 --
 - We could use WebGL from Pasj2s (see `pas2js/packages/rtl/src/webgl.pas` and pasj2s demos using it). We can make these calls available to our WebAssembly code (using canvas example from Pas2js and explanation from https://www.freepascal.org/~michael/articles/fpcwasm1/fpcwasm1.pdf how to expose JS functionality to WebAssembly).
@@ -188,6 +222,29 @@ Currently, the project executes, printing logs (using our cgeref:CastleLog[]) to
 - Then finish the plans in "How" section above: data from zip, sound, automatic webserver, etc.
 - _Trung Le (Kagamma)_ has been doing lots of work with CGE + FPC WebAssembly. His fork contains a branch https://github.com/Kagamma/castle-engine/tree/wasm32-wasi-port[wasm32-wasi-port]. Merge and/or cherry-pick this work to CGE as needed. Thank you!
 
+== Running WASM code outside of the browser
+
+_WebAssembly_ is not limited to running in a web browser. We support running the compiled WASM binaries also using https://wasmtime.dev/[Wasmtime]. Just run then like this on the command-line:
+
+```
+export WASMTIME_BACKTRACE_DETAILS=1 # get a more detailed backtrace
+wasmtime <project-name>.wasm
+```
+
+The WASM file is in the project top-level directory if you compiled using
+
+```
+castle-engine compile --os=wasi --cpu=wasm32 --mode=debug
+```
+
+or inside `castle-engine-output/web/dist/` if you compiled using
+
+```shell
+castle-engine compile -web=target --mode=debug
+```
+
+The main use-case of this is additional https://wiki.freepascal.org/WebAssembly/Debugging[debugging] approach. In case of a crash, the `wasmtime` will give you a useful stack trace with line numbers (if only you compiled with `--mode=debug`, as shown above).
+
 == Thank you
 
 I want to thank everyone involved in this and let's push forward! Web target is a really cool feature, from my talks I know it's an important feature for many CGE users, and I feel we have it in our reach. Let's keep coding and enjoy making games :)