From a837c52c14bb38a3d3b04dca91cca963a8dca262 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Vouillon?= Date: Tue, 5 Nov 2024 12:44:02 +0100 Subject: [PATCH] Updated documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Jérôme Vouillon --- doc/reference/dune/env.rst | 19 ++++++++-- doc/reference/dune/executable.rst | 45 ++++++++++++++++------- doc/reference/dune/library.rst | 4 ++ doc/tests.rst | 3 +- doc/wasmoo.rst | 61 +++++++++++++++++++++++++++++-- 5 files changed, 110 insertions(+), 22 deletions(-) diff --git a/doc/reference/dune/env.rst b/doc/reference/dune/env.rst index 485a1bc396b..fa9fc24a37f 100644 --- a/doc/reference/dune/env.rst +++ b/doc/reference/dune/env.rst @@ -51,9 +51,22 @@ Fields supported in ```` are: - ``(js_of_ocaml (runtest_alias ))`` specifies the alias under which :ref:`inline_tests` and tests (:ref:`tests-stanza`) run for the `js` mode. -- ``(js_of_ocaml (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 ))`` specifies whether the `js` mode is enabled. It is enabled by default. + +- ``(wasm_of_ocaml (flags )(build_runtime )(link_flags ))`` + specifies ``wasm_of_ocaml`` flags. See :ref:`wasmoo-field` for more details. + +- ``(wasm_of_ocaml (compilation_mode ))`` controls whether to use separate + compilation or not where ```` is either ``whole_program`` or + ``separate``. + +- ``(wasm_of_ocaml (sourcemap ))`` controls whether to generate sourcemap + or not where ```` 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 ))`` specifies the alias under which + :ref:`inline_tests` and tests (:ref:`tests-stanza`) run for the `wasm` mode. + +- ``(wasm_of_ocaml (enabled_if ))`` specifies whether the `wasm` mode is enabled. It is enabled by default. - ``(binaries )``, where ```` is a list of entries of the form ``( as )``. ``( as )`` makes the binary diff --git a/doc/reference/dune/executable.rst b/doc/reference/dune/executable.rst index deb0e3f1ba0..e4bf938223f 100644 --- a/doc/reference/dune/executable.rst +++ b/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 )``, Dune will know how to build ``.exe``. If requested, it will also know how to build ``.bc``, ``.bc.js`` and ``.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)). ``.exe`` is a native code executable, ``.bc`` is a bytecode executable which requires ``ocamlrun`` to run, ``.bc.js`` is a JavaScript generated using ``js_of_ocaml``, and ``.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 ``.bc.wasm.assets``). Please note: in case native compilation is not available, ``.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,20 +266,17 @@ options using ``(js_of_ocaml ())``. - ``(javascript_files ())`` to specify ``js_of_ocaml`` JavaScript runtime files. -- ``(wasm_files ())`` to specify ``wasm_of_ocaml`` - JavaScript and Wasm runtime files. - - ``(compilation_mode )`` where ``>`` is either ``whole_program`` or ``separate``. This is only available inside ``executable`` stanzas. - ``(sourcemap )`` where ``>`` is one of ``no``, ``file`` or ``inline``. This is only available inside ``executable`` stanzas. -- ``(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 )`` to specify whether the `js` mode is enabled. It is enabled by default. + This is only available inside ``executable`` stanzas. ```` is specified in the :doc:`/reference/ordered-set-language`. +```` 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 @@ -287,6 +284,26 @@ 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 ())``. + +```` are all optional. They are the same as the ```` above plus: + +- ``(wasm_files ())`` to specify ``wasm_of_ocaml`` + Wasm runtime files. + +For the ``(sourcemap )`` option, source maps are generated when ``>`` 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 ----------- diff --git a/doc/reference/dune/library.rst b/doc/reference/dune/library.rst index 8237e6d8f86..667ab5acaa4 100644 --- a/doc/reference/dune/library.rst +++ b/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`. diff --git a/doc/tests.rst b/doc/tests.rst index a26960658b1..9e9a9f9267f 100644 --- a/doc/tests.rst +++ b/doc/tests.rst @@ -258,6 +258,7 @@ 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: @@ -265,7 +266,7 @@ For instance: (library (name foo) - (inline_tests (modes byte best js)) + (inline_tests (modes byte best js wasm)) (preprocess (pps ppx_expect))) diff --git a/doc/wasmoo.rst b/doc/wasmoo.rst index 2a088b6d6db..01c5c56ddbf 100644 --- a/doc/wasmoo.rst +++ b/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