[ANN] camlid: A library for building C stub generators

Ecosystem
1

Dear all,

I’m happy to announce the first release of camlid (documentation).

While there are many C stub generators for OCaml, camlid takes a different approach: it is an OCaml library designed to help you build custom C stub generators.

Key Comparisons:

  • Vs. Ctypes: Manipulation of C structures stays in C. You don’t need to replicate C type descriptions in OCaml, keeping the compilation and maintenance simple.

  • Vs. Camlidl/SWIG: The generator is written in pure OCaml. This makes it easier to factorize and customize your bindings without resorting to m4, sed, or complex external DSLs.

Highlighted Features:

  • Library-specific initialization: Easily handle data structure setup.

  • Native Optimization: supports unboxed/untagged parameters in native mode.

  • Automated Definitions: Automatically generates the C/OCaml definitions your generated code uses. Referencing a generated C function name in your generated OCaml code automatically triggers its generation in the C file.

  • Free Variables: Generated functions can contain free variables that are automatically added as formal parameters. This allows you to easily pass a global “context” or “handle” through a generic function without manual boilerplate.

Example Usage: Using the built-in helpers, a generator is as simple as:

open Camlid
open Helper

 let () = Generate.to_file
    (* Indicates the basename used for the generated files *)
    "mylib"
    (* Indicates header to include *)
    ~headers:["alib.h"]
  [
    func "f_input" [ input int_trunc];
    func "f_output" [ output (ptr_ref int_trunc)];
    func "f_with_res" [] ~result:int_trunc;
    func "f_no_arg_no_result" [];
  ]

Only the mli of the generated module remains to be written with the documentation. For the first function above, the parameter is correctly marked as untagged (for OCaml versions that support it):

external f_input: (int [@untagged]) -> unit = "camlid_stub_f_input_byte" "camlid_stub_f_input"

A more complex example (converting the flint binding from Ctypes) can be found here.

The API is still experimental, and I would love to hear your feedback on the organization and naming! The package is already in the opam repository.

(The modern-ocaml template is awesome!)

8 Likes
C Stub : Sometimes the Old Ways Are Best?