Crate raml

Raml is a library for directly interacting with the C OCaml runtime, in Rust. Consquently, raml is designed for rust shared objects that expose raw C FFI bindings, which are then either statically or dynamically linked against an OCaml binary, which calls into these raw FFI bindings as if they were regular, so-called “C stubs”. Similarly, any OCaml runtime functions, such as caml_string_length, will get their definition from the final OCaml binary, with its associated runtime.

The benefit of this approach is that it removes any bridging C code, and allows in essence, a direct interface between Rust and OCaml.

The macro has the format: (name, |params...|, <local variables..>, { // code body }, -> optional return value listed in local variables)

A basic example demonstrates their usage:

#[macro_use] extern crate raml;

// linking against this rust static lib, you can access this function in OCaml via:
// `external beef : int -> int = "ml_beef"`
caml!(ml_beef, |parameter|, <local>, {
    let i = int_val!(parameter);
    let res = 0xbeef * i;
    println!("about to return  0x{:x} to OCaml runtime", res);
    local = val_int!(res);
} -> local);

// this is only here to satisfy docs
fn main() {}

The macro takes care of automatically declaring CAMLparam et. al, as well as CAMLlocal and CAMLreturn.

If you need more fine grained control, caml_body! and others are available.

Some more examples:

#[macro_use] extern crate raml;

// these are two functions that OCaml code can access via `external val` declarations
caml!(ml_send_int, |v, v2|, <l>, {
    let x = int_val!(v);
    l = val_int!(0xbeef);
    println!("send_int  0x{:x}", x);
    // io::stdout().flush();
} -> l);

caml!(ml_send_two, |v, v2|, {
    println!("local root addr: {:p} caml_local_roots: {:#?}, v: {:?}", &raml::memory::caml_local_roots, raml::memory::caml_local_roots, v);
    let x = int_val!(v);
    let len = raml::mlvalues::caml_string_length(v2);
    let ptr = string_val!(v2);
    let slice = ::std::slice::from_raw_parts(ptr, len);
    let string = ::std::str::from_utf8_unchecked(slice);
    println!("got  0x{:x}, {}", x, string);
});

// this is only here to satisfy docs, you will likely want a staticlib, not a rust executable
fn main() {}

These will be accessible to an OCaml program via external declarations, e.g., for the above we could do something like:

external send_int : int -> int = "ml_send_int"
external send_two : int -> string -> unit = "ml_send_two"

let f x = x land 0x0000ffff

let _ =
  let string = "string thing" in
  let deadbeef = 0xdeadbeef in
  let res = send_int 0xb1b1eb0b in
  Printf.printf "send_int returned: 0x%x\n" res;
  flush stdout;
  send_two deadbeef string;
  send_two (f deadbeef) string

Modules

• alloc
  External definitions for allocating values in the OCaml runtime
• callback
  Callbacks from C to OCaml This is also where you initialize the OCaml runtime system via caml_startup or caml_main
• memory
  Defines types and macros primarily for interacting with the OCaml GC. In addition, a few extra convenience macros are added, in particular, caml! and caml_body! which are the primary API endpoints of raml.
• mlvalues
  Contains OCaml types and conversion functions from runtime representations.

Macros

• bp_val
  Pointer to the first byte
• caml
  Defines an external Rust function for FFI use by an OCaml program, with automatic CAMLparam, CAMLlocal, and CAMLreturn inserted for you.
• caml_body
  Defines an OCaml FFI body, including any locals, as well as a return if provided; it is up to you to define the parameters.
• caml_ffi
• caml_local
  Initializes and registers the given identifier(s) as a local value with the OCaml runtime.
• caml_param
  Registers OCaml parameters with the GC
• extract_exception
• field
  Extracts from the $block an OCaml value at the $ith-field
• int_val
  Converts an OCaml int into a usize
• is_exception_result
• long_val
  Long_val(x) ((x) >> 1)
• make_exception_result
• return0
  Returns an OCaml unit value
• store_field
  Stores the $val at $offset in the $block.
• string_val
  Extracts a machine ptr to the bytes making up an OCaml string
• val_int
  Converts a machine usize into an OCaml int
• val_long
  (((intnat)(x) << 1) + 1)