unikernel/duniverse/dune_/doc/jsoo.rst

@@ -0,0 +1,86 @@
+.. _jsoo:
+
+***************************************
+JavaScript Compilation With Js_of_ocaml
+***************************************
+
+.. TODO(diataxis)
+
+   This is an how-to guide.
+
+Js_of_ocaml_ is a compiler from OCaml to JavaScript. The compiler works by
+translating OCaml bytecode to JS files. The compiler can be installed with opam:
+
+.. code:: console
+
+   $ opam install js_of_ocaml-compiler
+
+Compiling to JS
+===============
+
+Dune has full support building js_of_ocaml libraries and executables transparently.
+There's no need to customize or enable anything to compile OCaml
+libraries/executables to JS.
+
+To build a JS executable, just define an executable as you would normally.
+Consider this example:
+
+.. code:: console
+
+   $ echo 'print_endline "hello from js"' > foo.ml
+
+With the following ``dune`` file:
+
+.. code:: dune
+
+  (executable (name foo) (modes js))
+
+And then request the ``.js`` target:
+
+.. code:: console
+
+   $ dune build ./foo.bc.js
+   $ node _build/default/foo.bc.js
+   hello from js
+
+Similar targets are created for libraries, but we recommend sticking to the
+executable targets.
+
+If you're using the js_of_ocaml syntax extension, you must remember to add the
+appropriate PPX in the ``preprocess`` field:
+
+.. code:: dune
+
+  (executable
+   (name foo)
+   (modes js)
+   (preprocess (pps js_of_ocaml-ppx)))
+
+Separate Compilation
+====================
+
+Dune supports two modes of compilation:
+
+- Direct compilation of a bytecode program to JavaScript. This mode allows
+  js_of_ocaml to perform whole-program deadcode elimination and whole-program
+  inlining.
+
+- Separate compilation, where compilation units are compiled to JavaScript
+  separately and then linked together. This mode is useful during development as
+  it builds more quickly.
+
+The separate compilation mode will be selected when the build profile
+is ``dev``, which is the default. It can also be explicitly specified
+in an ``env`` stanza (see :doc:`/reference/dune/env`) or per executable
+inside ``(js_of_ocaml (compilation_mode ...))`` (see :doc:`/reference/dune/executable`)
+
+Sourcemap
+=========
+
+Js_of_ocaml can generate sourcemap for the generated JavaScript file.
+It can either embed it at the end of the ``.js`` file or write it to separate file.
+By default, it is inlined when using the ``dev`` build profile and is not generated otherwise.
+The behavior can explicitly be specified in an ``env`` stanza (see :doc:`/reference/dune/env`)
+or per executable inside ``(js_of_ocaml (sourcemap ...))`` (see :doc:`/reference/dune/executable`)
+
+.. _js_of_ocaml: http://ocsigen.org/js_of_ocaml/