external name : type = C-function-name

        external input : in_channel -> string -> int -> int -> int
                       = "input"

        val name : type

        external name : type = C-function-name

    external input2 : in_channel * string * int * int -> int = "input2"

        type int_endo = int -> int
        external f : int_endo -> int_endo = "f"
        external g : (int -> int) -> (int -> int) = "f"

CAMLprim value input(value channel, value buffer, value offset, value length)
{
  ...
}

CAMLprim value add_nat_native(value nat1, value ofs1, value len1,
                              value nat2, value ofs2, value len2,
                              value carry_in)
{
  ...
}
CAMLprim value add_nat_bytecode(value * argv, int argn)
{
  return add_nat_native(argv[0], argv[1], argv[2], argv[3],
                        argv[4], argv[5], argv[6]);
}

        external name : type =
                 bytecode-C-function-name native-code-C-function-name

        external add_nat: nat -> int -> int -> nat -> int -> int -> int -> int
                        = "add_nat_bytecode" "add_nat_native"

CAMLprim value input(value channel, value buffer, value offset, value length)
{
  return Val_long(getblock((struct channel *) channel,
                           &Byte(buffer, Long_val(offset)),
                           Long_val(length)));
}

long getblock(struct channel * channel, char * p, long n)
{
  ...
}

• the table of the required primitives;
• a library that provides the bytecode interpreter, the memory manager, and the standard primitives;
• libraries and object code files (.o files) mentioned on the command line for the Caml linker, that provide implementations for the user's primitives.

• the -custom option;
• the names of the desired Caml object files (.cmo and .cma files) ;
• the names of the C object files and libraries (.o and .a files) that implement the required primitives. Under Unix and Windows, a library named libname.a residing in one of the standard library directories can also be specified as -cclib -lname.

• the names of the desired Caml native object files (.cmx and .cmxa files);
• the names of the C object files and libraries (.o, .a, .so or .dll files) that implement the required primitives.

        ocamlc -a -o mylib.cma -custom a.cmo b.cmo -cclib -lmylib

        ocamlc -o myprog mylib.cma ...

        ocamlc -o myprog -custom a.cmo b.cmo ... -cclib -lmylib

        ocamlc -a -o mylib.cma a.cmo b.cmo

        ocamlc -o myprog -custom mylib.cma ... -cclib -lmylib

• the names of the desired Caml object files (.cmo and .cma files) ;
• the names of the C shared libraries (.so or .dll files) that implement the required primitives. Under Unix and Windows, a library named dllname.so (respectively, .dll) residing in one of the standard library directories can also be specified as -dllib -lname.

        ocamlc -a -o mylib.cma a.cmo b.cmo -dllib -lmylib

        ocamlc -o myprog mylib.cma ...

        ocamlc -o myprog a.cmo b.cmo ... -dllib -lmylib

        ocamlc -make-runtime -o /home/me/ocamlunixrun unix.cma threads.cma

        ocamlc -use-runtime /home/me/ocamlunixrun -o myprog \
                unix.cma threads.cma your .cmo and .cma files

• an unboxed integer;
• a pointer to a block inside the heap (such as the blocks allocated through one of the alloc_* functions below);
• a pointer to an object outside the heap (e.g., a pointer to a block allocated by malloc, or to a C variable).

  callback(caml_get_public_method(foo, hash_variant("bar")), foo);

• Is_long(v) is true if value v is an immediate integer, false otherwise
• Is_block(v) is true if value v is a pointer to a block, and false if it is an immediate integer.

• Val_long(l) returns the value encoding the long int l.
• Long_val(v) returns the long int encoded in value v.
• Val_int(i) returns the value encoding the int i.
• Int_val(v) returns the int encoded in value v.
• Val_bool(x) returns the Caml boolean representing the truth value of the C integer x.
• Bool_val(v) returns 0 if v is the Caml boolean false, 1 if v is true.
• Val_true, Val_false represent the Caml booleans true and false.

• Wosize_val(v) returns the size of the block v, in words, excluding the header.
• Tag_val(v) returns the tag of the block v.
• Field(v, n) returns the value contained in the n^th field of the structured block v. Fields are numbered from 0 to Wosize_val(v)-1.
• Store_field(b, n, v) stores the value v in the field number n of value b, which must be a structured block.
• Code_val(v) returns the code part of the closure v.
• string_length(v) returns the length (number of characters) of the string v.
• Byte(v, n) returns the n^th character of the string v, with type char. Characters are numbered from 0 to string_length(v)-1.
• Byte_u(v, n) returns the n^th character of the string v, with type unsigned char. Characters are numbered from 0 to string_length(v)-1.
• String_val(v) returns a pointer to the first byte of the string v, with type char *. This pointer is a valid C string: there is a null character after the last character in the string. However, Caml strings can contain embedded null characters, that will confuse the usual C functions over strings.
• Double_val(v) returns the floating-point number contained in value v, with type double.
• Double_field(v, n) returns the n^th element of the array of floating-point numbers v (a block tagged Double_array_tag).
• Store_double_field(v, n, d) stores the double precision floating-point number d in the n^th element of the array of floating-point numbers v.
• Data_custom_val(v) returns a pointer to the data part of the custom block v. This pointer has type void * and must be cast to the type of the data contained in the custom block.
• Int32_val(v) returns the 32-bit integer contained in the int32 v.
• Int64_val(v) returns the 64-bit integer contained in the int64 v.
• Nativeint_val(v) returns the long integer contained in the nativeint v.

• Atom(t) returns an ``atom'' (zero-sized block) with tag t. Zero-sized blocks are preallocated outside of the heap. It is incorrect to try and allocate a zero-sized block using the functions below. For instance, Atom(0) represents the empty array.
• alloc(n, t) returns a fresh block of size n with tag t. If t is less than No_scan_tag, then the fields of the block are initialized with a valid value in order to satisfy the GC constraints.
• alloc_tuple(n) returns a fresh block of size n words, with tag 0.
• alloc_string(n) returns a string value of length n characters. The string initially contains garbage.
• copy_string(s) returns a string value containing a copy of the null-terminated C string s (a char *).
• copy_double(d) returns a floating-point value initialized with the double d.
• copy_int32(i), copy_int64(i) and copy_nativeint(i) return a value of Caml type int32, int64 and nativeint, respectively, initialized with the integer i.
• alloc_array(f, a) allocates an array of values, calling function f over each element of the input array a to transform it into a value. The array a is an array of pointers terminated by the null pointer. The function f receives each pointer as argument, and returns a value. The zero-tagged block returned by alloc_array(f, a) is filled with the values returned by the successive calls to f. (This function must not be used to build an array of floating-point numbers.)
• copy_string_array(p) allocates an array of strings, copied from the pointer to a string array p (a char **). p must be NULL-terminated.

• alloc_small(n, t) returns a fresh small block of size n £ Max_young_wosize words, with tag t. If this block is a structured block (i.e. if t < No_scan_tag), then the fields of the block (initially containing garbage) must be initialized with legal values (using direct assignment to the fields of the block) before the next allocation.
• alloc_shr(n, t) returns a fresh block of size n, with tag t. The size of the block can be greater than Max_young_wosize. (It can also be smaller, but in this case it is more efficient to call alloc_small instead of alloc_shr.) If this block is a structured block (i.e. if t < No_scan_tag), then the fields of the block (initially containing garbage) must be initialized with legal values (using the initialize function described below) before the next allocation.

• failwith(s), where s is a null-terminated C string (with type char *), raises exception Failure with argument s.
• invalid_argument(s), where s is a null-terminated C string (with type char *), raises exception Invalid_argument with argument s.

• raise_constant(id) raises the exception id with no argument;
• raise_with_arg(id, v) raises the exception id with the Caml value v as argument;
• raise_with_string(id, s), where s is a null-terminated C string, raises the exception id with a copy of the C string s as argument.

Note:

void foo (value v1, value v2, value v3)
{
  CAMLparam3 (v1, v2, v3);
  ...
  CAMLreturn0;
}

Note:

value bar (value v1, value v2, value v3)
{
  CAMLparam3 (v1, v2, v3);
  CAMLlocal1 (result);
  result = alloc (3, 0);
  ...
  CAMLreturn (result);
}

value bar (value v1, value v2, value v3)
{
  CAMLparam3 (v1, v2, v3);
  CAMLlocal1 (result);
  result = alloc (3, 0);
  Store_field (result, 0, v1);
  Store_field (result, 1, v2);
  Store_field (result, 2, v3);
  CAMLreturn (result);
}

Warning:

        Field(v, n) = vn;

        initialize(&Field(v, n), vn);

        Field(v, n) = w;

        initialize(&Field(v, n), w);

        modify(&Field(v, n), w);

value alloc_list_int(int i1, int i2)
{
  CAMLparam0 ();
  CAMLlocal2 (result, r);

  r = alloc(2, 0);                        /* Allocate a cons cell */
  Store_field(r, 0, Val_int(i2));         /* car = the integer i2 */
  Store_field(r, 1, Val_int(0));          /* cdr = the empty list [] */
  result = alloc(2, 0);                   /* Allocate the other cons cell */
  Store_field(result, 0, Val_int(i1));    /* car = the integer i1 */
  Store_field(result, 1, r);              /* cdr = the first cons cell */
  CAMLreturn (result);
}

value alloc_list_int(int i1, int i2)
{
  CAMLparam0 ();
  CAMLlocal2 (result, r);

  r = alloc_small(2, 0);                  /* Allocate a cons cell */
  Field(r, 0) = Val_int(i2);              /* car = the integer i2 */
  Field(r, 1) = Val_int(0);               /* cdr = the empty list [] */
  result = alloc_small(2, 0);             /* Allocate the other cons cell */
  Field(result, 0) = Val_int(i1);         /* car = the integer i1 */
  Field(result, 1) = r;                   /* cdr = the first cons cell */
  CAMLreturn (result);
}

value alloc_list_int(int i1, int i2)
{
  CAMLparam0 ();
  CAMLlocal2 (tail, r);

  r = alloc_small(2, 0);                  /* Allocate a cons cell */
  Field(r, 0) = Val_int(i1);              /* car = the integer i1 */
  Field(r, 1) = Val_int(0);               /* A dummy value
  tail = alloc_small(2, 0);               /* Allocate the other cons cell */
  Field(tail, 0) = Val_int(i2);           /* car = the integer i2 */
  Field(tail, 1) = Val_int(0);            /* cdr = the empty list [] */
  modify(&Field(r, 1), tail);             /* cdr of the result = tail */
  return r;
}

type window                   (* The type "window" remains abstract *)
external initscr: unit -> window = "curses_initscr"
external endwin: unit -> unit = "curses_endwin"
external refresh: unit -> unit = "curses_refresh"
external wrefresh : window -> unit = "curses_wrefresh"
external newwin: int -> int -> int -> int -> window = "curses_newwin"
external mvwin: window -> int -> int -> unit = "curses_mvwin"
external addch: char -> unit = "curses_addch"
external mvwaddch: window -> int -> int -> char -> unit = "curses_mvwaddch"
external addstr: string -> unit = "curses_addstr"
external mvwaddstr: window -> int -> int -> string -> unit = "curses_mvwaddstr"
(* lots more omitted *)

        ocamlc -c curses.mli

#include <curses.h>
#include <mlvalues.h>

value curses_initscr(value unit)
{
  CAMLparam1 (unit);
  CAMLreturn ((value) initscr());  /* OK to coerce directly from WINDOW * to
                              value since that's a block created by malloc() */
}

value curses_wrefresh(value win)
{
  CAMLparam1 (win);
  wrefresh((WINDOW *) win);
  CAMLreturn (Val_unit);
}

value curses_newwin(value nlines, value ncols, value x0, value y0)
{
  CAMLparam4 (nlines, ncols, x0, y0);
  CAMLreturn ((value) newwin(Int_val(nlines), Int_val(ncols),
                             Int_val(x0), Int_val(y0)));
}

value curses_addch(value c)
{
  CAMLparam1 (c);
  addch(Int_val(c));            /* Characters are encoded like integers */
  CAMLreturn (Val_unit);
}

value curses_addstr(value s)
{
  CAMLparam1 (s);
  addstr(String_val(s));
  CAMLreturn (Val_unit);
}

/* This goes on for pages. */

        cc -c -I/usr/local/lib/ocaml curses.c

        ocamlc -c curses.c

open Curses
let main_window = initscr () in
let small_window = newwin 10 5 20 10 in
  mvwaddstr main_window 10 2 "Hello";
  mvwaddstr small_window 4 3 "world";
  refresh();
  for i = 1 to 100000 do () done;
  endwin()

        ocamlc -c test.ml

        ocamlc -custom -o test test.cmo curses.o -cclib -lcurses

• callback(f, a) applies the functional value f to the value a and return the value returned by f.
• callback2(f, a, b) applies the functional value f (which is assumed to be a curried Caml function with two arguments) to a and b.
• callback3(f, a, b, c) applies the functional value f (a curried Caml function with three arguments) to a, b and c.
• callbackN(f, n, args) applies the functional value f to the n arguments contained in the array of values args.

    let f x = print_string "f is applied to "; print_int n; print_newline()
    let _ = Callback.register "test function" f

    void call_caml_f(int arg)
    {
        callback(*caml_named_value("test function"), Val_int(arg));
    }

    void call_caml_f(int arg)
    {
        static value * closure_f = NULL;
        if (closure_f == NULL) {
            /* First time around, look up by name */
            closure_f = caml_named_value("test function");
        }
        callback(*closure_f, Val_int(arg));
    }

    exception Error of string
    let _ = Callback.register_exception "test exception" (Error "any string")

    void raise_error(char * msg)
    {
        raise_with_string(*caml_named_value("test exception"), msg);
    }

• The C part of the program must provide a main function, which will override the default main function provided by the Caml runtime system. Execution will start in the user-defined main function just like for a regular C program.
  
  
• At some point, the C code must call caml_main(argv) to initialize the Caml code. The argv argument is a C array of strings (type char **), terminated with a NULL pointer, which represents the command-line arguments, as passed as second argument to main. The Caml array Sys.argv will be initialized from this parameter. For the bytecode compiler, argv[0] and argv[1] are also consulted to find the file containing the bytecode.
  
  
• The call to caml_main initializes the Caml runtime system, loads the bytecode (in the case of the bytecode compiler), and executes the initialization code of the Caml program. Typically, this initialization code registers callback functions using Callback.register. Once the Caml initialization code is complete, control returns to the C code that called caml_main.
  
  
• The C code can then invoke Caml functions using the callback mechanism (see section 18.7.1).

        ocamlc -output-obj -o camlcode.o unix.cma other .cmo and .cma files
        cc -o myprog C objects and libraries \
           camlcode.o -L/usr/local/lib/ocaml -lunix -lcamlrun

        ocamlopt -output-obj -o camlcode.o unix.cmxa other .cmx and .cmxa files
        cc -o myprog C objects and libraries \
           camlcode.o -L/usr/local/lib/ocaml -lunix -lasmrun

Warning:

• Alpha under Digital Unix / Tru64 Unix with gcc: object files produced by ocamlc -output-obj must be linked with the gcc options -Wl,-T,12000000 -Wl,-D,14000000. This is not necessary for object files produced by ocamlopt -output-obj.
• Windows NT: the object file produced by Objective Caml have been compiled with the /MT flag, and therefore all other object files linked with it should also be compiled with /MT.

(* File mod.ml -- some ``useful'' Caml functions *)

let rec fib n = if n < 2 then 1 else fib(n-1) + fib(n-2)

let format_result n = Printf.sprintf "Result is: %d\n" n

(* Export those two functions to C *)

let _ = Callback.register "fib" fib
let _ = Callback.register "format_result" format_result

/* File modwrap.c -- wrappers around the Caml functions */

#include <stdio.h>
#include <string.h>
#include <caml/mlvalues.h>
#include <caml/callback.h>

int fib(int n)
{
  static value * fib_closure = NULL;
  if (fib_closure == NULL) fib_closure = caml_named_value("fib");
  return Int_val(callback(*fib_closure, Val_int(n)));
}

char * format_result(int n)
{
  static value * format_result_closure = NULL;
  if (format_result_closure == NULL)
    format_result_closure = caml_named_value("format_result");
  return strdup(String_val(callback(*format_result_closure, Val_int(n))));
  /* We copy the C string returned by String_val to the C heap
     so that it remains valid after garbage collection. */
}

        ocamlc -custom -output-obj -o modcaml.o mod.ml
        ocamlc -c modwrap.c
        cp /usr/local/lib/ocaml/libcamlrun.a mod.a
        ar r mod.a modcaml.o modwrap.o

/* File main.c -- a sample client for the Caml functions */

#include <stdio.h>

int main(int argc, char ** argv)
{
  int result;

  /* Initialize Caml code */
  caml_startup(argv);
  /* Do some computation */
  result = fib(10);
  printf("fib(10) = %s\n", format_result(result));
  return 0;
}

        cc -o prog main.c mod.a -lcurses

• char *identifier
  A zero-terminated character string serving as an identifier for serialization and deserialization operations.
  
  
• void (*finalize)(value v)
  The finalize field contains a pointer to a C function that is called when the block becomes unreachable and is about to be reclaimed. The block is passed as first argument to the function. The finalize field can also be NULL to indicate that no finalization function is associated with the block. Important note: the v parameter of this function is of type value, but it must not be declared using the CAMLparam macros.
  
  
• int (*compare)(value v1, value v2)
  The compare field contains a pointer to a C function that is called whenever two custom blocks are compared using Caml's generic comparison operators (=, <>, <=, >=, <, > and compare). The C function should return 0 if the data contained in the two blocks are structurally equal, a negative integer if the data from the first block is less than the data from the second block, and a positive integer if the data from the first block is greater than the data from the second block. Note: You must use CAMLparam to declare v1 and v2 and CAMLreturn to return the result.
  
  The compare field can be set to custom_compare_default; this default comparison function simply raises Failure.
  
  
• long (*hash)(value v)
  The hash field contains a pointer to a C function that is called whenever Caml's generic hash operator (see module Hashtbl) is applied to a custom block. The C function can return an arbitrary long integer representing the hash value of the data contained in the given custom block. The hash value must be compatible with the compare function, in the sense that two structurally equal data (that is, two custom blocks for which compare returns 0) must have the same hash value. Note: You must use CAMLparam to declare v and CAMLreturn to return the result.
  
  The hash field can be set to custom_hash_default, in which case the custom block is ignored during hash computation.
  
  
• void (*serialize)(value v, unsigned long * wsize_32, unsigned long * wsize_64)
  The serialize field contains a pointer to a C function that is called whenever the custom block needs to be serialized (marshaled) using the Caml functions output_value or Marshal.to_.... For a custom block, those functions first write the identifier of the block (as given by the identifier field) to the output stream, then call the user-provided serialize function. That function is responsible for writing the data contained in the custom block, using the serialize_... functions defined in <caml/intext.h> and listed below. The user-provided serialize function must then store in its wsize_32 and wsize_64 parameters the sizes in bytes of the data part of the custom block on a 32-bit architecture and on a 64-bit architecture, respectively. Note: You must use CAMLparam to declare v and CAMLreturn to return the result.
  
  The serialize field can be set to custom_serialize_default, in which case the Failure exception is raised when attempting to serialize the custom block.
  
  
• unsigned long (*deserialize)(void * dst)
  The deserialize field contains a pointer to a C function that is called whenever a custom block with identifier identifier needs to be deserialized (un-marshaled) using the Caml functions input_value or Marshal.from_.... This user-provided function is responsible for reading back the data written by the serialize operation, using the deserialize_... functions defined in <caml/intext.h> and listed below. It must then rebuild the data part of the custom block and store it at the pointer given as the dst argument. Finally, it returns the size in bytes of the data part of the custom block. This size must be identical to the wsize_32 result of the serialize operation if the architecture is 32 bits, or wsize_64 if the architecture is 64 bits.
  
  The deserialize field can be set to custom_deserialize_default to indicate that deserialization is not supported. In this case, do not register the struct custom_operations with the deserializer using register_custom_operations (see below).

This command is available only under Cygwin, but not for the native Win32 port.

• Caml source files and object files (.cmo, .cmx, .ml) comprising the Caml part of the library;
• C object files (.o, .a) comprising the C part of the library;
• Support libraries for the C part (-llib).

• A Caml bytecode library .cma incorporating the .cmo and .ml Caml files given as arguments, and automatically referencing the C library generated with the C object files.
• A Caml native-code library .cmxa incorporating the .cmx and .ml Caml files given as arguments, and automatically referencing the C library generated with the C object files.
• If dynamic linking is supported on the target platform, a .so shared library built from the C object files given as arguments, and automatically referencing the support libraries.
• A C static library .a built from the C object files.

-cclib, -ccopt, -I, -linkall

These options are passed as is to ocamlc or ocamlopt. See the documentation of these commands.

-pthread, -rpath, -R, -Wl,-rpath, -Wl,-R

These options are passed as is to the C compiler. Refer to the documentation of the C compiler.

-custom

Force the construction of a statically linked library only, even if dynamic linking is supported.

-failsafe

Fall back to building a statically linked library if a problem occurs while building the shared library (e.g. some of the support libraries are not available as shared libraries).

-Ldir

Add dir to the search path for support libraries (-llib).

-ocamlc cmd

Use cmd instead of ocamlc to call the bytecode compiler.

-ocamlopt cmd

Use cmd instead of ocamlopt to call the native-code compiler.

-o output

Set the name of the generated Caml library. ocamlmklib will generate output.cma and/or output.cmxa. If not specified, defaults to a.

-oc outputc

Set the name of the generated C library. ocamlmklib will generate liboutputc.so (if shared libraries are supported) and liboutputc.a. If not specified, defaults to the output name given with -o.

Example

ocamlmklib -o zip zip.cmo zip.cmx zipstubs.o -lz -L/usr/local/zlib

ocamlc -a -o zip.cma zip.cmo -dllib -lzip \
        -cclib -lzip -cclib -lz -ccopt -L/usr/local/zlib
ocamlopt -a -o zip.cmxa zip.cmx -cclib -lzip \
        -cclib -lzip -cclib -lz -ccopt -L/usr/local/zlib
gcc -shared -o dllzip.so zipstubs.o -lz -L/usr/local/zlib
ar rc libzip.a zipstubs.o

ocamlc -a -custom -o zip.cma zip.cmo -cclib -lzip \
        -cclib -lz -ccopt -L/usr/local/zlib
ocamlopt -a -o zip.cmxa zip.cmx -lzip \
        -cclib -lz -ccopt -L/usr/local/zlib
ar rc libzip.a zipstubs.o

ocamlmklib -o zip zip.cmo -lz -L/usr/local/zlib

ocamlmklib -o zip zip.cmx -lz -L/usr/local/zlib

ocamlmklib -o zip zipstubs.o -lz -L/usr/local/zlib