[Git][ghc/ghc][master] docs: add a section for the wasm backend

[Marge Bot (@marge-bot)]

Marge Bot pushed to branch master at Glasgow Haskell Compiler / GHC


Commits:
631c6c72 by Cheng Shao at 2023-02-16T06:43:09-05:00
docs: add a section for the wasm backend

Fixes #22658

- - - - -


2 changed files:

- docs/users_guide/index.rst
- + docs/users_guide/wasm.rst


Changes:

=====================================
docs/users_guide/index.rst
=====================================
@@ -23,6 +23,7 @@ Contents:
    hints
    utils
    win32-dlls
+   wasm
    bugs
    eventlog-formats
    editing-guide
@@ -33,4 +34,3 @@ Indices and tables
 
 * :ref:`genindex`
 * :ref:`search`
-


=====================================
docs/users_guide/wasm.rst
=====================================
@@ -0,0 +1,101 @@
+.. _wasm:
+
+Using the GHC WebAssembly backend
+=================================
+
+.. _wasm-clarify:
+
+What does the WebAssembly “backend” mean
+----------------------------------------
+
+In order to compile Haskell to wasm, you need a custom GHC build that
+targets wasm. There isn't a GHC option which allows you to use a
+stock GHC installed via ``ghcup`` or ``stack`` to generate wasm. That’s
+because GHC is still a single-target compiler, so each GHC build is only
+capable of compiling code that runs on a single architecture and operating
+system.
+
+So, the term GHC wasm backend isn’t the same sense as the
+unregisterised/LLVM/NCG backends. It merely describes GHC’s support as a
+cross compiler that targets wasm, and more specifically,
+``wasm32-wasi``.
+
+The generated wasm module makes use of a few post-MVP extensions that
+are supported by default in latest releases of
+Chrome/Firefox/Safari/`wasmtime <https://wasmtime.dev>`__. The wasm
+module uses `WASI <https://wasi.dev>`__ as the system call layer, so
+it’s supported by any wasm engine that implements WASI (including
+browsers, which can provide the WASI layer via JavaScript).
+
+.. _wasm-setup:
+
+Setting up the GHC wasm backend
+-------------------------------
+
+The wasm backend is still a tech preview and not included in the
+official bindists yet. If you are using x86_64-linux, you can follow the
+“getting started” subsections in
+`ghc-wasm-meta <https://gitlab.haskell.org/ghc/ghc-wasm-meta>`__ to
+quickly set up the GHC wasm backend using the nightly artifacts.
+
+It’s also possible to build the GHC wasm backend manually, if your host
+system is one of {x86_64,aarch64}-{linux,darwin}. Refer to the
+``ghc-wasm-meta`` readme for detailed instructions.
+
+.. _wasm-compile:
+
+Using the GHC wasm backend to compile & link code
+-------------------------------------------------
+
+Once the GHC wasm backend is set up, you can use it to compile and link
+code. The compiler executables follow the cross compiler linking
+convention, so you need to call ``wasm32-wasi-ghc``,
+``wasm32-wasi-ghc-pkg`` and ``wasm32-wasi-hsc2hs`` instead of ``ghc``,
+``ghc-pkg`` and ``hsc2hs``.
+
+You can also use the ``--with-compiler=``, ``--with-hc-pkg=`` and
+``--with-hsc2hs`` flags of ``cabal`` to build cabal projects. The
+``wasm32-wasi-cabal`` wrapper script set up by the ``ghc-wasm-meta``
+installer does this automatically for you, but using flags manually also
+works with stock ``cabal`` installations. When ``cabal`` builds an
+executable component, that executable will be built as a wasm module,
+and you can use ``cabal list-bin exe:foo`` to find the wasm module’s
+location in the build directory.
+
+.. _wasm-run:
+
+Running the GHC wasm backend’s output
+-------------------------------------
+
+Once you have a wasm module, you can run it with a dedicated wasm engine
+like ``wasmtime``, or inside the browsers.
+
+To run it with ``wasmtime``, you can simply do:
+
+.. code:: sh
+
+   $ wasmtime run foo.wasm
+
+Just like native executables, you can pass command line arguments, and
+also RTS options, as long as it’s built with ``-rtsopts``:
+
+.. code:: sh
+
+   $ wasmtime run foo.wasm --bar +RTS --nonmoving-gc -RTS
+
+You can also mount some host directory into it:
+
+.. code:: sh
+
+   $ wasmtime run --mapdir /::$PWD foo.wasm
+
+As long as the filesystem capability is provided, in addition to
+filesystem I/O in Haskell code, you can use the RTS eventlog and
+profiling functionality, then inspect the report files:
+
+.. code:: sh
+
+   $ wasmtime run --mapdir /::$PWD foo.wasm +RTS -hc -l -RTS
+
+To run the wasm module in the browsers, refer to the ``ghc-wasm-meta``
+documentation for more details.



View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/631c6c726d6ab86be1a3aa289e1468a75fb36bf6

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/631c6c726d6ab86be1a3aa289e1468a75fb36bf6
You're receiving this email because of your account on gitlab.haskell.org.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-commits/attachments/20230216/f5571668/attachment-0001.html>