what needs to be done
[rclg.git] / README
blobda900341ba55dfc7061792c5e7fc2f1f934937a4
1  -*- mode: text -*-
3 (we are really in muse mode; but most people don't have it readily
4 available and we aren't forcing the use of Emacs/muse.   M-x muse-mode
5 makes reading easier IMHO).
8 * License 
10 See the file COPYING in the top level directory.
12 * Interfacing Common Lisp and R
14 This library considers multiple approaches for connecting Common Lisp
15 and R, particularly for embedding R within CL.  CLSR also attempts to
16 do the reverse.  RCL is a third approach, which provides more
17 porcelain around the plumbing.  RCLG also tries to use R with the
18 threaded SBCL capability.  All of this will be commented on later (in
19 time, in this file).
22 * Quick start
24 ** Requirements
26 You will need the following libraries available:
28 1. ASDF   (system definition facility, for loading packages)
29 2. CFFI   (Common foreign function interface: later than CFFI-060526)
30                                                         (May 26 2006)
31 3. RCLG   (this library)
35 Once you have these, then the simple way to get started is to:
37 1. add rclg.asd to the ASDF systems path.
38 2. See  rclg-demo.lisp  for getting started.  It has incantations for:
39    a. compiling and loading cffi
40    b. compiling and loading rclg
41    c. basic R functions
42    d. basic data conversion.
53 * Past and possibly present "Issues"
55 ** From the file formerly known as NOTES/06032006.rif (date contained)
57 1. In the current version of cffi, the variable names get wrapped in
58    asterisks, so
60 (defcvar "R_CStackLimit"  :unsigned-long)  ;; :unsigned long
61 (defcvar "R_SignalHandlers" :unsigned-long) ;; :unsigned long
63    make variables named *R-CSTACKLIMIT* and *R-SIGNALHANDLERS*
65 2. In "rclg-demo.lisp", I wanted to mention that rnb doesn't mean "no
66    blocking", it means "no backconverting".  It's not that it doesn't
67    protect --- it does all the normal protection, it just doesn't
68    convert the result back from R to Lisp.  It's to avoid pushing big
69    objects back and forth through the pipe needlessly.  In some sense,
70    rnb is what you'd use to do an R assignment, but you get a CL name
71    for whatever it is rather than an R name.
73 3. At this point, it seems like setting *R-SIGNALHANDLERS* to 0 is
74    preventing an immediate seg fault.  So that's good.
76 4. We are still getting errors related to the stack, and I can't
77    actually *find* anything.  Whenever I try to find a function, I'm
78    getting back "Unbound value".  I don't know for sure that this is
79    related to the stack problems.  The equivalent C program does find
80    things.  I've put the C and Lisp programs in subdirectory
81    simple-test.  I'm not sure whether want to be using Rf_findVar or
82    Rf_findFun.
84 5. I'm not sure 100% I'm handling the stack correctly.  On the mailing
85    list, it suggests setting R_CStackLimit = -1.  However, CFFI
86    believes that *R-CSTACKLIMIT* is an unsigned long, and won't let me
87    set it to -1.  I'm seting it to the two's complement value, which
88    is 429476295.  I think this is OK, but tell me if it isn't.
90 6. It is worth noting that Rf_initEmbeddedR *will* change the value of
91    R_CStackLimit.  So it is important to set signalhandlers to 0
92    BEFORE starting R, and then probably set StackLimit afterwards.
93    I've played a bit with going into the R source and turning off the
94    stuff in the initialization that sets it to some value, but that
95    produced an infinite loop of stack checks.
97 7. I had to make a bunch of changes so that all the built-in file
98    constants match my directory structure.  I think it's set up so you
99    only have to change the path in one place now (the defvar of
100    *R-HOME-STR* in rclg-load).
102 ** From the file formerly known as src/NOTES
106 1.R SEXP
108 rclg-types:sexptype
109   "Gets the sexptype of an robj.  WARNING: ASSUMES THAT THE TYPE
110 IS STORED IN THE LOW ORDER 5 BITS OF THE SXPINFO-STRUCT, AND THAT
111 IT CAN BE EXTRACTED VIA A 'mod 32' OPERATION!  MAY NOT BE PORTABLE."
113 2. NAs
116 (defvar *r-NA-internal* -2147483648) ;;  PLATFORM SPECIFIC HACK!!!
119 3. SBCL-specific hacks
121 rclg-convert:sequence-to-robj is sbcl-specific!  Should think about
122 removing rclg-helpers for more portability, if it's fast enough.
124 Consolidate with-gensyms somewhere?
126 We only get r-names and r-dims back at the "toplevel" call to r.
127 Should rnb protect?  Don't think we're using poss-sexp for anything...
129 with-r-traps is SBCL specific.  
130 Multiprocessing stuff (with mutex) is SBCL specific.
132 In R, memory.c contains allocVector.  Looks like it *should* be doable
133 to directly pass vectors around (non-portably, of course).
146 * Comparison of Implementation and Design of RCLG, CLSR.
148 ** Tools to initialize R
150 1. rclg-init : start-rclg update-R
151                start-rclg-update-thread stop-rclg-update-thread 
152                with-R-traps with-r-mutex
154    initialize and maintain the R evaluator process. 
156 2. rclg-load : load-r-libraries  (FFI initializer, not FFI <-> CL specifier.
158    initialize environment and load libraries.
160 3. clsr-loader: uffi-load-r-library (package: clsr)
162 4. clsr : instantiates an R process.
164 ** Tools to handle R data structures and SEXPs in CL
166 1. rclg-access  : r-setcar, r-car, r-cdr
167                   (R SEXP content <-> CL data)
169    low-level defuns for data transport between R SEXPs and CL. 
171 2. rclg-convert : convert-to-r, convert-from-r, *r-na*, r-nil, r-bound
172                   (data type and data conversion)
174 3. rclg-types : SEXP data structure information.  exports types, print method.
176    structures and objects for R internal types
178 4. clsr-rref : High level R SEXP data structures and mappings
180 5. clsr-sxp : SEXP data structures and mappings
182 ** Mappings:  Name (Function/variable), object registry
184 1. rclg-control : r (internal: rname-to-robj, rname-to-rfun
186    primary interface to R evaluator
188 2. clsr-objects : tracks created R objects  in CL (reference counter).
191 ** R evaluation
193 1. rclg-control : r (converts results),
194                   rnb (uneval'd R object, unprotected)
196 1. rclg-parse-objects : tools to handle string commands.
199 ** internal FFI
201 1. rclg-foreigns : maps libR to CL
203 ** CL tools (some R, some general)
205 1. rclg-utils : with-gensyms, over-column-major-indices, to-list, to-vector