*** About Hydro ***

Hydro is an independent implementation of ICE, the object-oriented RPC
protocol by ZeroC, for the O'Caml programming language. This is an
early, not yet complete release, but the code is already stable and
usable. For the restrictions of this release, see below.

Hydro (like ICE) allows you to bridge language barriers by letting
components written in different programming languages communicate with
each other. ZeroC's ICE product currently includes implementations for
C++, Java, C#, Python, Ruby, VB, and PHP.  Hydro adds support for
O'Caml. The ICE protocol is rich enough to make the representation of
the data to communicate easy and convenient to use, and adopts an
object-oriented type system. ZeroC sees ICE as a superior successor to
CORBA.

Hydro includes a runtime, and a generator called hydrogen. The runtime
is fully asynchronous, based on Ocamlnet's event queues. The generator
is used to create a thin layer on top of the runtime that maps
abstract Hydro types to specific O'Caml types.  The Hydro engine
therefore appears to the programmer as if it was typed using the input
IDL file. Unlike the generators shipped by ZeroC, hydrogen does not
create marshalling code -- we see this as the task of the runtime and
not of the language mapping layer. Because of this design decision we
have high confidence in the correctness of the generator.

Although we want Hydro to be an implementation whose protocol is fully
compatible with ICE and that can process all its IDL files, we take
some freedom to deviate from what is described in ZeroC's "ICE
manual". ICE was designed with mainstream object-oriented languages in
mind, and therefore lacks many of the advanced constructs available in
O'Caml (variants, for example).  Conversely, ICE includes constructs
such as hierarchical exceptions and downcasts which do not exist in
O'Caml (and for good reason!).  To deal with the "impedance mismatch,"
we implemented emulations for these concepts.  On the other hand,
O'Caml offers advanced features which ought to be exploited by a good
implementation.  For example, in O'Caml, asynchronous networking code
is quite natural, so we have chosen to make this the default style. So
while Hydro is quite straightforward, the O'Caml programmer should not
expect a design which is a perfect one-to-one translation of what
ZeroC describes.

For the license conditions, see the file LICENSE.

*** Features ***

- Support for clients (proxies) and servers
- The whole ICE type system is implemented, and can be marshalled.
  This includes graphs of objects.
- The whole ICE type system can be mapped to O'Caml types. The
  mapping is quite flexible and configurable, e.g. you can choose
  whether you prefer arrays or lists as representations of 
  ICE sequences. Where necessary, the properties of the ICE type
  system are emulated. For example, hydrogen generates special
  code for downcasts of objects.
- IDL files are dynamically represented at runtime
- The runtime supports both asynchronous and synchronous method
  invocation
- The runtime can be integrated with other libraries that also base
  on Ocamlnet's event queues, e.g. with Ocamlnet's HTTP clients, or
  SunRPC.
- Fully automatic connection management
- Servers can be integrated into Netplex
- The generated code is properly indented
- Liberal license conditions

*** Restrictions ***

- Hydro only supports twoway calls over TCP for now
- Hydro does not support separate compilation (i.e. you cannot split
  an .ice file into several parts, hydrogen every part alone, and then
  merge them later). This is a fundamental restriction we'll never
  be able to improve.
- There is no support for Slice checksums
- There is no support for checked proxy casts (too will follow soon)
- There is no support for configuration files
- The runtime and the generated language mapping layer are both
  reentrant. However, there is no specific support for multi-threaded
  programming beyond this
- There is no support for compression
- Except of calling the locator service of IceGrid, there is no support
  for add-on technologies like IceGrid, Freeze, etc. We have some interest
  in IceGrid, so this may also follow at some time.

*** Prerequisites ***

You need the following to build Hydro:

- omake
- ocamlnet
- ocamlpcre
- findlib

*** Build & Install ***

Build the bytecode version: make all
Build the native version: make opt

Install the library in the findlib default location: make install
Remove it from there: make uninstall

Note that the "Makefile" is just a wrapper for "OMakefile". For detailed
control you might want to invoke omake directly.

Also note that "hydrogen" is installed into the findlib directory.
You can invoke "hydrogen" by

    ocamlfind hydrogen/hydrogen [args]

*** Documentation ***

The reference manual is in doc/html.

*** Authors ***

Hydro is developed by Gerd Stolpmann <gerd@gerd-stolpmann.de> and Mika
Illouz <mika@illouz.net> for Wink Technologies, Inc.
(http://wink.com).