Module `Omod`

Load installed modules in the toplevel.

v0.0.2 — homepage

Omod

type fpath = string: The type for file paths.

type silent = [ | `Yes | `Loads | `No ]: The type for specifying silence. See load.

val load : ?⁠batch:bool -> ?⁠silent:silent -> ?⁠force:bool -> ?⁠incs:bool -> ?⁠init:bool -> ?⁠dir:fpath -> string -> bool

load ~batch ~silent ~force ~deps ~incs ~init ~dir "M" loads module M and returns true if the load was successful; init files may however have failed to load. The exact side effects of this function are described here. The optional parameters are as follows:

batch if true alternative load sequences error rather than interactively ask to select one. Defaults to not !Sys.interactive.
silent if `All nothing is logged except errors. If `Loads then load sequences are not logged but other diagnostic messages may be logged. If `No both load sequences and diagnostic messages are logged. Defaults to `No.
force if true force the reload of objects. Defaults to false.
incs if true directory includes should be added. Defaults to true. See load semantics for details.
init if true toplevel init files should be loaded, see the load semantics. Defaults to true.
dir is currently ignored.

The full syntax for specifying the module to load is:

[PKG.]M(@VARIANT)*

M is always the top level (compilation unit) module name to load.
PKG constrains M to be found in package PKG. Packages names are the name of directories just below omod's library directory (see omod conf, and omod pkg for a list).
@VARIANT (repeatable) indicates that all ambiguities should be resolved according to variant VARIANT. This means that if an object can be found in multiple directories in a package directory P, the one that is rooted in the hierarchy starting at P/VARIANT or P/@VARIANT will be selected. If no ambiguity arises the parameter is ignored. See the tutorial for an example.

val loads : ?⁠batch:bool -> ?⁠silent:silent -> ?⁠force:bool -> ?⁠incs:bool -> ?⁠init:bool -> ?⁠dir:fpath -> string list -> bool: loads is like load but for a list of module specifications. Note that specified variants apply to all of the modules.

val help : unit -> unit: help () prints basic help on stdout.

val status : unit -> unit: status () prints what is currently loaded by omod (including assumptions)

Assuming loads

This following can be used to assume that certain loads are already performed to prevent them from being (re)loaded by load invocations.

val assume_load : ?⁠batch:bool -> ?⁠silent:silent -> ?⁠force:bool -> ?⁠incs:bool -> ?⁠init:bool -> ?⁠dir:fpath -> string -> bool: assume_load is like load but assumes the corresponding load sequence was already performed.

val assume_loads : ?⁠batch:bool -> ?⁠silent:silent -> ?⁠force:bool -> ?⁠incs:bool -> ?⁠init:bool -> ?⁠dir:fpath -> string list -> bool: assume_loads is like loads but assumes the corresponding load sequence was already performed.

val assume_inc : fpath -> unit: assume_inc dir assumes that path dir has been included.

val assume_obj : fpath -> unit: assume_obj obj assumes that file path obj has been loaded.

module Private : sig ... end: Private definitions.

Tutorial

To use the toplevel helpers simply bring the Omod module in your scope: type or add the following line to your ~/.ocamlinit file.

#use "omod.top"

If you are using ocamlnat you unfortunately need to #use another file:

#use "omod.nattop"

It is also likely that opam's initialization bits in .ocamlinit to find the file to #use won't work. So you need to invoke ocamlnat with -noinit and indicate where the file to #use can be found. The following invocation should work:

rlwrap ocamlnat -I $OCAML_TOPLEVEL_PATH -noinit

Now whenever you want to use a module named M invoke:

# Omod.load "M"

This will recursively load its dependencies and toplevel init files. See load for more options and details.

If you are using omod in scripts you should also specify the package PKG where M should be found using the PKG.M syntax. This because a further package install could also install a module M resulting in a load ambiguity and your script no longer working.

If you run into multiple load sequence resolutions, Omod interactively asks to choose one of the possible sequences. Assuming you have the package ptime installed this is an example:

# Omod.load "Ptime_clock"

since ptime provides an os clock for your operating system and a jsoo clock for your browser.

The ambiguity can be automatically resolved by specfiying the variant you want explicitely (see load for details) for example to directly request the OS clock you should issue:

# Omod.load "Ptime_clock\@os"

In a script it would even be better to write:

# Omod.load "ptime.Ptime_clock\@os"

Finally to list what was loaded by Omod type:

# Omod.status ()

For information about how Omod locates packages, consult omod conf --help.

Load semantics and effects

Loading an object means: load its dependencies, add its containing directory to the included directories (if incs is true), load the actual object and finally load its toplevel init file (if init is true and the file exists, see below).
The toplevel init file of an object with basename o is a file called o_top_init.ml in the same directory as the object.
If an object is available both as a standalone file (cmo, cmx) and in a library archive (cma, cmxs), Omod favours loading the library archive.
If an interface dependency cannot be resolved to an implementation but does resolve to a compiled interface, the dependency is assumed to be a mli-only compilation unit and the directory of the compiled interface is added to the includes (if incs is true).
The initalization performed by omod.top and omod.nattop assume (with incs:false and init:false) the following modules:
- utop.UTop if omod.top is #used in utop.
- ocaml.Toploop if omod.top is #used (not in utop).
- ocaml.Opttoploop if omod.nattop is #used. .
Load sequences with vmthread variants and objects of the form m.p.ext (profiling versions in the stdlib) are excluded from load sequence results. This reduces the load sequence from multiple occurences to a single candidate on many modules.
For ocamlnat dependency analysis is made on cmx and cmxa files, the suffixes of resulting objects is then mapped to cmxs. This assumes the corresponding files exist and their objects match.