Source

ocaml-cstruct-codegen / README.txt

Full commit
(* OASIS_START *)
(* DO NOT EDIT (digest: 48387c4b705458822196dc29f25d4964) *)
This is the README file for the ocaml-cstruct-codegen distribution.

Library for generating OCaml code to work with C-like structures

See the files INSTALL.txt for building and installation instructions. 


(* OASIS_STOP *)

  There already exists similar library "ocaml-cstruct"
( https://github.com/avsm/ocaml-cstruct ).  Here are differences between them:

  Cons:
- ocaml-cstruct is easier to add in a project (compare with section
  "How to use" below)
- ocaml-cstruct uses Camlp4, so it allows one to write cstruct-definitions
  directly in the code
- ocaml-cstruct-codegen is written in a too simple way, sometimes cynical

  Pros:
- ocaml-cstruct-codegen doesn't use Camlp4, it uses code generation
  (so people who don't want to learn Camlp4 can improve this library)
- typing: every structure has its own abstract type, so it's impossible
  to use a structure getter/setter on another structure (with different
  layout; so with different type)
- guarantees of full initialization of structures (when it's needed)
- can dump structures to human-readable strings

  Of course this can be imlpemented in ocaml-cstruct, but author didn't want
to "dive into Camlp4" just to do it.

  For each structure "mystruct" with field "a" this library generates
module Mystruct with abstract type t and values:
- val sizeof : int -- size of structure in octets
- val get_a : t -> <typeof a> -- gets field "a"
- val set_a : t -> <typeof a> -> unit -- set field "a"
- val of_bigarray : bigarray -> t -- create Mystruct.t on top of bigarray
- val bigarray_of : t -> bigarray -- get bigarray of Mystruct.t
- val create : unit -> t -- create uninitialized Mystruct.t
- val make : a:<typeof a> -> t -- create Mystruct.t passing initial field
  values as labelled arguments (so user has guarentees that all fields are
  initialized)
- val dump : t -> string -- creates human-readable string like "{ a=123 }"


  How to use:

Install ocaml-cstruct-codegen.

Add to _oasis:

    PreBuildCommand: sh ./gen_cstructs.sh

Add to _oasis / BuildDepends:

    cstruct_codegen, extunix

(since generated code uses extunix library to access bigarray "fields".)

Add to _tags:

    <src/gen_cstructs.*> : pkg_cstruct_codegen

Create ./gen_cstructs.sh:

    #! /bin/sh
    ocamlbuild src/gen_cstructs.byte && ./gen_cstructs.byte

In src/gen_cstructs.ml:

    open Cstruct_codegen
    [.. your structure definitions ..]
    let () = codegen "src/cstructs.ml" [struc1; struct2; ...]

Then use "src/cstructs.ml".  Something like:

    open Cstructs
    let my1 = Mystruct.make ~a:12 in print_string (Mystruct.dump my1)