OCaml-R
                  ===================

   Objective Caml bindings for the R interpreter.

   Copyright 2008-2010 INRIA - Maxence Guesdon.
   Contact: [email protected]

   Copyright 2009-2010 Guillaume Yziquel.
   Contact: [email protected]

   Licenced under the GPL version 3.

                               Lausanne, October 2010



-1- Status of OCaml-R
=====================

   OCaml-R is still in development, is usable, but
   still has some syntactic idiosyncrasies and some
   performance bottlenecks.

   OCaml-R was initially written by Maxence Guesdon
   and has been almost entirely rewritten by Guillaume
   Yziquel to provide a tight integration with R's API.


-2- Description of OCaml-R
==========================

   OCaml-R is an Objective Caml binding embedding R's
   interpreter into OCaml code. It also provides bindings
   to R's standalone mathematical library, and has
   embryonic support for R's standard libraries.

   A longer term goal is to provide a syntax extension
   introspecting R packages to generate OCaml code binding
   the R symbols at OCaml compile time.

   Another longer term goal is to provide a syntax extension
   around R's calling conventions. The current situation
   is quite clumsy and unsatisfying.

   The aim of OCaml-R is to target R's most recent versions
   of R. More specifically, it is developed against the R
   packages provided in Debian. Please report any issues
   regarding to portability.


-3- Availability of source code and binaries
============================================

   Source code is managed with Git in these repositories:

   -- http://yziquel.homelinux.org/gitweb/?p=ocaml-r.git
   -- http://github.com/yziquel/OCaml-R

   To get the source code, type:

   -- git clone git://github.com/yziquel/OCaml-R.git

   There are some precompiled binaries for Debian, amd64:

   -- http://yziquel.homelinux.org/debian/pool/main/o/ocaml-r/

   PLEASE: Give me feedback if you have the slightest compilation
   error, or if you would like to have the binaries packaged for
   some other distribution system, or some other architecture!


-4-  Required dependencies for OCaml-R
=======================================

   You will need OCaml, findlib, and R. Using a full R
   distribution is recommended.

   You will need usual GNU utilities and camlp4 to build the
   software from source.


-5-  Build instructions
=======================

   Ideally, you should only have to run 'make' to build the
   OCaml-R software. make install should work. Please report
   if it doesn't, (since I'm working on it directly building
   Debian packages instead of using the install target).

   The paths for linking the R libraries to the OCaml libraries
   are taken from Debian. You may need to adapt these paths to
   your system. Again, please report if you encounter the need
   to do so.

   Currently, it works on Debian, and someone has reported me
   that it compiles without problems on Mac OS X 10 6.3.


-6-  How to use the library
===========================

   This goes somewhat further than the scope of this README file.
   However, a few general statements about findlib packaging:

   The R package depends on R.cma or R.cmxa, which contains the
   R module module and links in dynamically the shared library
   of R's interpreter.

   However, #require "R" is not sufficient to have the R interpreter
   properly initialised.

   The R.interpreter package depends on oCamlR.cmo or oCamlR.cmx,
   and when loaded, this module properly initialises the Python
   interpreter. So you only have to #require "R.interpreter" to
   have R up and running.

   There are other packages. R.math links to the standalone
   mathematical shared library of R. Other packages, such as
   R.base and R.stats are embryonic bindings of R's standard
   library. Help is very welcome on this side.

   The OCaml-R API:     http://yziquel.homelinux.org/api/ocaml-r


-7-  The author, and contact information
========================================

   As mentionned earlier, OCaml-R was initially written by Maxence
   Guesdon. It was a rather simple binding that was used essentially
   by feeding strings to the R interpreter parser and evaluation
   function, and providing data conversion functions for simple R
   types. This was version 0.1 of OCaml-R.

   The current version 0.2, is essentially an almost complete rewrite
   by Guillaume Yziquel providing tight integration with the R library.
   It can dissect R values to expose their internal structures to OCaml
   (though this shouldn't be the most useful aspect, nor the recommended
   way to use this binding), it construct R calls by building up R values
   directly, integrates OCaml's and R's garbage collectors (though somewhat
   poorly), chains R exceptions back to Objective Caml, and provides static
   initialisation of the R interpreter.

   The initial author, Maxence Guesdon, can be reached at:

                      [email protected]

   You can reach Guillaume Yziquel at:

                    [email protected]

   I (Guillaume Yziquel) really welcome comments and fair criticisms
   on the work done.


-8-  Copyright and licencing information
========================================

   This software is licenced under the version 3 of the GNU General
   Public Licence (GPL v3).


-9-  More documentation
=======================

   Documentation is rather scarce for now, but will progressively
   build up with time. You will find more information at

             http://yziquel.homelinux.org/ocaml-r