How to build a toplevel

First, initialize the toplevel using Js_of_ocaml_toplevel.JsooTop.initialize.

Then, build your bytecode program with debug enabled (-g) and linkall (-linkall). You should obviously link in all the libraries you want accessible in the final toplevel.

Finaly, compile your toplevel to JavaScript passing the --toplevel flags to the js_of_ocaml compiler.

If you want to limit the set of modules available in the toplevel, you can explicitly pass a list of compilation units that should be accessible using the --export FILE flag. FILE must contain names of compilation unit to export - one per line. The jsoo_listunits tool, provided by the js_of_ocaml-toplevel opam package, can be used to generate this list from a set of findlib libraries.

For example, the following command will create a file FILE containing all compilation unit names provided by the findlib libraries stdlib and str.

  jsoo_listunits -o FILE stdlib str

Note that toplevels currently cannot be built using separate compilation.

How to build a program using the Dynlink library

OCaml supports dynlink of bytecode files using the dynlink library. In order to work when compiled to JavaScript, one need to follow the following steps:

First, make sure to link js_of_ocaml-compiler.dynlink to initialize the support for dynlink (the initialization is done automatically by side-effect).

Then, build your bytecode program with debug enabled (-g) and linkall (-linkall).

Finaly, compile your program to JavaScript passing the --dynlink flags to the js_of_ocaml compiler.

Here is an example showing how to compile and use a program using Dynlink:

  # cat main.ml
  let () = Dynlink.loadfile "./plugin.cmo"

  # Compiling main program
  ocamlfind ocamlc -linkpkg -package dynlink -package js_of_ocaml-compiler.dynlink main.ml -o main.bc
  js_of_ocaml main.bc --dynlink

  # Compiling plugin
  ocamlfind ocamlc -c plugin.ml

  # Test
  node ./main.js