odig 0.0.2 · OCaml Package

OCaml compilation objects.

Note. All paths returned by functions of this module are made absolute (using for now, a fake realpath(2)).

Compilation objects

module Digest : sig ... end

Compilation object digests.

type digest = Digest.t

The type for compilation object digests.

type dep = string * digest option

The type for compilation object dependencies. A module name and an optional digest (often a cmi digest).

val pp_dep : dep Fmt.t

pp_dep ppf d prints an unspecified representation of d on ppf.

type mli

The type for mli files.

type cmi

The type for cmi files.

type cmti

The type for cmti files.

type ml

The type for ml files.

type cmo

The type for cmo files.

type cmt

The type for cmt files.

type cma

The type for cma files.

type cmx

The type for cmx files.

type cmxa

The type for cmxa files.

type cmxs

The type for cmxs files.

module Mli : sig ... end

mli files.

module Cmi : sig ... end

cmi files.

module Cmti : sig ... end

cmti files.

module Ml : sig ... end

ml files.

module Cmo : sig ... end

cmo files.

module Cmt : sig ... end

cmt files.

module Cma : sig ... end

cma files.

module Cmx : sig ... end

cmx files.

module Cmxa : sig ... end

cmxa files.

module Cmxs : sig ... end

cmxs files.

Compilation object sets

type set

The type for sets of compilation objects.

val empty_set : set

empty_set is an empty set of compilation objects.

val mlis : set -> mli list

mlis s is the list of mlis contained in s.

val cmis : set -> cmi list

cmis s is the list of cmis contained in s.

val cmtis : set -> cmti list

cmtis s is the list of cmtis contained in s.

val mls : set -> ml list

mls s is the list of mls contained in s.

val cmos : ?files:bool -> set -> cmo list

cmos ~files s is the list of cmos contained in s. If files is true (defaults to false), only the cmo files are listed and cmos that are part of cma files are omitted.

val cmts : set -> cmt list

cmts s is the list of cmts contained in s.

val cmas : set -> cma list

cmas s is the list of cmas contained in s.

val cmxs : ?files:bool -> set -> cmx list

cmxs ~files s is the list of cmxs contained in s. If files is true (defaults to false), only the cmx files are listed and cmxs that are part of cmxa files are omitted.

val cmxas : set -> cmxa list

cmxa s is the list of cmxas contained in s.

val cmxss : set -> cmxs list

cmxss s is the list of cmxss contained in s.

val set_of_dir : 
  ?err:(Fpath.t -> ('a, [ `Msg of string ]) Pervasives.result -> unit) ->
  Fpath.t ->
  set

set_of_dir ~err d is the set of compilation objects that are present in the file hierarchy rooted at d.

This is a best-effort function, it will call err on errors and continue; at worst you'll get an empty_set. err's default simply logs the error at level Logs.level.Error.

Compilation object indexes

type 'a index

See Index.t.

module Index : sig ... end

Compilation object indexes

Dependency resolution

type ('a, 'o) dep_resolution = [

| `None
| `Some of 'a * 'o
| `Amb of ('a * 'o) list

]

The type for dependency resolutions. Either no, some or an ambiguous resolution.

type ('a, 'o) dep_resolver = dep -> ('a * 'o) list -> ('a, 'o) dep_resolution

The type for dependency resolvers. Determines a resolution from a dependency and list of matching candidates.

val cmi_for_interface : 
  resolve:('a, cmi) dep_resolver ->
  'a index ->
  dep ->
  ('a, cmi) dep_resolution

cmi_for_interface ~resolve i dep is the resolution resolve of cmis matching module interface dep in i.

val cmo_for_interface : 
  resolve:('a, cmo) dep_resolver ->
  'a index ->
  dep ->
  ('a, cmo) dep_resolution

cmo_for_interface ~resolve i dep is the resolution resolve of cmos matching module interface dep in i.

val cmx_for_interface : 
  resolve:('a, cmx) dep_resolver ->
  'a index ->
  dep ->
  ('a, cmx) dep_resolution

cmx_for_interface ~resolve i dep is the resolution resolve of cmxs matching module interface dep in i.

Recursive resolution

type ('a, 'o) dep_src = ('a * 'o) list

The type for dependency sources. Tracks an object (head) to its source (tail). This is only used to allow good end-user feedback.

type ('a, 'o) rec_dep_resolution = [

| `Resolved of ('a * 'o) * ('a, 'o) dep_src
| `Unresolved of dep * [ `None | `Amb of ('a * 'o) list ] * ('a, 'o) dep_src
| `Conflict of string * ('a, 'o) dep_src list Digest.map

]

The type for recursive dependency resolution:

`Resolved (obj, src), a resolved object obj. src is one of the sources for obj.
`Unresolved (dep, reason, src), unresolved dependency dep for reason reason; either not found or ambiguous. src is one of the sources of dep.
`Conflict (n, dm), conflicting resolution for module name n. dm is the set of conflicting digests for n mapped to one of their source.

val pp_rec_dep_resolution : 
  ('a * 'o) Fmt.t ->
  ('a, 'o) rec_dep_resolution Fmt.t

pp_rec_dep_resolution pp_obj is an unspecified formatter for recursive dependency resolutions using pp_obj to format objects.

val rec_cmis_for_interfaces : 
  resolve:('a, cmi) dep_resolver ->
  'a index ->
  (dep * ('a, cmi) dep_src) list ->
  ('a, cmi) rec_dep_resolution Astring.String.map

See, mutatis mutandis, rec_cmos_for_interfaces.

val rec_cmos_for_interfaces : 
  ?cmo_deps:(cmo -> dep list) ->
  resolve:('a, cmo) dep_resolver ->
  'a index ->
  (dep * ('a, cmo) dep_src) list ->
  ('a, cmo) rec_dep_resolution Astring.String.map

rec_cmos_for_interfaces ~cmo_deps ~resolve i deps maps module names to the result of recursively resolving module interface dependencies deps (tupled with a dependency source) to cmos in i using resolve. More precisely:

First deps are resolved to cmos. Then for each of these cmos, their interface dependencies, as determined by cmo_deps (defaults to Cmo.cmi_deps) are resolved to cmos and recursively.
Conflicts occur if two module interface dependencies occur with the same module name but different interface digests. This means that the resolution request is inconsistent and cannot be used for linking.
Unresolvedness may be due to: missing objects in index, existing objects excluded by resolve, ambiguous objects not decided by resolve or because a module interface has no corresponding implementation – the OCaml compilation model allows this.

val fold_rec_dep_resolutions : 
  deps:('o -> dep list) ->
  (string -> ('a, 'o) rec_dep_resolution -> 'b -> 'b) ->
  ('a, 'o) rec_dep_resolution Astring.String.map ->
  'b ->
  'b

fold_rec_dep_resolutions ~deps f res acc folds f with acc over the partial evaluation order of res using deps on resolved objects. Conflicts and unresolved dependencies are also folded over.

raises Invalid_argument
if deps returns, on a resolved object, a name that is not in the domain of res.

package odig

Compilation objects

Compilation object sets

Compilation object indexes

Dependency resolution

Recursive resolution