ocaml-cstruct-codegen / README.txt

Full commit
(* 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. 


  There already exists similar library "ocaml-cstruct"
( ).  Here are differences between them:

- 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

- 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 implemented in ocaml-cstruct, but author of this
library didn't want to "dive into Camlp4" just to add features to

  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
- val dump : t -> string -- creates human-readable string like "{ a=123 }"

  How to use:

Install ocaml-cstruct-codegen.

Add to _oasis:

    PreBuildCommand: 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 ./

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

In src/

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

Then use "src/".  Something like:

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