OCaml-R
===================
Objective Caml bindings for the R interpreter.
Copyright 2008-2010 INRIA - Maxence Guesdon.
Contact: maxence.guesdon@inria.fr
Copyright 2009-2010 Guillaume Yziquel.
Contact: guillaume.yziquel@citycable.ch
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:
maxence.guesdon@inria.fr
You can reach Guillaume Yziquel at:
guillaume.yziquel@citycable.ch
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