package ocaml_plugin

  1. Overview
  2. Docs

The following functions are exposed for expert users only, not for the casual user, because they are much more error prone. Prefer load_ocaml_src_files if possible.

The complexity is due to the following unexpected or unpredictable behavior of Dynlink: dynlinking a file with a given filename only works properly the first time. Further dynlinks with the same filename (even if the contents of the file has changed in the meantime) will not load the new module but instead execute the initial module. Some even says that the behavior upon reload depends on the platform. Long story short: don't do that. Dynlink files at most once.

To work around this, you may automatically copy the given file to a temporary and unique name before dynlinking it.

It is worth noting too that the *load_cmxs_file functions below only work with cmxs files produced by ocaml_plugin's compile_ocaml_src_files_into_cmxs_file. They expect the code to perform some internal library calls, thus it cannot be used with any arbitrary cmxs compiled in some other way. Furthermore those functions would return an error even though the cmxs was built with ocaml_plugin when built under a different context (compiler version used, cmi dependencies version, etc.) The intended usage is to have the compilation and loading done using the same executable.

val compile_ocaml_src_files_into_cmxs_file : Dynloader.dynloader -> string list -> output_file:string -> unit Async.Deferred.Or_error.t

This compiles the source files into cmxs file, but does not execute the plugin toplevel. The resulting cmxs file can be loaded by the *load_cmxs_file function below either from within the same process or other processes which share the same executable. If compile succeeds, it returns Ok and write the compiled cmxs file into output_file (may override existing file), otherwise it returns Error and won't write to output_file at all.

val load_cmxs_file : string -> t Core.Or_error.t Async.Deferred.t
val blocking_load_cmxs_file : string -> t Core.Or_error.t

blocking_load_cmxs_file will return an error if called after the async scheduler has been started.