GHC JS browser introduction blog post/tutorial

blog/ghc-js-browser-example/browser-example.md

@@ -0,0 +1,55 @@
+
+# GHC JavaScript Browser Example
+
+## Introduction
+
+
+## Building
+
+TODO: Can we do something with the cabal project file and/or environment variables and the with-compiler/with-hs-pkg fields to optionally specify /path/to/build/stage1/bin in the case that the user is currently building the compiler themselves, since Hadrian can't install stage 1 and prebuilt binaries are generally unavailable.
+
+## Features
+
+### Foreign Import JavaScript
+
+To access JavaScript-specific features in Haskell, we can import them via Haskell's `foreign import` syntax.
+
+In our example (in `app/Main.hs`), we have:
+```
+foreign import javascript unsafe "((html) => { return setInner(html); })"
+  setInnerHtml :: CString -> IO ()
+```
+
+Here, there are a number of details to take note of:
+- we specify the import as a string of JavaScript with _a single function call_ (TODO: Elaborate on syntax)
+- _TODO: Explain unsafe vs interruptible_
+- we must pass arguments as types from the `base` library's `Foreign.C` module - in this case `CString`
+- return types must also be `Foreign.C` types, or unit (`()`)
+
+On the JavaScript side (in `js/example.js`), we have:
+```
+function setInner(html) {
+  document.body.innerHTML = "example" + h$decodeUtf8z(html,0);
+  return;
+}
+```
+
+In this JavaScript function, we match the inputs specified in the `foreign import` declaration. However, we unfortunately have to currently use internal functions of GHC's JavaScript backend - in order to convert this `CString` (stored as a byte array) into a JavaScript string, we use `h$decodeUtf8z`.
+
+## Current Limitations
+
+### Libraries Using C FFI Imports
+
+If a function is imported via `foreign import ccall`, then that symbol will end up being referenced in the generated JavaScript, with `h$` prepended.
+
+In the example code, the `lucid-svg` library indirectly calls `bytestring`'s `cIsValidUtf8`, which imports the c symbol `bytestring_is_valid_utf8`. To work around this, we can add the missing definition in our own javascript - which we do in `js/example.js`:
+
+```
+function h$bytestring_is_valid_utf8(bs) {
+  return true;
+}
+```
+
+Although this definiton is far from ideal, it demonstrates that we can link in missing library c functions via our own implementation in our project.
+
+### TODO: Talk about the ghc-options JS source linking workaround?

blog/ghc-js-browser-example/browser-example/app/Main.hs

@@ -0,0 +1,26 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module Main where
+
+import Foreign.C.String
+import Lucid.Svg
+
+
+foreign import javascript unsafe "((html) => { return setInner(html); })"
+  setInnerHtml :: CString -> IO ()
+
+
+svg :: Svg () -> Svg ()
+svg content = do
+  doctype_
+  with (svg11_ content) [width_ "300", height_ "200"]
+
+
+image :: Svg ()
+image = rect_ [width_ "100%", height_ "100%", fill_ "red"]
+
+
+main :: IO ()
+main = do
+  setInnerHtml =<< newCString (show $ svg image)
+  print $ svg image

blog/ghc-js-browser-example/browser-example/browser-example.cabal

@@ -0,0 +1,13 @@
+cabal-version:      2.4
+name:               browser-example
+version:            0.1.0.0
+
+executable browser-example
+    main-is:          Main.hs
+
+    build-depends:    base ^>=4.17.0.0,
+                      lucid-svg,
+		      text,
+    hs-source-dirs:   app
+    ghc-options:      js/example.js
+    default-language: Haskell2010

blog/ghc-js-browser-example/browser-example/js/example.js

@@ -0,0 +1,9 @@
+
+function h$bytestring_is_valid_utf8(bs) {
+  return true;
+}
+
+function setInner(html) {
+  document.body.innerHTML = "example" + h$decodeUtf8z(html,0);
+  return;
+}