Mercurial > pub > dyncall > bindings

comparison R/rdyncall/man/rdyncall.Rd @ 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 \name{rdyncall}
2 \docType{package}
3 \alias{rdyncall}
4 \alias{rdyncall-package}
5 \title{Improved Foreign Function Interface (FFI) and Dynamic Bindings to C Libraries (e.g. OpenGL) }
6 \description{The package provides a cross-platform framework for dynamic binding of
7 C libraries using a flexible Foreign Function Interface (FFI).
8 The FFI supports almost all fundamental C types, multiple calling conventions,
9 symbolic access to foreign C struct/union data types and wrapping of R functions
10 as C callback function pointers.
11 Dynamic bindings to shared C libraries are data-driven by cross-platform binding specification
12 using a compact plain text format ; an initial repository of bindings to a couple of
13 common C libraries (OpenGL, SDL, Expat, glew, CUDA, OpenCL, ODE, R) comes with the package.
14 The package includes a variety of technology demos and OS-specific notes for installation of shared libraries.
15 }
16 \details{
17 \pkg{rdyncall} offers a stack of interoperability technologies for working
18 with foreign compiled languages using cross-platform portable abstraction
19 methods.
20
21 For R application development, the package facilitates direct access from R
22 to the C Application Programming Interface (API) of common libraries.
23 This enables a new style of development: R applications can use
24 low-level services of portable C libraries.
25 System-level code can be implemented in R without leaving the language.
26 C APIs can be explored from within the R interpreter.
27 Moving the R code from one platform to the other does not involve
28 recompilation.
29 Ofcourse, the run-time libraries need to be installed using a standard
30 procedure of the target Operating-System Distribution.
31 See \link{rdyncall-demos} for details on this.
32
33 For R core development and research, the package provides an improved Foreign
34 Function Interface (FFI) that can be used to call arbitrary
35 foreign precompiled C code without the need for additional
36 compilation of wrapper code. The back-end library is extendable with new
37 calling conventions (such as Fortran,Pascal,COM,etc.. - which has not been
38 the focus as of this release, but might be supported officially in the near
39 futurue).
40 Basic type-safety checks for argument passing and framework support for
41 working with foreign C data types such as pointers, arrays, structs and
42 wrapping of R functions into first-level C callback function pointers
43 round up this framework.
44 }
45 \section{Overview}{
46 \itemize{
47 \item Flexible FFI with support for almost all C types, type-safety checks and multiple calling conventions. See \code{\link{.dyncall}}.
48 \item Loading of shared libraries with \emph{automatic unload management} and using direct access to OS linker. See \code{\link{.dynload}}.
49 \item Cross-platform naming and loading of shared libraries. See \code{\link{dynfind}}.
50 \item Binding C library functions via thin call wrappers. See \code{\link{dynbind}}.
51 \item Handling of foreign C pointer, array and struct/union data types. See \code{\link{packing}} and \code{\link{struct}}.
52 \item Dynamic wrapping of R functions as C function pointers to be used in C callbacks. See \code{\link{new.callback}}.
53 \item Dynamic bindings to standard and common C libraries and APIs (functions, variables, macro constants, enums, struct and union types). See \code{\link{dynport}}.
54 }
55 }
56 \section{Getting Started}{
57 Several demos ranging from simple FFI calls to the C standard math library up to more complex 3D OpenGL/SDL Applications are available.
58 See \code{demos(package="rdyncall")} for an overview.
59 Some demos require shared C libraries to be installed in the system. Please read \link{rdyncall-demos} for details.
60 }
61 \section{Supported Platforms}{
62 The low-level implementation is mainly based on libraries from the DynCall
63 Project (\url{http://dyncall.org}). The library suite is distributed
64 as part of the package source tree.
65
66 The dyncall and dyncallback libraries implement generic low-level services
67 with the help of a small amount of hand-written assembly code and
68 careful modeling of the target machine's calling sequence
69 for each platform to support.
70
71 As of version 0.6, the following processor architectures are supported:
72
73 \itemize{
74 \item Intel i386 32-bit and AMD 64-bit Platforms
75 \item ARM 32-bit (OABI, EABI and ARMHF ABI with support for Thumb)
76 \item PowerPC 32-bit (support for callbacks not implemented for Linux/BSD)
77 \item MIPS 32- and 64-bit (support for callbacks not yet implemented)
78 \item SPARC 32- and 64-bit (support for callbacks not yet implemented)
79 }
80
81 The DynCall libraries are tested on Linux, Mac OS X, Windows, BSD derivates
82 and more exotic platforms such as game consoles and Plan9.
83 Please see the details on portability for \link{dyncall}, \link{dyncallback} and \link{dynload}
84 and the official DynCall manual for full details of the back-end.
85 The R Package has been tested on several major R platforms.
86 The following gives a list of comments on platforms about the status of this package.
87
88 \tabular{l}{
89 \cr
90 Linux Debian 4/ppc32 , R-2.4.0 : ok, but no callbacks. \cr
91 Linux Debian 5/arm , R-2.7.0 : ok, SDL not tested. \cr
92 Linux Debian 6/x86 , R-2.12.2: ok. \cr
93 Linux Debian 6/x64 , R-2.12.2: ok. \cr
94 Linux Ubuntu 10/armv7, R-2.14 : ok. \cr
95 Linux Fedora 14/x86 : ok. \cr
96 Linux Ubuntu 12/i386 , R-2.15.1: ok. \cr
97 Mac OS X 10.4/ppc , R-2.10.0: ok. \cr
98 Mac OS X 10.6/x86 , R-2.12.2: ok. \cr
99 Mac OS X 10.6/x64 , R-2.12.2: ok. \cr
100 Mac OS X 10.7/x64 , R-2.15.1: ok. \cr
101 NetBSD 5.0/x86 : ok. \cr
102 NetBSD 5.1/x64 : ok. \cr
103 OpenBSD 4.8/x64 , R-2.7.0 : SDL failed. \cr
104 Windows XP/x86 , R-2.12.2: ok. \cr
105 Windows 7/x86 , R-2.12.2: ok. \cr
106 Windows 7/x64 , R-2.12.2: ok, use correct 64-bit SDL DLL, SDL extension not tested - see \link{rdyncall-demos}) \cr
107 FreeBSD 8.2/x86 : build ok, no tests made for X11. \cr
108 }
109 }
110 \references{
111 Adler, D. (2012) \dQuote{Foreign Library Interface}, \emph{The R Journal}, \bold{4(1)}, 30--40, June 2012.
112 \url{http://journal.r-project.org/archive/2012-1/RJournal_2012-1_Adler.pdf}
113
114 Adler, D., Philipp, T. (2008) \emph{DynCall Project}.
115 \url{http://dyncall.org}
116 }
117 \examples{
118 \donttest{
119 # multimedia example
120 # load dynports for OpenGL, Simple DirectMedia library
121 # globals:
122 surface <- NULL
123 # init SDL and OpenGL
124 init <- function()
125 {
126 dynport(SDL)
127 dynport(GL)
128 if ( SDL_Init(SDL_INIT_VIDEO) != 0 ) stop("SDL_Init failed")
129 surface <<- SDL_SetVideoMode(320,240,32,SDL_DOUBLEBUF+SDL_OPENGL)
130 cat("surface dimension:", surface$w, "x",surface$h,sep="")
131 }
132 # draw blue screen
133 updateSurface <- function(t)
134 {
135 glClearColor(0,0,t \%\% 1,0)
136 glClear(GL_COLOR_BUFFER_BIT+GL_DEPTH_BUFFER_BIT)
137 SDL_GL_SwapBuffers()
138 }
139 # wait till close
140 mainloop <- function()
141 {
142 quit <- FALSE
143 evt <- new.struct(SDL_Event)
144 base <- SDL_GetTicks() / 1000
145 t <- 0
146 while(!quit) {
147 updateSurface(t)
148 while(SDL_PollEvent(evt)) {
149 if ( evt$type == SDL_QUIT ) quit <- TRUE
150 }
151 now <- SDL_GetTicks() / 1000
152 t <- now - base
153 }
154 }
155 init()
156 mainloop()
157 }
158 }
159 \keyword{programming}
160 \keyword{interface}
161