|
0
|
1 Initial Announcement: Package rdyncall released on CRAN. (Version 0.7.3)
|
|
|
2
|
|
|
3 Short Introduction
|
|
|
4 ------------------
|
|
|
5 The package facilities dynamic R bindings to the C interface of some common
|
|
|
6 shared libraries and a flexible Foreign Function Interface for the
|
|
|
7 interoperability between R and C.
|
|
|
8
|
|
|
9 Since the initial presentation of the package at Use!R 2009, a number of
|
|
|
10 improvements have been done to rdyncall, the low-level DynCall libraries
|
|
|
11 and the build system for an official release on CRAN.
|
|
|
12
|
|
|
13 Overview
|
|
|
14 --------
|
|
|
15 The package comprises a toolkit to work with C interfaces to native code from
|
|
|
16 within the dynamic R interpreter without the need for C wrapper compilation:
|
|
|
17
|
|
|
18 - Dynamic R bindings to some common C shared libraries, across platforms.
|
|
|
19 - Foreign Function Interface that supports almost all C arg/return types
|
|
|
20 and has built-in type-checking facility.
|
|
|
21 - Portable naming and loading of shared libraries across platforms.
|
|
|
22 - Handling of aggregate C struct and union data types.
|
|
|
23 - Wrapping of R functions as C callbacks.
|
|
|
24 - Binding of C functions to R in batches.
|
|
|
25
|
|
|
26 The intended audience for this package are developers experienced with C, that
|
|
|
27
|
|
|
28 .. need complete R bindings of C libraries.
|
|
|
29 .. want to write cross-platform portable system-level code in R.
|
|
|
30 .. need a FFI that supports almost all C fundamental types for arguments
|
|
|
31 and return types and thus does not need compilation of wrapper C code
|
|
|
32 .. want to work with C struct/union types directly in R
|
|
|
33 .. are interested in dynamic binding techniques between static and dynamic
|
|
|
34 languages and cross-platform binding strategies.
|
|
|
35
|
|
|
36
|
|
|
37 Brief Tour 1/2: Dynamic R Bindings to C Libraries
|
|
|
38 -------------------------------------------------
|
|
|
39
|
|
|
40 The dynamic binding interface consists of a single function, similar to
|
|
|
41 'library' or 'require':
|
|
|
42
|
|
|
43 > dynport(portname)
|
|
|
44
|
|
|
45 portname refers to a 'DynPort' file name that represents an R binding to a
|
|
|
46 common C interface and library.
|
|
|
47 The function the above has the side effect of attaching a newly created R name
|
|
|
48 space, populated with thin R helper objects to C entities of the underlying
|
|
|
49 C library:
|
|
|
50
|
|
|
51 - call wrapper to C functions
|
|
|
52 - symbolic constants of C macros and enums,
|
|
|
53 - type information objects for C struct and union data types.
|
|
|
54
|
|
|
55 The package contains a repository of the following DynPort files:
|
|
|
56
|
|
|
57 Port Name | Description of C Shared Library/API
|
|
|
58 ------------+-------------------------------------------------
|
|
|
59 expat | Expat XML Parser Library
|
|
|
60 GL | OpenGL 1.1 API
|
|
|
61 GLU | OpenGL Utility Library
|
|
|
62 SDL | Simple DirectMedia Layer library
|
|
|
63 SDL_image | Loading of image files (png,jpeg..)
|
|
|
64 SDL_mixer | Loading/Playing of ogg/mp3/mod music files.
|
|
|
65 SDL_ttf | Loading/Rendering of True Type Fonts.
|
|
|
66 glew | OpenGL Extension Wrangler (includes OpenGL 3.0)
|
|
|
67 gl3 | strict OpenGL 3 (untested)
|
|
|
68 R | R shared library
|
|
|
69 ode | Open Dynamics (Physics-) Engine (untested)
|
|
|
70 cuda | NVIDIA Cuda (untested)
|
|
|
71 opencl | OpenCL (untested)
|
|
|
72 stdio | C Standard Library I/O Functions
|
|
|
73
|
|
|
74 In order to use a DynPort on a host system, the shared C libraries
|
|
|
75 need to be installed first.
|
|
|
76
|
|
|
77 See manual page on 'rdyncall-demos' (type ?'rdyncall-demos') for a detailed
|
|
|
78 description of the installation notes for several libraries the above,
|
|
|
79 collected for a large range of operating-systems and OS distributions.
|
|
|
80
|
|
|
81 Since the rdyncall package is alredy ported across major R platforms, code
|
|
|
82 that uses a DynPort can run cross-platform without compilation.
|
|
|
83
|
|
|
84 Here is a small example for using the SDL and OpenGL for multimedia/3D:
|
|
|
85
|
|
|
86 -- snip
|
|
|
87
|
|
|
88 # load SDL and OpenGL bindings
|
|
|
89 dynport(SDL)
|
|
|
90 dynport(GL)
|
|
|
91
|
|
|
92 # initialize video sub-system
|
|
|
93 SDL_Init(SDL_INIT_VIDEO)
|
|
|
94
|
|
|
95 # open double-buffered OpenGL window surface
|
|
|
96 surface <- SDL_SetVideoMode(640,480,32,SDL_OPENGL+SDL_DOUBLEBUF)
|
|
|
97
|
|
|
98 # print dimension by accessing fields external C pointer to struct SDL_Surface
|
|
|
99 print( paste("dimenstion:", surface$w, "x", surface$h ))
|
|
|
100
|
|
|
101 # clear buffer
|
|
|
102 glClearColor(0.3,0.6,0.8,0)
|
|
|
103 glClear(GL_COLOR_BUFFER_BIT)
|
|
|
104
|
|
|
105 # update display
|
|
|
106 SDL_GL_SwapBuffers()
|
|
|
107
|
|
|
108 -- snap
|
|
|
109
|
|
|
110 A more detailed version including user-interface handling is available
|
|
|
111 in 'demo(SDL)'.
|
|
|
112
|
|
|
113
|
|
|
114 Brief Tour 2/2: Alternative FFI via '.dyncall'
|
|
|
115 ----------------------------------------------
|
|
|
116
|
|
|
117 The alternative foreign function interface offered by '.dyncal' has a similar
|
|
|
118 intend such as '.C'. It allows to call shared library functions directly from R,
|
|
|
119 but without additional wrapper C code needed, because it supports almost all
|
|
|
120 fundamental C data types and uses a function type signature text specification
|
|
|
121 for type-checking and flexible conversions between R and C values.
|
|
|
122
|
|
|
123 The interface is as following:
|
|
|
124
|
|
|
125 > .dyncall(address, signature, ...)
|
|
|
126
|
|
|
127 'signature' is a character string that encodes the arguments and return-type of
|
|
|
128 a C function.
|
|
|
129 Here is an example of C function from the OpenGL API:
|
|
|
130
|
|
|
131 void glClearColor(float red, float green, float blue, float alpha);
|
|
|
132
|
|
|
133 one would specify the function type via "ffff)v" as type signature and
|
|
|
134 pass additional arguments for '...':
|
|
|
135
|
|
|
136 > .dyncall(addressOf_glClearColor, "ffff)v", 0.3,0.7,1,0)
|
|
|
137
|
|
|
138 Support for pointers (low-level void and typed pointers to struct/union) and
|
|
|
139 wrapping of R functions to first-level C function pointers is also available.
|
|
|
140
|
|
|
141 -- snip
|
|
|
142
|
|
|
143 # load C math library across major platforms (Windows,Mac OS X,Linux)
|
|
|
144 mathlib <- dynfind(c("msvcrt","m","m.so.6"))
|
|
|
145
|
|
|
146 # resolve symbol 'sqrt'
|
|
|
147 x <- .dynsym(mathlib,"sqrt")
|
|
|
148
|
|
|
149 # C function call 'double sqrt(double x)' with x=144
|
|
|
150 .dyncall(x, "d)d", 144)
|
|
|
151
|
|
|
152 # .dyncall uses complex mapping of types, same works with 'integer' argument:
|
|
|
153 .dyncall(x, "d)d", 144L)
|
|
|
154
|
|
|
155 -- snap
|
|
|
156
|
|
|
157
|
|
|
158 Implementation Details
|
|
|
159 ----------------------
|
|
|
160
|
|
|
161 This package contains low-level services related to the generic invocation
|
|
|
162 of machine-code functions using official calling convention specifications
|
|
|
163 as the binary interface. A similar service exists for the oppositve direction
|
|
|
164 in order to write R functions and wrap them as first-level C function callback
|
|
|
165 pointers.
|
|
|
166
|
|
|
167 The implementation is based on libraries from the DynCall Project that
|
|
|
168 implement a small amount of code in Assembly and have to play closely
|
|
|
169 together with the calling conventions of various processor-architectures and
|
|
|
170 platforms.
|
|
|
171 The implementation can be tricky has to be done on a calling-convention
|
|
|
172 basis. The efforts legitimate this non-portsble approach due to a
|
|
|
173 very small code size and a generic machine-call solution designed for
|
|
|
174 dynamic interpreters. (total size of shared lib object in rdyncall is ~60kb )
|
|
|
175
|
|
|
176
|
|
|
177 Portability and Platforms
|
|
|
178 -------------------------
|
|
|
179
|
|
|
180 A large set of platforms and calling conventions are already supported and a
|
|
|
181 suite of testing tools ensure a stable implementation at low-level.
|
|
|
182
|
|
|
183 Processor-Architectures:
|
|
|
184 - Intel i386 32-bit and AMD 64-bit Platforms
|
|
|
185 - PowerPC 32-bit (support for callbacks on System V systems not yet implemented)
|
|
|
186 - ARM 32-bit (with support for Thumb)
|
|
|
187 - MIPS 32- and 64-bit (support for callbacks not yet implemented)
|
|
|
188 - SPARC 32-bit and 64-bit (support for callbacks not yet implemented)
|
|
|
189
|
|
|
190 The DynCall libraries are tested on Linux, Mac OS X, Windows, BSD derivates,
|
|
|
191 Solaris and more exotic platforms such as game consoles, Plan9, Haiku and Minix.
|
|
|
192 The R Package has been tested on several major 32- and 64-bit R platforms
|
|
|
193 including Windows 32/64-bit, Linux (i386,amd64,ppc,arm), NetBSD (i386,amd64),
|
|
|
194 Solaris (i386,amd64).
|
|
|
195
|
|
|
196 As of this release, no support for callbacks is available on MIPS or SPARC.
|
|
|
197 Callbacks on PowerPC 32-bit for Mac OS X work fine, for other
|
|
|
198 ELF/System V-based PowerPC systems, callbacks are not yet implemented.
|
|
|
199
|
|
|
200
|
|
|
201 Known Bugs
|
|
|
202 ----------
|
|
|
203
|
|
|
204 * PowerPC/Mac OS X 10.4: Building Universal Binaries are broken.. in particular
|
|
|
205 the as for i386 assembler.
|
|
|
206 Workaround for PowerPC users: install with "--no-multiarch" or use prebuilt
|
|
|
207 binaries built on OS X >= 10.5.
|
|
|
208
|
|
|
209 * SPARC Assembly sources are currently implemented for GNU assembler and do
|
|
|
210 not assemble using the 'fbe' Assembler tool on Solaris.
|
|
|
211
|
|
|
212
|
|
|
213 More Information
|
|
|
214 ----------------
|
|
|
215
|
|
|
216 More demos and examples are in the package.
|
|
|
217 A 20-page vignette with the title "Foreign Library Interface" is available via
|
|
|
218 > vignette("FLI")
|
|
|
219
|
|
|
220 A cross-platform audio/visual OpenGL-based demo-scene production
|
|
|
221 written in 100% pure R is available here:
|
|
|
222
|
|
|
223 http://dyncall.org/demos/soulsalicious/
|
|
|
224
|
|
|
225 A video of demo is also at the website.
|
|
|
226
|
|
|
227
|
|
|
228 The website of the DynCall Project is at
|
|
|
229
|
|
|
230 http://dyncall.org/
|
|
|
231
|
|
|
232
|
|
|
233 Help and Feedback
|
|
|
234 -----------------
|
|
|
235 The package contains new methods for dynamic binding of native code to R
|
|
|
236 that were designed to work cross-platform. Thus the package required intensive
|
|
|
237 testing on a large range of processor/OS/tool-chain combinations.
|
|
|
238 It was (and still is!) also very helpful to run tests on different
|
|
|
239 'distributions' of the same OS for checking e.g. the search algorithm for
|
|
|
240 locating shared libraries by a short name across operating-systems
|
|
|
241 (see '?dynfind' for details on this).
|
|
|
242
|
|
|
243 I am very thankful for any feedback including bug-reports, success and
|
|
|
244 failure stories or ideas of improvements. If you feel that an important
|
|
|
245 architecture, platform or build-tool is missing here please let me know too.
|
|
|
246
|
|
|
247 The DynCall authors appreciate any support for porting the DynCall libraries
|
|
|
248 and the R package e.g. remote development accounts, qemu/gxemul images,
|
|
|
249 hardware. In particular we are currently looking for the following
|
|
|
250 arch/os/compilers environment for porting the DynCall libraries and rdyncall:
|
|
|
251
|
|
|
252 - Sparc/Solaris/SunPro
|
|
|
253 - PowerPC/AIX/XL C
|
|
|
254 - MIPS/IRIX/MIPSpro
|
|
|
255
|
|
|
256 If you can help us out, please get in contact us.
|
|
|
257
|
|
|
258
|
|
|
259 ChangeLog
|
|
|
260 ---------
|
|
|
261
|
|
|
262 0.7.3: [2011-07-19] Added vignette, new ports, new tool-chain an fixes for bugs
|
|
|
263 o bugfix for Fedora/x64: added search path 'lib64' folder for 'dynfind'.
|
|
|
264 o added support for Sun make, DynCall uses Makefile.embedded.
|
|
|
265 o added sparc and sparc64 support using gcc tool-chain.
|
|
|
266 o added support for amd64 using solaris tool-chain.
|
|
|
267 o added vignette "foreign library interface".
|
|
|
268 o bugfix for solaris/x64: added search path 'amd64' folder for 'dynfind'.
|
|
|
269 o bugfix in examples for libm using 'm.so.6' besides 'm' on unix
|
|
|
270 (needed by debian 6 sid unstable)
|
|
|
271
|
|
|
272 0.7.2: [2011-04-27] Minor fixes
|
|
|
273 o added win64/mingw64 support.
|
|
|
274
|
|
|
275 0.7.1: [2011-04-26] Minor fixes
|
|
|
276 o minor Makevars fix for parallel builds.
|
|
|
277
|
|
|
278 0.7.0: [2011-04-20] Initial Release
|
|
|
279 o first upload to CRAN.
|
|
|
280
|
|
|
281
|
|
|
282 enjoy,
|
|
|
283 - Daniel
|
|
|
284
|
