Architecture support
====================

bin-prot works at its best on little endian architecture and has been
thoroughly tested only on i386 and amd64. Using it on other architectures can
exhibit a number of limitation. Here is a summary of such limitation taken from
a post by upstream author Markus Mottl to the Caml mailing list
(http://groups.google.com/group/fa.caml/msg/80da07bb322f2d7a)

> We currently do not have any immediate need and man power to fully
> support big-endian machines (we also don't have access to any), but
> we'll gladly accept patches.  This could be implemented using
> platform-specific macros as is the case with 32/64bit.
> 
> This is what works / doesn't work as of now:
> 
>   *) Big-endian and little-endian machines cannot communicate with
> each other for anything but very specific cases.  Don't use the binary
> protocol in such heterogeneous environments.
> 
>   *) 32 and 64 bit, little-endian architectures can communicate
> freely, assuming, of course, that integers do not overflow on 32bit.
> This is tested at runtime to prevent hard to debug errors.
> 
>   *) 32bit big-endian machines can communicate with each other freely.
> 64 bit big-endians can communicate with each other freely, too, but
> not necessarily with 32bit big-endians: values of type int64, etc.,
> may not necessarily be communicated correctly.  Note, too, that you
> should exclusively use the automatically generated converters on
> big-endian machines.  The hand-written (slower) ones for the basic
> types are intended mostly for testing purposes only, and will not work
> when mixed with a different endianness (they assume little-endians).
> 
> Thus, it certainly makes sense to package the binary protocol for
> big-endians, too, as long as people are informed of what works.  Since
> almost nobody uses big-endian machines, most users won't care.  But
> I'd surely be happy to see a patch to fully support all
> architectures... 

Syntax extension usage
======================

The easiest way to use bin-prot syntax extension is via findlib.

To compile sources which are using it invoke findlib passing "-syntax camlp4o"
and providing the "bin_prot.syntax" package. For example:

  $ cat foo.ml 
  TYPE_CONV_PATH "Foo"
  type foo = Foo with bin_io

  $ ocamlfind ocamlc -linkpkg -package bin_prot.syntax -syntax camlp4o -o foo foo.ml

Similarly, to try the syntax extension in the toplevel:

  $ ledit ocaml
        Objective Caml version 3.10.1

  # #use "topfind";;
  - : unit = ()
  Findlib has been successfully loaded. Additional directives:
  <snip>

  # #camlp4o;;
  /usr/lib/ocaml/3.10.1/camlp4: added to search path
  /usr/lib/ocaml/3.10.1/camlp4/camlp4o.cma: loaded
          Camlp4 Parsing version 3.10.1
  
  # #require "bin_prot.syntax";;
  <snip>
  /usr/local/lib/ocaml/3.10.1/type-conv/pa_type_conv.cmo: loaded
  /usr/lib/ocaml/3.10.1/bin_prot/pa_bin_prot.cmo: loaded

  # type foo = Foo with bin_io;;
  type foo = Foo
  val bin_read_foo__ : 'a -> 'b -> 'c -> 'd = <fun>
  val bin_read_foo_ :
    Bin_prot.Unsafe_common.sptr_ptr -> Bin_prot.Unsafe_common.eptr -> foo =
    <fun>
  val bin_read_foo :
    Bin_prot.Common.buf -> pos_ref:Bin_prot.Common.pos ref -> foo = <fun>