package js_of_ocaml
All checked builds passInstall
dune-project
Dependency
Authors
Maintainers
Sources
sha256=a991ce25175a5a13240c8bf64354b8f35e0a8d7223b90bef01ba32bc6f929cf4
sha512=ce476986cb2c78990f29b1d7a01bb173a0d30ad0e0a80ba7bde9aa8365952ed01eda4935d92a323b982b0c1c897b20ef01eabe75fe80e4da858f73f6a2d25232
doc/build-toplevel.html
Toplevel and Dynlink
This page explains how to build an OCaml toplevel (REPL) that runs in the browser, and how to use dynamic linking to load bytecode at runtime.
Both js_of_ocaml and wasm_of_ocaml support these features.
Building a toplevel
A toplevel is an interactive OCaml environment (like ocaml or utop). Js_of_ocaml and wasm_of_ocaml can compile a toplevel to JavaScript or WebAssembly, allowing it to run in the browser. See the live demo.
With js_of_ocaml
- Initialize the toplevel in your OCaml code using
Js_of_ocaml_toplevel.Direct.initialize
Build your bytecode with debug info and linkall:
ocamlfind ocamlc -g -linkall -package js_of_ocaml-toplevel \ -linkpkg toplevel.ml -o toplevel.byte
Compile to JavaScript with the
--toplevelflag:js_of_ocaml --toplevel toplevel.byte -o toplevel.js
With wasm_of_ocaml
- Initialize the toplevel in your OCaml code using
Js_of_ocaml_toplevel.Direct.initialize
Build your bytecode with debug info and linkall, linking
wasm_of_ocaml-compiler.dynlinkandjs_of_ocaml-toplevel.common:ocamlfind ocamlc -g -linkall -package wasm_of_ocaml-compiler.dynlink \ -package js_of_ocaml-toplevel.common -package compiler-libs.toplevel \ -linkpkg toplevel.ml -o toplevel.byte
Compile to WebAssembly with the
--toplevelflag:wasm_of_ocaml --toplevel toplevel.byte -o toplevel.js
Running the toplevel in a Web Worker
The toplevel can run in a Web Worker so that parsing, compiling and evaluating code does not block the page: the page ships source to the worker and renders the results asynchronously.
This splits into two programs:
- the worker, which links the toplevel and evaluates the code;
- the host page, which drives the worker and renders results — it does not link the toplevel runtime, so it stays small.
The worker's entry point hands control to the generic driver:
(* worker.ml *)
let () = Js_of_ocaml_toplevel_worker.start ()Build it like a toplevel. Passing --no-cmis keeps the .cmi files out of worker.js (smaller output); the cmis are then provided as a bundle that the worker fetches at startup:
ocamlfind ocamlc -g -linkall \
-package js_of_ocaml-toplevel -package js_of_ocaml-toplevel.worker \
-linkpkg worker.ml -o worker.byte
js_of_ocaml --toplevel --no-cmis worker.byte -o worker.jsProduce that bundle with jsoo_mkcmis; it must be named stdlib.cmis.js. Only unwrapped libraries are resolvable from the toplevel this way (for example stdlib and lwt, not the wrapped js_of_ocaml):
jsoo_mkcmis -o stdlib.cmis.js stdlib
Both js_of_ocaml and jsoo_mkcmis place cmis under /static/cmis, so the worker only fetches the bundle when the cmis are not already there: drop --no-cmis to embed them in worker.js instead, and no bundle is needed.
The host page drives the worker through Js_of_ocaml_toplevel_worker_lwt_client (create, execute, reset, and interrupt to stop a hung computation). It depends only on js_of_ocaml-toplevel.worker_lwt_client and the dependency-free js_of_ocaml-toplevel.protocol (for the result type), so it links no toplevel runtime:
ocamlfind ocamlc -g \
-package js_of_ocaml-lwt \
-package js_of_ocaml-toplevel.worker_lwt_client \
-package js_of_ocaml-toplevel.protocol \
-linkpkg main.ml -o main.byte
js_of_ocaml main.byte -o main.jsThe toplevel/examples/lwt_toplevel_worker sources are a complete example, with a banner, input history, an examples sidebar, and a Cancel button that interrupts a stuck computation.
Limiting available modules
By default, all linked modules are available in the toplevel. To limit this, use --export FILE where FILE lists compilation unit names (one per line).
The jsoo_listunits tool generates this list from findlib libraries:
jsoo_listunits -o units.txt stdlib str js_of_ocaml --toplevel --export units.txt toplevel.byte
The --export flag works the same way with wasm_of_ocaml.
Using the Dynlink library
OCaml's Dynlink module lets you load bytecode files at runtime. This works in both js_of_ocaml and wasm_of_ocaml with some setup.
With js_of_ocaml
- Link
js_of_ocaml-compiler.dynlinkin your program (initializes dynlink support)
Build your bytecode with debug info and linkall:
ocamlfind ocamlc -g -linkall -package dynlink \ -package js_of_ocaml-compiler.dynlink -linkpkg main.ml -o main.byte
Compile to JavaScript with the
--dynlinkflag:js_of_ocaml --dynlink main.byte -o main.js
With wasm_of_ocaml
- Link
wasm_of_ocaml-compiler.dynlinkin your program (initializes dynlink support)
Build your bytecode with debug info and linkall:
ocamlfind ocamlc -g -linkall -package dynlink \ -package wasm_of_ocaml-compiler.dynlink -linkpkg main.ml -o main.byte
Compile to WebAssembly with the
--dynlinkflag:wasm_of_ocaml --dynlink main.byte -o main.js
Plugin .cmo files are compiled on the fly to WebAssembly and instantiated at runtime.
Example
(* main.ml *)
let () = Dynlink.loadfile "./plugin.cmo"With js_of_ocaml:
# Compile main program
ocamlfind ocamlc -g -linkall -package dynlink \
-package js_of_ocaml-compiler.dynlink -linkpkg main.ml -o main.byte
js_of_ocaml --dynlink main.byte -o main.js
# Compile plugin
ocamlfind ocamlc -c plugin.ml
# Run
node ./main.jsWith wasm_of_ocaml:
# Compile main program
ocamlfind ocamlc -g -linkall -package dynlink \
-package wasm_of_ocaml-compiler.dynlink -linkpkg main.ml -o main.byte
wasm_of_ocaml --dynlink main.byte -o main.js
# Compile plugin
ocamlfind ocamlc -c plugin.ml
# Run
node ./main.jsLoading precompiled files
By default, Dynlink.loadfile compiles .cmo and .cma files on the fly. You can also precompile plugins ahead of time for faster loading.
With js_of_ocaml
Use js_of_ocaml to compile a .cmo or .cma file to JavaScript:
js_of_ocaml plugin.cmo -o plugin.js js_of_ocaml plugin2.cma -o plugin2.js
Then load the resulting JavaScript file at runtime. In Node.js, use require:
let require s =
Js_of_ocaml.Js.Unsafe.fun_call
(Js_of_ocaml.Js.Unsafe.js_expr "require")
[| Js_of_ocaml.Js.Unsafe.inject (Js_of_ocaml.Js.string s) |]
let () = require "./plugin.js"In a browser, use a <script> tag:
<script src="plugin.js"></script>With wasm_of_ocaml
Use wasm_of_ocaml compile to compile a .cmo to a .wasmo file, or a .cma to a .wasma file:
wasm_of_ocaml compile plugin.cmo -o plugin.wasmo wasm_of_ocaml compile plugin2.cma -o plugin2.wasma
Then load the precompiled file using Wasm_of_ocaml_compiler_dynlink.loadfile:
let () = Wasm_of_ocaml_compiler_dynlink.loadfile "./plugin.wasmo"This skips the on-the-fly bytecode-to-Wasm compilation step, which can significantly reduce loading time for large plugins.
See also
- Command-line options — The
--topleveland--dynlinkflags - Compilation modes — Whole program vs separate compilation
index— Toplevel API