[Caml-list] ANN: ocaml-ctypes, a library for calling C functions directly from OCaml

[Caml-list] ANN: ocaml-ctypes, a library for calling C functions directly from OCaml

[Jeremy Yallop]

I'm happy to announce the initial release of ocaml-ctypes.

The ocaml-ctypes library makes it possible to call C functions
directly from OCaml without writing or generating C code.  The core of
the library is a set of combinators for describing C types -- scalars,
functions, structs, unions, arrays, and pointers to values and
functions.  Type descriptions can then be used to bind native
functions and values.  Here's a simple example:

    # let puts = foreign "puts" (string @-> returning int);;
    val puts : string -> int = <fun>
    # puts "Hello, world!";;
    Hello, world!

Here's a more substantial example that shows how to describe a C
structure type, map the type to an OCaml record, and call a function
that returns the structure.

    (* Describe the C struct.  There are two fields, both ints. *)
    let div_t = structure "div_t";;
    let q = div_t *:* int
    let r = div_t *:* int
    let () = seal div_t

    (* Define the OCaml record that we'll use to view the C structure. *)
    type div_result = { quot : int; rem: int }

    (* Define the conversions between the C struct and the OCaml record. *)
    let div_result_of_div_t d = { quot = getf d q; rem = getf d r }
    let div_t_of_div_result {quot; rem} =
        let d = make div_t in (setf d q quot; setf d r rem; d)

    (* Create a "view type" for that looks like div_result and behaves
like div_t *)
    let div_result = view ~read:div_result_of_div_t
~write:div_t_of_div_result div_t

    (* Bind to the standard C `div' function *)
    let div = foreign "div" (int @-> int @-> returning div_result)

    (* Try it out *)
    # div 17 2;;
    - : div_result = {quot = 8; rem = 1}

The distribution contains larger examples and a fairly extensive test
suite, showing how to use other features of the library, such as
binding to functions that accept callback arguments.  Among the
examples is Anil Madhavapeddy's port of the `curses' example from the
OCaml documentation; it's instructive to compare the two
implementations:

    OCaml manual curses example
    http://caml.inria.fr/pub/docs/manual-ocaml/manual033.html#toc147

    ocaml-ctypes curses example
    https://github.com/ocamllabs/ocaml-ctypes/blob/master/examples/ncurses/ncurses.ml

Detailed installation instructions for ocaml-ctypes can be found in
the tutorial.  (Briefly: ensure libffi is installed, then 'opam
install ctypes'.)

Comments, bug reports, and other feedback are most welcome.

Tutorial:
https://github.com/ocamllabs/ocaml-ctypes/wiki/ctypes-tutorial
Examples:
https://github.com/ocamllabs/ocaml-ctypes/tree/master/examples
API documentation: http://ocamllabs.github.io/ocaml-ctypes/
Github repository: https://github.com/ocamllabs/ocaml-ctypes
Direct download:
https://github.com/ocamllabs/ocaml-ctypes/archive/ocaml-ctypes-0.1.tar.gz

Re: [Caml-list] ANN: ocaml-ctypes, a library for calling C functions directly from OCaml

[Francois Berenger]

That looks very interesting!!!

How about the cost of exchanging values between C and OCaml?

Is there a trick in ocaml-ctypes like there is for bigarrays?

Regards,
F.

On 06/07/2013 08:17 AM, Jeremy Yallop wrote:
> I'm happy to announce the initial release of ocaml-ctypes.
>
> The ocaml-ctypes library makes it possible to call C functions
> directly from OCaml without writing or generating C code.  The core of
> the library is a set of combinators for describing C types -- scalars,
> functions, structs, unions, arrays, and pointers to values and
> functions.  Type descriptions can then be used to bind native
> functions and values.  Here's a simple example:
>
>      # let puts = foreign "puts" (string @-> returning int);;
>      val puts : string -> int = <fun>
>      # puts "Hello, world!";;
>      Hello, world!
>
> Here's a more substantial example that shows how to describe a C
> structure type, map the type to an OCaml record, and call a function
> that returns the structure.
>
>      (* Describe the C struct.  There are two fields, both ints. *)
>      let div_t = structure "div_t";;
>      let q = div_t *:* int
>      let r = div_t *:* int
>      let () = seal div_t
>
>      (* Define the OCaml record that we'll use to view the C structure. *)
>      type div_result = { quot : int; rem: int }
>
>      (* Define the conversions between the C struct and the OCaml record. *)
>      let div_result_of_div_t d = { quot = getf d q; rem = getf d r }
>      let div_t_of_div_result {quot; rem} =
>          let d = make div_t in (setf d q quot; setf d r rem; d)
>
>      (* Create a "view type" for that looks like div_result and behaves
> like div_t *)
>      let div_result = view ~read:div_result_of_div_t
> ~write:div_t_of_div_result div_t
>
>      (* Bind to the standard C `div' function *)
>      let div = foreign "div" (int @-> int @-> returning div_result)
>
>      (* Try it out *)
>      # div 17 2;;
>      - : div_result = {quot = 8; rem = 1}
>
> The distribution contains larger examples and a fairly extensive test
> suite, showing how to use other features of the library, such as
> binding to functions that accept callback arguments.  Among the
> examples is Anil Madhavapeddy's port of the `curses' example from the
> OCaml documentation; it's instructive to compare the two
> implementations:
>
>      OCaml manual curses example
>      http://caml.inria.fr/pub/docs/manual-ocaml/manual033.html#toc147
>
>      ocaml-ctypes curses example
>      https://github.com/ocamllabs/ocaml-ctypes/blob/master/examples/ncurses/ncurses.ml
>
> Detailed installation instructions for ocaml-ctypes can be found in
> the tutorial.  (Briefly: ensure libffi is installed, then 'opam
> install ctypes'.)
>
> Comments, bug reports, and other feedback are most welcome.
>
> Tutorial:
> https://github.com/ocamllabs/ocaml-ctypes/wiki/ctypes-tutorial
> Examples:
> https://github.com/ocamllabs/ocaml-ctypes/tree/master/examples
> API documentation: http://ocamllabs.github.io/ocaml-ctypes/
> Github repository: https://github.com/ocamllabs/ocaml-ctypes
> Direct download:
> https://github.com/ocamllabs/ocaml-ctypes/archive/ocaml-ctypes-0.1.tar.gz
>

Re: [Caml-list] ANN: ocaml-ctypes, a library for calling C functions directly from OCaml

[Anthony Tavener]

[-- Attachment #1: Type: text/plain, Size: 4500 bytes --]

"Too good to be true" is coming to mind now... because this looks
very nice. :) My TODO list has been getting choked up with "make
OCaml bindings for <some C lib>", but it's so unpleasant to do
(especially for libraries in development which you know will change).

Let's see how well this works...
Thanks, Jeremy!


On Thu, Jun 6, 2013 at 7:28 PM, Francois Berenger <berenger@riken.jp> wrote:

> That looks very interesting!!!
>
> How about the cost of exchanging values between C and OCaml?
>
> Is there a trick in ocaml-ctypes like there is for bigarrays?
>
> Regards,
> F.
>
>
> On 06/07/2013 08:17 AM, Jeremy Yallop wrote:
>
>> I'm happy to announce the initial release of ocaml-ctypes.
>>
>> The ocaml-ctypes library makes it possible to call C functions
>> directly from OCaml without writing or generating C code.  The core of
>> the library is a set of combinators for describing C types -- scalars,
>> functions, structs, unions, arrays, and pointers to values and
>> functions.  Type descriptions can then be used to bind native
>> functions and values.  Here's a simple example:
>>
>>      # let puts = foreign "puts" (string @-> returning int);;
>>      val puts : string -> int = <fun>
>>      # puts "Hello, world!";;
>>      Hello, world!
>>
>> Here's a more substantial example that shows how to describe a C
>> structure type, map the type to an OCaml record, and call a function
>> that returns the structure.
>>
>>      (* Describe the C struct.  There are two fields, both ints. *)
>>      let div_t = structure "div_t";;
>>      let q = div_t *:* int
>>      let r = div_t *:* int
>>      let () = seal div_t
>>
>>      (* Define the OCaml record that we'll use to view the C structure. *)
>>      type div_result = { quot : int; rem: int }
>>
>>      (* Define the conversions between the C struct and the OCaml record.
>> *)
>>      let div_result_of_div_t d = { quot = getf d q; rem = getf d r }
>>      let div_t_of_div_result {quot; rem} =
>>          let d = make div_t in (setf d q quot; setf d r rem; d)
>>
>>      (* Create a "view type" for that looks like div_result and behaves
>> like div_t *)
>>      let div_result = view ~read:div_result_of_div_t
>> ~write:div_t_of_div_result div_t
>>
>>      (* Bind to the standard C `div' function *)
>>      let div = foreign "div" (int @-> int @-> returning div_result)
>>
>>      (* Try it out *)
>>      # div 17 2;;
>>      - : div_result = {quot = 8; rem = 1}
>>
>> The distribution contains larger examples and a fairly extensive test
>> suite, showing how to use other features of the library, such as
>> binding to functions that accept callback arguments.  Among the
>> examples is Anil Madhavapeddy's port of the `curses' example from the
>> OCaml documentation; it's instructive to compare the two
>> implementations:
>>
>>      OCaml manual curses example
>>      http://caml.inria.fr/pub/docs/**manual-ocaml/manual033.html#**toc147<http://caml.inria.fr/pub/docs/manual-ocaml/manual033.html#toc147>
>>
>>      ocaml-ctypes curses example
>>      https://github.com/ocamllabs/**ocaml-ctypes/blob/master/**
>> examples/ncurses/ncurses.ml<https://github.com/ocamllabs/ocaml-ctypes/blob/master/examples/ncurses/ncurses.ml>
>>
>> Detailed installation instructions for ocaml-ctypes can be found in
>> the tutorial.  (Briefly: ensure libffi is installed, then 'opam
>> install ctypes'.)
>>
>> Comments, bug reports, and other feedback are most welcome.
>>
>> Tutorial:
>> https://github.com/ocamllabs/**ocaml-ctypes/wiki/ctypes-**tutorial<https://github.com/ocamllabs/ocaml-ctypes/wiki/ctypes-tutorial>
>> Examples:
>> https://github.com/ocamllabs/**ocaml-ctypes/tree/master/**examples<https://github.com/ocamllabs/ocaml-ctypes/tree/master/examples>
>> API documentation: http://ocamllabs.github.io/**ocaml-ctypes/<http://ocamllabs.github.io/ocaml-ctypes/>
>> Github repository: https://github.com/ocamllabs/**ocaml-ctypes<https://github.com/ocamllabs/ocaml-ctypes>
>> Direct download:
>> https://github.com/ocamllabs/**ocaml-ctypes/archive/ocaml-**
>> ctypes-0.1.tar.gz<https://github.com/ocamllabs/ocaml-ctypes/archive/ocaml-ctypes-0.1.tar.gz>
>>
>>
>
> --
> Caml-list mailing list.  Subscription management and archives:
> https://sympa.inria.fr/sympa/**arc/caml-list<https://sympa.inria.fr/sympa/arc/caml-list>
> Beginner's list: http://groups.yahoo.com/group/**ocaml_beginners<http://groups.yahoo.com/group/ocaml_beginners>
> Bug reports: http://caml.inria.fr/bin/caml-**bugs<http://caml.inria.fr/bin/caml-bugs>
>

[-- Attachment #2: Type: text/html, Size: 5761 bytes --]

Re: [Caml-list] ANN: ocaml-ctypes, a library for calling C functions directly from OCaml

[Jeremy Yallop]

On 7 June 2013 02:28, Francois Berenger <berenger@riken.jp> wrote:
> How about the cost of exchanging values between C and OCaml?
>
> Is there a trick in ocaml-ctypes like there is for bigarrays?

Array and struct memory in ocaml-ctypes is managed similarly to the
way bigarray does things, i.e. objects are allocated on the C heap, so
both C and OCaml functions can safely access them without copying.
However, there's no special compiler support for ocaml-ctypes as there
is for bigarrays, so it's likely that array access will be slower for
the moment.

Of course, arrays in ocaml-ctypes also have some advantages over
bigarrays.  For example, they can hold a broader range of data --
structs, pointers, and so on.

I'm hoping to add bigarray integration to ocaml-ctypes at some point.