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 a library called "ocaml-cstruct"
( https://github.com/avsm/ocaml-cstruct ) that serves similar purpose.
However, author of this library didn't want to "dive into Camlp4" to
add new features to ocaml-cstruct, and decided to write his own
implementation instead.

  Here is how they compare:

  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

  Cons:
- ocaml-cstruct is easier to add in a project (compare ocaml-cstruct docs
  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 very direct, one might even say
  cynical, way


  What would this library give you:

  For the structure called "mystruct" with a signle field called "a" 
 this library would generates module Mystruct with abstract type t and
  values:

- val sizeof : int -- get size of structure in octets
- val get_a : t -> <typeof a> -- get 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 -- convert t to human-readable string like "{ a=123 }"

  This, of course, scales up for multiple fields.


  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" [struct1; struct2; ...]

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

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


  People:

- Dmitry Grebeniuk <gdsfh1@gmail.com> -- code
- Dmitry Astapov <dastapov@gmail.com> -- documentation corrections


  License:

LGPL-2.1 with OCaml linking exception