From 17e309d25bc943ddf9d331b157cb43939f0cf0e9 Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Thu, 15 Feb 2024 16:41:36 -0500
Subject: [PATCH] Fix reST in users guide
It appears that aef587f65de642142c1dcba0335a301711aab951 wasn't valid syntax.
---
docs/users_guide/javascript.rst | 13 ++++++++-----
1 file changed, 8 insertions(+), 5 deletions(-)
diff --git a/docs/users_guide/javascript.rst b/docs/users_guide/javascript.rst
index 90039cecc95d..d21a187d0be0 100644
--- a/docs/users_guide/javascript.rst
+++ b/docs/users_guide/javascript.rst
@@ -157,7 +157,7 @@ passed as an ``Int`` to a ``Callback`` that accepts a ``JSVal``:
releaseCallback add3
Callbacks as Foreign Exports
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
JavaScript callbacks allow for a sort of FFI exports via FFI imports. To do
this, a global JavaScript variable is set, and that global variable can then
@@ -331,7 +331,7 @@ Next, the JavaScript ``h$getcwd`` function demonstrates several details:
in the error case.
Writing JavaScript Functions to be NodeJS and Browser Aware
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In the above example of implementing ``getcwd``, the function we use in the JavaScript
implementation is from NodeJS, and the behaviour doesn't make sense to implement in a
@@ -434,7 +434,7 @@ C functions compiled with Emscripten get a "_" prepended to their name in
JavaScript. For example, C "malloc" becomes "_malloc" in JavaScript.
EMCC pragmas
-~~~~~~~~~~~~
+^^^^^^^^^^^^
By default the EMCC linker drops code considered dead and it has no way to know
which code is alive due to some call from Haskell or from a JavaScript wrapper.
@@ -470,16 +470,19 @@ passed once; the latter argument overrides the former ones).
This pragma allows additional options to be passed to Emscripten if need be. We
already pass:
+
- `-sSINGLE_FILE=1`: required to create a single `.js` file as artefact
(otherwise `.wasm` files corresponding to C codes need to be present in the
current working directory when invoking the resulting `.js` file).
+
- `-sALLOW_TABLE_GROWTH`: required to support `addFunction`
+
- `-sEXPORTED_RUNTIME_METHODS` and `-sEXPORTED_FUNCTIONS`: see above.
Be careful because some extra arguments may break the build in unsuspected ways.
Wrappers
-~~~~~~~~
+^^^^^^^^
The JavaScript backend doesn't generate wrappers for foreign imports to call
directly into the compiled C code. I.e. given the following foreign import:
@@ -513,7 +516,7 @@ GHC's JavaScript rts provides helper functions for this in `rts/js/mem.js`. See
`h$copyFromHeap`, `h$copyToHeap`, `h$initHeapBuffer`, etc.
Callbacks
-~~~~~~~~~
+^^^^^^^^^
Some C functions take function pointers as arguments (e.g. callbacks). This is
supported by the JavaScript backend but requires some work from the wrapper
--
GitLab