87 lines
2.5 KiB
ReStructuredText
87 lines
2.5 KiB
ReStructuredText
|
.. _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/
|