[Git][ghc/ghc][master] docs: release notes, user guide: add js backend

[Marge Bot (@marge-bot)]

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


Commits:
08c0822c by doyougnu at 2023-02-15T00:16:39-05:00
docs: release notes, user guide: add js backend

Follow up from #21078

- - - - -


2 changed files:

- docs/users_guide/9.6.1-notes.rst
- docs/users_guide/codegens.rst


Changes:

=====================================
docs/users_guide/9.6.1-notes.rst
=====================================
@@ -132,6 +132,15 @@ Compiler
     presented in this GHC version as a technology preview, bugs and
     missing features are expected.
 
+- The JavaScript backend has been merged. GHC is now able to be built as a
+  cross-compiler targeting the JavaScript platform. The backend should be
+  considered a technology preview. As such it is not ready for use in
+  production, is not distributed in the GHC release bindists and requires the
+  user to manually build GHC as a cross-compiler. See the JavaScript backend
+  `wiki <https://gitlab.haskell.org/ghc/ghc/-/wikis/javascript-backend>`_ page
+  on the GHC wiki for the current status, project roadmap, build instructions
+  and demos.
+
 - The :extension:`TypeInType` is now marked as deprecated. Its meaning has been included
   in :extension:`PolyKinds` and :extension:`DataKinds`.
 


=====================================
docs/users_guide/codegens.rst
=====================================
@@ -95,6 +95,36 @@ was built this way. If it has then the native code generator probably
 won't be available. You can check this information by calling
 ``ghc --info`` (see :ghc-flag:`--info`).
 
+.. _javascript-code-gen:
+
+JavaScript Code Generator
+------------------------------
+
+.. index::
+   single: JavaScript code generator
+
+This is an alternative code generator included in GHC 9.6 and above. It
+generates `ECMA-262 <https://tc39.es/ecma262/>`_ compliant JavaScript and is
+included as a technical preview. At time of writing, it is being actively
+developed but is not suitable for serious projects and production environments.
+The JavaScript backend is not distributed in the GHC bindist and requires a
+manual build. See `building the JavaScript backend
+<https://gitlab.haskell.org/ghc/ghc/-/wikis/javascript-backend/building>`_ page
+on the GHC wiki for build instructions.
+
+A JavaScript cross-compiling GHC produces an executable script, and a directory
+of the same name suffixed with ``.jsexe``. For example, compiling a file named
+``Foo.hs`` will produce an executable script ``Foo`` and a ``Foo.jsexe``
+directory. The script is a thin wrapper that calls `Node.js
+<https://nodejs.org/en/>`_ on the payload of the compiled Haskell code and can
+be run in the usual way, e.g., ``./Foo``, as long as ``node`` is in your
+environment . The actual payload is in ``<ModuleName>.jsexe/all.js``, for
+example ``Foo.jsexe/all.js``. This file is the Haskell program cross-compiled to
+JavaScript *concrete syntax* and can be wrapped in a ``<script>`` HTML tag. For
+a breakdown of the rest of the build artifacts see the `compiler output
+<https://gitlab.haskell.org/ghc/ghc/-/wikis/javascript-backend/building#compiler-output-and-build-artifacts>`_
+section in the wiki.
+
 .. _unreg:
 
 Unregisterised compilation



View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/08c0822c74eb97ea8a6673c6a942d9c03a169bc8

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/08c0822c74eb97ea8a6673c6a942d9c03a169bc8
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/20230215/9d5d63d4/attachment-0001.html>