README

   1  -*- mode: text -*-
   2
   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).
   6
   7
   8 * License
   9
  10 See the file COPYING in the top level directory.
  11
  12 * Interfacing Common Lisp and R
  13
  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).
  20
  21
  22 * Quick start
  23
  24 ** Requirements
  25
  26 Common Lisp Implementation:
  27
  28 A. (WORKS!) SBCL 1.0 and later (known, might work on earlier versions)
  29
  30 B. (Goal, but not working yet):  CLISP is a target, but there are a
  31    few configuration issues to resolve.
  32
  33 You will need the following libraries available:
  34
  35 1. ASDF   (system definition facility, for loading packages)
  36 2. CFFI   (Common foreign function interface: later than CFFI-060526)
  37                                                         (May 26 2006)
  38 3. RCLG   (this library)
  39
  40
  41
  42 Once you have these, then the simple way to get started is to:
  43
  44 1. add rclg.asd to the ASDF systems path.
  45 2. See  rclg-demo.lisp  for getting started.  It has incantations for:
  46    a. compiling and loading cffi
  47    b. compiling and loading rclg
  48    c. basic R functions
  49    d. basic data conversion.
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61 * Past and possibly present "Issues"
  62
  63 1. Need to get it working ("again") with CLISP.
  64
  65 ** From the file formerly known as NOTES/06032006.rif (date contained)
  66
  67 1. In the current version of cffi, the variable names get wrapped in
  68    asterisks, so
  69
  70 (defcvar "R_CStackLimit"  :unsigned-long)  ;; :unsigned long
  71 (defcvar "R_SignalHandlers" :unsigned-long) ;; :unsigned long
  72
  73    make variables named *R-CSTACKLIMIT* and *R-SIGNALHANDLERS*
  74
  75 2. In "rclg-demo.lisp", I wanted to mention that rnb doesn't mean "no
  76    blocking", it means "no backconverting".  It's not that it doesn't
  77    protect --- it does all the normal protection, it just doesn't
  78    convert the result back from R to Lisp.  It's to avoid pushing big
  79    objects back and forth through the pipe needlessly.  In some sense,
  80    rnb is what you'd use to do an R assignment, but you get a CL name
  81    for whatever it is rather than an R name.
  82
  83 3. At this point, it seems like setting *R-SIGNALHANDLERS* to 0 is
  84    preventing an immediate seg fault.  So that's good.
  85
  86 4. We are still getting errors related to the stack, and I can't
  87    actually *find* anything.  Whenever I try to find a function, I'm
  88    getting back "Unbound value".  I don't know for sure that this is
  89    related to the stack problems.  The equivalent C program does find
  90    things.  I've put the C and Lisp programs in subdirectory
  91    simple-test.  I'm not sure whether want to be using Rf_findVar or
  92    Rf_findFun.
  93
  94 5. I'm not sure 100% I'm handling the stack correctly.  On the mailing
  95    list, it suggests setting R_CStackLimit = -1.  However, CFFI
  96    believes that *R-CSTACKLIMIT* is an unsigned long, and won't let me
  97    set it to -1.  I'm seting it to the two's complement value, which
  98    is 429476295.  I think this is OK, but tell me if it isn't.
  99
 100 6. It is worth noting that Rf_initEmbeddedR *will* change the value of
 101    R_CStackLimit.  So it is important to set signalhandlers to 0
 102    BEFORE starting R, and then probably set StackLimit afterwards.
 103    I've played a bit with going into the R source and turning off the
 104    stuff in the initialization that sets it to some value, but that
 105    produced an infinite loop of stack checks.
 106
 107 7. I had to make a bunch of changes so that all the built-in file
 108    constants match my directory structure.  I think it's set up so you
 109    only have to change the path in one place now (the defvar of
 110    *R-HOME-STR* in rclg-load).
 111
 112 ** From the file formerly known as src/NOTES
 113
 114
 115
 116 1.R SEXP
 117
 118 rclg-types:sexptype
 119   "Gets the sexptype of an robj.  WARNING: ASSUMES THAT THE TYPE
 120 IS STORED IN THE LOW ORDER 5 BITS OF THE SXPINFO-STRUCT, AND THAT
 121 IT CAN BE EXTRACTED VIA A 'mod 32' OPERATION!  MAY NOT BE PORTABLE."
 122
 123 2. NAs
 124
 125
 126 (defvar *r-NA-internal* -2147483648) ;;  PLATFORM SPECIFIC HACK!!!
 127
 128
 129 3. SBCL-specific hacks
 130
 131 rclg-convert:sequence-to-robj is sbcl-specific!  Should think about
 132 removing rclg-helpers for more portability, if it's fast enough.
 133
 134 Consolidate with-gensyms somewhere?
 135
 136 We only get r-names and r-dims back at the "toplevel" call to r.
 137 Should rnb protect?  Don't think we're using poss-sexp for anything...
 138
 139 with-r-traps is SBCL specific.
 140 Multiprocessing stuff (with mutex) is SBCL specific.
 141
 142 In R, memory.c contains allocVector.  Looks like it *should* be doable
 143 to directly pass vectors around (non-portably, of course).
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156 * Comparison of Implementation and Design of RCLG, CLSR.
 157
 158 ** Tools to initialize R
 159
 160 1. rclg-init : start-rclg update-R
 161                start-rclg-update-thread stop-rclg-update-thread
 162                with-R-traps with-r-mutex
 163
 164    initialize and maintain the R evaluator process.
 165
 166 2. rclg-load : load-r-libraries  (FFI initializer, not FFI <-> CL specifier.
 167
 168    initialize environment and load libraries.
 169
 170 3. clsr-loader: uffi-load-r-library (package: clsr)
 171
 172 4. clsr : instantiates an R process.
 173
 174 ** Tools to handle R data structures and SEXPs in CL
 175
 176 1. rclg-access  : r-setcar, r-car, r-cdr
 177                   (R SEXP content <-> CL data)
 178
 179    low-level defuns for data transport between R SEXPs and CL.
 180
 181 2. rclg-convert : convert-to-r, convert-from-r, *r-na*, r-nil, r-bound
 182                   (data type and data conversion)
 183
 184 3. rclg-types : SEXP data structure information.  exports types, print method.
 185
 186    structures and objects for R internal types
 187
 188 4. clsr-rref : High level R SEXP data structures and mappings
 189
 190 5. clsr-sxp : SEXP data structures and mappings
 191
 192 ** Mappings:  Name (Function/variable), object registry
 193
 194 1. rclg-control : r (internal: rname-to-robj, rname-to-rfun
 195
 196    primary interface to R evaluator
 197
 198 2. clsr-objects : tracks created R objects  in CL (reference counter).
 199
 200
 201 ** R evaluation
 202
 203 1. rclg-control : r (converts results),
 204                   rnb (uneval'd R object, unprotected)
 205
 206 1. rclg-parse-objects : tools to handle string commands.
 207
 208
 209 ** internal FFI
 210
 211 1. rclg-foreigns : maps libR to CL
 212
 213 ** CL tools (some R, some general)
 214
 215 1. rclg-utils : with-gensyms, over-column-major-indices, to-list, to-vector