Mercurial > pub > dyncall > bindings

comparison R/rdyncall/inst/doc/ANNOUNCEMENT.txt @ 0:0cfcc391201f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
initial from svn dyncall-1745
author Daniel Adler
date Thu, 19 Mar 2015 22:26:28 +0100
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:0cfcc391201f
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