PageRenderTime 20ms CodeModel.GetById 15ms app.highlight 2ms RepoModel.GetById 1ms app.codeStats 0ms

/trunk/Doc/Manual/R.html

#
HTML | 180 lines | 135 code | 43 blank | 2 comment | 0 complexity | 576bdabafab6ca1224e0268ed1e53705 MD5 | raw file
  1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  2<html>
  3<head>
  4<title>SWIG and R</title>
  5<link rel="stylesheet" type="text/css" href="style.css">
  6</head>
  7
  8<body bgcolor="#ffffff">
  9<H1><a name="R"></a>35 SWIG and R</H1>
 10<!-- INDEX -->
 11<div class="sectiontoc">
 12<ul>
 13<li><a href="#R_nn2">Bugs</a>
 14<li><a href="#R_nn3">Using R and SWIG</a>
 15<li><a href="#R_nn4">Precompiling large R files</a>
 16<li><a href="#R_nn5">General policy</a>
 17<li><a href="#R_language_conventions">Language conventions</a>
 18<li><a href="#R_nn6">C++ classes</a>
 19<li><a href="#R_nn7">Enumerations</a>
 20</ul>
 21</div>
 22<!-- INDEX -->
 23
 24
 25
 26<p>
 27R is a GPL'ed open source statistical and plotting environment.
 28Information about R can be found at <a
 29href="http://www.r-project.org/">www.r-project.org</a>.
 30
 31The R bindings are under active development.  They have been used to
 32compile and run an R interface to QuantLib running on Mandriva Linux
 33with gcc. The R bindings also work on Microsoft Windows using Visual C++.
 34</p>
 35
 36<H2><a name="R_nn2"></a>35.1 Bugs</H2>
 37
 38
 39<p>
 40Currently the following features are not implemented or broken:
 41</p>
 42
 43<ul>
 44<li>Garbage collection of created objects
 45<li>C Array wrappings
 46</ul>
 47
 48<H2><a name="R_nn3"></a>35.2 Using R and SWIG</H2>
 49
 50
 51<p>
 52To use R and SWIG in C mode, execute the following commands where
 53example.c is the name of the file with the functions in them
 54</p>
 55
 56<div class="shell">
 57<pre>
 58swig -r example.i
 59R CMD SHLIB example_wrap.c example.c
 60</pre>
 61</div>
 62
 63<p>
 64The corresponding options for C++ mode are
 65</p>
 66
 67<div class="shell">
 68<pre>
 69swig -c++ -r -o example_wrap.cpp example.i
 70R CMD SHLIB example_wrap.cpp example.cpp
 71</pre>
 72</div>
 73
 74<p>
 75Note that R is sensitive to the names of the files.
 76The name of the wrapper file must be the
 77name of the library unless you use the -o option to R when building the library, for example:
 78</p>
 79
 80<div class="shell">
 81<pre>
 82swig -c++ -r -o example_wrap.cpp example.i
 83R CMD SHLIB -o example.so example_wrap.cpp example.cpp
 84</pre>
 85</div>
 86
 87<p>
 88R is also sensitive to the name of the file 
 89extension in C and C++ mode. In C++ mode, the file extension must be .cpp
 90rather than .cxx for the R compile command to recognize it. If your C++ code is 
 91in a file using something other than a .cpp extension, then it may still work using PKG_LIBS:
 92</p>
 93
 94<div class="shell">
 95<pre>
 96swig -c++ -r -o example_wrap.cpp example.i
 97PKG_LIBS="example.cxx" R CMD SHLIB -o example example_wrap.cpp
 98</pre>
 99</div>
100
101<p>
102The commands produces two files.  A dynamic shared object file called
103example.so, or example.dll, and an R wrapper file called example.R.  To load these
104files, start up R and type in the following commands
105</p>
106
107<div class="shell">
108<pre>
109dyn.load(paste("example", .Platform$dynlib.ext, sep=""))
110source("example.R")
111cacheMetaData(1)
112</pre>
113</div>
114
115The cacheMetaData(1) will cause R to refresh its object tables.
116Without it, inheritance of wrapped objects may fail.
117
118<p>
119These two files can be loaded in any order
120</p>
121
122<H2><a name="R_nn4"></a>35.3 Precompiling large R files</H2>
123
124
125In cases where the R file is large, one make save a lot of loading
126time by precompiling the R wrapper.  This can be done by creating the
127file makeRData.R which contains the following
128
129<pre>
130source('BigFile.R')
131save(list=ls(all=TRUE),file="BigFile.RData", compress=TRUE)
132q(save="no")
133</pre>
134
135This will generate a compiled R file called BigFile.RData that
136will save a large amount of loading time.
137
138
139
140<H2><a name="R_nn5"></a>35.4 General policy</H2>
141
142
143<p>
144The general policy of the module is to treat the C/C++ as a basic
145wrapping over the underlying functions and rely on the R type system
146to provide R syntax.
147</p>
148
149<H2><a name="R_language_conventions"></a>35.5 Language conventions</H2>
150
151
152<p>
153getitem and setitem use C++ conventions (i.e. zero based indices). [<-
154and [ are overloaded to allow for R syntax (one based indices and
155slices)
156</p>
157
158<H2><a name="R_nn6"></a>35.6 C++ classes</H2>
159
160
161<p>
162C++ objects are implemented as external pointer objects with the class
163being the mangled name of the class. The C++ classes are encapsulated
164as an SEXP with an external pointer type. The class is the mangled
165name of the class. The nice thing about R is that is allows you to
166keep track of the pointer object which removes the necessity for a lot
167of the proxy class baggage you see in other languages.
168</p>
169
170<H2><a name="R_nn7"></a>35.7 Enumerations</H2>
171
172
173<p>
174enumerations are characters which are then converted back and forth to
175ints before calling the C routines. All of the enumeration code is
176done in R.
177</p>
178
179</body>
180</html>