Commits

Anonymous committed 382e860

readme

Comments (0)

Files changed (1)

 
 
 (* 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
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.