From 3bf17ffa786ecd5fde10c721a09324020b9c64a0 Mon Sep 17 00:00:00 2001 From: Javier Chavarri Date: Sat, 15 Oct 2022 18:43:34 +0000 Subject: [PATCH] docs: document experimental melange support In particular, the new "melange" mode introduced for libraries. Signed-off-by: Javier Chavarri --- doc/dune-files.rst | 7 ++--- doc/index.rst | 1 + doc/jsoo.rst | 6 ++--- doc/melange.rst | 66 ++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 74 insertions(+), 6 deletions(-) create mode 100644 doc/melange.rst diff --git a/doc/dune-files.rst b/doc/dune-files.rst index b859e88aef3..d2bee50e07b 100644 --- a/doc/dune-files.rst +++ b/doc/dune-files.rst @@ -586,9 +586,10 @@ to use the :ref:`include_subdirs` stanza. - ``(modes )`` is for modes which should be built by default. The most common use for this feature is to disable native compilation - when writing libraries for the OCaml toplevel. The following modes - are available: ``byte``, ``native``, and ``best``. ``best`` is - ``native`` or ``byte`` when native compilation isn't available. + when writing libraries for the OCaml toplevel. It can also be used to define + libraries that should be compiled with Melange (see :ref:`melange_main`). The + following modes are available: ``byte``, ``native``, ``best``, and ``melange``. + ``best`` is ``native`` or ``byte`` when native compilation isn't available. - ``(no_dynlink)`` disables dynamic linking of the library. This is for advanced use only. By default, you shouldn't set this option. diff --git a/doc/index.rst b/doc/index.rst index 2c372673f49..41cdfe53b35 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -19,6 +19,7 @@ Welcome to Dune's Documentation! foreign-code documentation jsoo + melange sites opam variants diff --git a/doc/jsoo.rst b/doc/jsoo.rst index efd6e01921e..04dd535b5f2 100644 --- a/doc/jsoo.rst +++ b/doc/jsoo.rst @@ -1,8 +1,8 @@ .. _jsoo: -********************** -JavaScript Compilation -********************** +*************************************** +JavaScript Compilation With Js_of_ocaml +*************************************** 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: diff --git a/doc/melange.rst b/doc/melange.rst new file mode 100644 index 00000000000..917228309cf --- /dev/null +++ b/doc/melange.rst @@ -0,0 +1,66 @@ +.. _melange_main: + +*********************************** +JavaScript Compilation With Melange +*********************************** + +`Melange `_ is a compiler from OCaml to +JavaScript. Unlike js_of_ocaml, Melange works by translating OCaml compiler +internal lambda representation to JS files. This allows to produce a single +JavaScript file from each OCaml module. Melange can be installed with +`opam, Esy, or Nix `_ package +managers. + +Compiling to JS +=============== + +Dune has experimental support for building Melange libraries. To use it, you +must declare the ``melange`` extension in your ``dune-project`` file: + +.. code:: scheme + + (lang dune 3.5) + (using melange 0.1) + +Then, given this example: + +.. code:: bash + + echo 'Js.log "hello from melange"' > foo.ml + +With the following ``dune`` file: + +.. code:: scheme + + (library (name foo) (modes melange)) + +One can then request the ``.js`` target: + +.. code:: bash + + $ dune build .foo.objs/melange/foo.js + $ node _build/default/.foo.objs/melange/foo.js + hello from melange + +At the moment, executable targets are not supported, but using explicit +targets inside libraries as shown above should enable similar results. + +Faster Builds with ``subdir`` and ``dirs`` Stanzas +================================================== + +Melange libraries are commonly installed from the ``npm`` package repository, +together with other JavaScript packages. To avoid having Dune inspect +unnecessary folders in ``node_modules``, it is recommended to explicitly +include those folders that are relevant for Melange builds. + +This can be accomplished by combining :ref:`subdir` and :ref:`dune-subdirs` +stanzas in a ``dune`` file and by co-locating this file together with the +``node_modules`` folder. The :ref:`dune-vendored_dirs` stanza can be used as +well to avoid warnings in Melange libraries during the application build. + +.. code:: scheme + + (subdir + node_modules + (vendored_dirs reason-react) + (dirs reason-react))