Merge pull request #1064 from rgrinberg/jsoo-manual
Move Jsoo content to its own page
This commit is contained in:
commit
ad0b376aeb
|
@ -1231,22 +1231,8 @@ follows:
|
|||
js_of_ocaml
|
||||
-----------
|
||||
|
||||
In ``library`` and ``executables`` stanzas, you can specify js_of_ocaml options
|
||||
using ``(js_of_ocaml (<js_of_ocaml-options>))``.
|
||||
|
||||
``<js_of_ocaml-options>`` are all optional:
|
||||
|
||||
- ``(flags <flags>)`` to specify flags passed to ``js_of_ocaml``. This field
|
||||
supports ``(:include ...)`` forms
|
||||
|
||||
- ``(javascript_files (<files-list>))`` to specify ``js_of_ocaml`` JavaScript
|
||||
runtime files.
|
||||
|
||||
``<flags>`` is specified in the `Ordered set language`_.
|
||||
|
||||
The default value for ``(flags ...)`` depends on the selected build
|
||||
profile. The build profile ``dev`` (the default) will enable sourcemap
|
||||
and the pretty JavaScript output.
|
||||
A :ref:`dune-jsoo-field` exists in executable and libraries stanzas that allows
|
||||
one to customize options relevant to jsoo.
|
||||
|
||||
.. _user-actions:
|
||||
|
||||
|
|
|
@ -20,6 +20,7 @@ Welcome to dune's documentation!
|
|||
advanced-topics
|
||||
configurator
|
||||
menhir
|
||||
jsoo
|
||||
faq
|
||||
known-issues
|
||||
migration
|
||||
|
|
|
@ -0,0 +1,83 @@
|
|||
***********
|
||||
js_of_ocaml
|
||||
***********
|
||||
|
||||
js_of_ocaml_ is a compiler from OCaml to JavaScript. The compiler works by
|
||||
translating OCaml bytecode to JS files. From here on, we'll abbreviate
|
||||
js_of_ocaml to jsoo. The compiler can be installed with opam:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ opam install js_of_ocaml-compiler
|
||||
|
||||
Compiling to JS
|
||||
===============
|
||||
|
||||
Dune has full support building jsoo 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:: bash
|
||||
|
||||
echo 'print_endline "hello from js"' > foo.ml
|
||||
|
||||
With the following dune file:
|
||||
|
||||
.. code:: scheme
|
||||
|
||||
(executable (name foo))
|
||||
|
||||
And then request the ``.js`` target:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ 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.
|
||||
|
||||
.. _dune-jsoo-field:
|
||||
|
||||
``js_of_ocaml`` field
|
||||
=====================
|
||||
|
||||
In ``library`` and ``executables`` stanzas, you can specify js_of_ocaml options
|
||||
using ``(js_of_ocaml (<js_of_ocaml-options>))``.
|
||||
|
||||
``<js_of_ocaml-options>`` are all optional:
|
||||
|
||||
- ``(flags <flags>)`` to specify flags passed to ``js_of_ocaml``. This field
|
||||
supports ``(:include ...)`` forms
|
||||
|
||||
- ``(javascript_files (<files-list>))`` to specify ``js_of_ocaml`` JavaScript
|
||||
runtime files.
|
||||
|
||||
``<flags>`` is specified in the `Ordered set language`_.
|
||||
|
||||
The default value for ``(flags ...)`` depends on the selected build profile. The
|
||||
build profile ``dev`` (the default) will enable sourcemap and the pretty
|
||||
JavaScript output.
|
||||
|
||||
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. There is currently no other way to control this
|
||||
behaviour.
|
||||
|
||||
.. _js_of_ocaml: http://ocsigen.org/js_of_ocaml/
|
|
@ -431,29 +431,6 @@ For rare cases where this is not what you want, you can force dune to use a
|
|||
different build contexts for merlin by adding the field ``(merlin)`` to this
|
||||
context.
|
||||
|
||||
Building JavaScript with js_of_ocaml
|
||||
====================================
|
||||
|
||||
Dune knows how to generate a JavaScript version of an executable
|
||||
(``<name>.bc.js``) using the js_of_ocaml compiler (the ``js_of_ocaml-compiler``
|
||||
opam package must be installed).
|
||||
|
||||
It 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. There is currently no other way to control this
|
||||
behaviour.
|
||||
|
||||
See the section about :ref:`dune-jsoo` for passing custom flags to the
|
||||
js_of_ocaml compiler
|
||||
|
||||
Distributing Projects
|
||||
=====================
|
||||
|
||||
|
|
Loading…
Reference in New Issue