Updated documentation

Signed-off-by: Jérôme Vouillon <[email protected]>

doc/reference/dune/env.rst

@@ -51,9 +51,22 @@ Fields supported in ``<settings>`` are:
 - ``(js_of_ocaml (runtest_alias <alias-name>))`` specifies the alias under which
   :ref:`inline_tests` and tests (:ref:`tests-stanza`) run for the `js` mode.
 
-- ``(js_of_ocaml (submodes <submodes>))`` controls whether to generate
-  JavaScript, Wasm code, or both. Each submode is either ``js`` or ``wasm``.
-  The default is to generate JavaScript code.
+- ``(js_of_ocaml (enabled_if <blang expression>))`` specifies whether the `js` mode is enabled. It is enabled by default.
+
+- ``(wasm_of_ocaml (flags <flags>)(build_runtime <flags>)(link_flags <flags>))``
+  specifies ``wasm_of_ocaml`` flags. See :ref:`wasmoo-field` for more details.
+
+- ``(wasm_of_ocaml (compilation_mode <mode>))`` controls whether to use separate
+  compilation or not where ``<mode>`` is either ``whole_program`` or
+  ``separate``.
+
+- ``(wasm_of_ocaml (sourcemap <mode>))`` controls whether to generate sourcemap
+  or not where ``<mode>`` is either ``no``, ``file`` (to generate sourcemap in a ``.map`` file next the the generated javascript file) or ``inline`` (to inline the sourcemap at the end of the generated JavaScript file).
+
+- ``(wasm_of_ocaml (runtest_alias <alias-name>))`` specifies the alias under which
+  :ref:`inline_tests` and tests (:ref:`tests-stanza`) run for the `wasm` mode.
+
+- ``(wasm_of_ocaml (enabled_if <blang expression>))`` specifies whether the `wasm` mode is enabled. It is enabled by default.
 
 - ``(binaries <binaries>)``, where ``<binaries>`` is a list of entries of the
   form ``(<filepath> as <name>)``. ``(<filepath> as <name>)`` makes the binary

doc/reference/dune/executable.rst

@@ -15,13 +15,13 @@ There can be additional modules in the current directory; you only need to
 specify the entry point. Given an ``executable`` stanza with ``(name <name>)``,
 Dune will know how to build ``<name>.exe``. If requested, it will also know how
 to build ``<name>.bc``, ``<name>.bc.js`` and ``<name>.bc.wasm.js`` (Dune 2.0
-and up also need specific configuration (see the ``modes`` optional field
+and up also needs specific configuration (see the ``modes`` optional field
 below)).
 
 ``<name>.exe`` is a native code executable, ``<name>.bc`` is a bytecode
 executable which requires ``ocamlrun`` to run, ``<name>.bc.js`` is a
 JavaScript generated using ``js_of_ocaml``, and ``<name>.bc.wasm.js`` is a
-Wasm loader generated using ``wasm_of_ocaml`` (the Wasm modules are included in
+Wasm loader script generated using ``wasm_of_ocaml`` (the Wasm modules are included in
 directory ``<name>.bc.wasm.assets``).
 
 Please note: in case native compilation is not available, ``<name>.exe`` will be
@@ -94,6 +94,8 @@ files for executables. See
 
 - ``js_of_ocaml``: See the section about :ref:`jsoo-field`
 
+- ``wasm_of_ocaml``: See the section about :ref:`wasmoo-field`
+
 - ``flags``, ``ocamlc_flags``, and ``ocamlopt_flags``: See
   :doc:`/concepts/ocaml-flags`.
 
@@ -168,6 +170,7 @@ available.
   non-OCaml application.
 - ``js`` for producing JavaScript from bytecode executables, see
   :doc:`/reference/dune-project/explicit_js_mode`.
+- ``wasm`` for producing JavaScript from bytecode executables.
 - ``plugin`` for producing a plugin (``.cmxs`` if native or ``.cma`` if
   bytecode).
 
@@ -189,6 +192,7 @@ Additionally, you can use the following shorthands:
 - ``byte`` for ``(byte exe)``
 - ``native`` for ``(native exe)``
 - ``js`` for ``(byte js)``
+- ``wasm`` for ``(byte wasm)``
 - ``plugin`` for ``(best plugin)``
 
 For instance, the following ``modes`` fields are all equivalent:
@@ -218,8 +222,8 @@ The extensions for the various linking modes are chosen as follows:
 .. (byte shared_object)        .bc%{ext_dll}
 .. (native/best shared_object) %{ext_dll}
 .. c                           .bc.c
-.. js                          .bc.js (JavaScript)
-.. js                          .bc.wasm.js (Wasm)
+.. js                          .bc.js
+.. wasm                        .bc.wasm.js
 .. (best plugin)               %{ext_plugin}
 .. (byte plugin)               .cma
 .. (native plugin)             .cmxs
@@ -237,10 +241,6 @@ linking mode that's the same as ``byte_complete``, but it uses the extension
 currently tracked by Dune, so they don't run ``.bc`` files during the build. Run
 the ``.bc.exe`` or ``.exe`` ones instead, as these are self-contained.
 
-When compiling to Wasm but not to JavaScript, a ``.bc.js`` file can
-also be produced for compatibility. It is just a copy of the
-``bc.wasm.js`` file.
-
 Lastly, note that ``.bc`` executables cannot contain C stubs. If your executable
 contains C stubs you may want to use ``(modes exe)``.
 
@@ -266,27 +266,44 @@ options using ``(js_of_ocaml (<js_of_ocaml-options>))``.
 - ``(javascript_files (<files-list>))`` to specify ``js_of_ocaml`` JavaScript
   runtime files.
 
-- ``(wasm_files (<files-list>))`` to specify ``wasm_of_ocaml``
-  JavaScript and Wasm runtime files.
-
 - ``(compilation_mode <mode>)`` where ``<mode>>`` is either ``whole_program`` or ``separate``.
   This is only available inside ``executable`` stanzas.
 
 - ``(sourcemap <config>)`` where ``<config>>`` is one of ``no``, ``file`` or ``inline``.
   This is only available inside ``executable`` stanzas.
 
-- ``(submodes <submodes>)`` controls whether to generate
-  JavaScript or Wasm code. Each submode is either ``js`` or ``wasm``.
-  The default is taken from the environment.
+- ``(enabled_if <blang expression>)`` to specify whether the `js` mode is enabled. It is enabled by default.
+  This is only available inside ``executable`` stanzas.
 
 ``<flags>`` is specified in the :doc:`/reference/ordered-set-language`.
+``<blang expression>`` is specified using the :doc:`/reference/boolean-language`,
 
 The default values for ``flags``, ``compilation_mode`` and ``sourcemap`` depend on the selected build profile. The
 build profile ``dev`` (the default) will enable inline sourcemap, separate compilation and pretty
 JavaScript output.
 
 See :ref:`jsoo` for more information.
 
+.. _wasmoo-field:
+
+wasm_of_ocaml
+~~~~~~~~~~~
+
+In ``library`` and ``executable`` stanzas, you can specify ``wasm_of_ocaml``
+options using ``(wasm_of_ocaml (<wasm_of_ocaml-options>))``.
+
+``<wasm_of_ocaml-options>`` are all optional. They are the same as the ``<js_of_ocaml-options>`` above plus:
+
+- ``(wasm_files (<files-list>))`` to specify ``wasm_of_ocaml``
+  Wasm runtime files.
+
+For the ``(sourcemap <config>)`` option, source maps are generated when ``<config>>`` is either ``file`` or ``inline``. They are put within the ``.bc.wasm.assets``  directory in both cases.
+
+The default values for ``flags``, ``compilation_mode`` and ``sourcemap`` depend on the selected build profile. The
+build profile ``dev`` (the default) will enable sourcemaps, separate compilation and pretty Wasm output.
+
+See :ref:`wasmoo` for more information.
+
 executables
 -----------
 

doc/reference/dune/library.rst

@@ -213,6 +213,10 @@ order to declare a multi-directory library, you need to use the
 
    Sets options for JavaScript compilation, see :ref:`jsoo-field`.
 
+.. describe:: (wasm_of_ocaml ...)
+
+   Sets options for JavaScript compilation, see :ref:`wasmoo-field`.
+
 .. describe:: (flags ...)
 
    See :doc:`/concepts/ocaml-flags`.

doc/tests.rst

@@ -258,14 +258,15 @@ field. Available modes are:
 - ``best`` for running tests in native mode with fallback to byte code,
   if native compilation is not available
 - ``js`` for running tests in JavaScript using Node.js
+- ``wasm`` for running tests in Wasm using Node.js
 
 For instance:
 
 .. code:: ocaml
 
    (library
     (name foo)
-    (inline_tests (modes byte best js))
+    (inline_tests (modes byte best js wasm))
     (preprocess (pps ppx_expect)))
 
 

doc/wasmoo.rst

@@ -11,9 +11,6 @@ Wasm Compilation With Wasm_of_ocaml
 Wasm_of_ocaml_ is a compiler from OCaml to WebAssembly (Wasm for
 short). The compiler works by translating OCaml bytecode to Wasm code.
 
-Compiling to Wasm is very similar to compiling to JavaScript. See
-:doc:`jsoo` for more information.
-
 
 Compiling to Wasm
 =================
@@ -33,7 +30,7 @@ With the following ``dune`` file:
 
 .. code:: dune
 
-  (executable (name foo) (modes js) (js_of_ocaml (submodes wasm)))
+  (executable (name foo) (modes wasm))
 
 And then request the ``.wasm.js`` target:
 
@@ -43,4 +40,60 @@ And then request the ``.wasm.js`` target:
    $ node _build/default/foo.bc.wasm.js
    hello from wasm
 
+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 wasm)
+   (preprocess (pps js_of_ocaml-ppx)))
+
+Selective Compilation
+=====================
+
+The ``js`` and ``wasm`` modes can be selectively disabled using the ``(js_of_ocaml (enabled_if ...))`` and ``(wasm_of_ocaml (enabled_if ...))`` options. This allows for instance to generate one, or the other dependings on a profile:
+
+.. code:: dune
+
+  (env
+   (js-only (wasm_of_ocaml (enabled_if false)))
+   (wasm-only (js_of_ocaml (enabled_if false))))
+
+To be able to invoke the generated code using the same JavaScript script name in all cases, you can add a rule to copy the Wasm launcher script when the js_of_ocaml compilation is disabled.
+
+.. code:: dune
+
+  (rule
+   (action (copy foo.bc.wasm.js foo.bc.js))
+   (enabled_if (= %{profile} wasm-only)))
+
+
+Separate Compilation
+====================
+
+Dune supports two modes of compilation:
+
+- Direct compilation of a bytecode program to Wasm. This mode allows
+  wasm_of_ocaml to perform whole-program deadcode elimination and whole-program
+  inlining.
+
+- Separate compilation, where compilation units are compiled to Wasm
+  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 ``(wasm_of_ocaml (compilation_mode ...))`` (see :doc:`/reference/dune/executable`)
+
+Sourcemap
+=========
+
+Wasm_of_ocaml can generate sourcemaps for the generated Wasm code.
+By default, they are generated when using the ``dev`` build profile and are not generated otherwise.
+The behavior can explicitly be specified in an ``env`` stanza (see :doc:`/reference/dune/env`)
+or per executable inside ``(wasm_of_ocaml (sourcemap ...))`` (see :doc:`/reference/dune/executable`)
+
 .. _wasm_of_ocaml: https://github.com/ocaml-wasm/wasm_of_ocaml