summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authordoyougnu <jeffrey.young@iohk.io>2023-01-26 15:01:11 -0500
committerMarge Bot <ben+marge-bot@smart-cactus.org>2023-02-15 00:16:39 -0500
commit08c0822c74eb97ea8a6673c6a942d9c03a169bc8 (patch)
treebda5f478c86e3f7c9abfbaac0111e62719fc3649
parent3b019a7ac8fc9059cc3213f6f95a2daef97ca442 (diff)
downloadhaskell-08c0822c74eb97ea8a6673c6a942d9c03a169bc8.tar.gz
docs: release notes, user guide: add js backend
Follow up from #21078
-rw-r--r--docs/users_guide/9.6.1-notes.rst9
-rw-r--r--docs/users_guide/codegens.rst30
2 files changed, 39 insertions, 0 deletions
diff --git a/docs/users_guide/9.6.1-notes.rst b/docs/users_guide/9.6.1-notes.rst
index 36067df41c..256e3f1aca 100644
--- a/docs/users_guide/9.6.1-notes.rst
+++ b/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`.
diff --git a/docs/users_guide/codegens.rst b/docs/users_guide/codegens.rst
index 993806b1a2..84dad3f968 100644
--- a/docs/users_guide/codegens.rst
+++ b/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