annotate R/rdyncall/man/dynport.Rd @ 3:f5d4d5c2f750

- gemspec fix
author cslag
date Thu, 31 Dec 2015 20:24:53 +0100
parents 0cfcc391201f
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
1 \name{dynport}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
2 \alias{dynport}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
3 \alias{loadDynportNamespace}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
4 \title{Dynamic R Bindings to standard and common C libraries}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
5 \description{Function to bind APIs of standard and common C libraries to R via dynamically created interface environment objects
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
6 comprising R wrappers for C functions, object-like macros, enums and data types.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
7 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
8 \usage{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
9 dynport(portname, portfile=NULL,
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
10 repo=system.file("dynports",package="rdyncall") )
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
11 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
12 \arguments{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
13 \item{portname}{the name of a dynport, given as a literal or character string.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
14 \item{portfile}{\code{NULL} or character string giving a script file to parse ; \code{portname} and \code{repo} are .}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
15 \item{repo}{character string giving the path to the root of the \emph{dynport} repository.}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
16 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
17 \details{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
18 \code{dynport} offers a convenient method for binding entire C libraries to R.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
19 This mechanism runs cross-platform and uses dynamic linkage but it implies
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
20 that the run-time library of a choosen binding need to be preinstalled in the system.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
21 Depending on the OS, the run-time libraries may be preinstalled or require manual installation.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
22 See \link{rdyncall-demos} for OS-specific installation notes for several C libraries.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
23
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
24 The binding method is data-driven using platform-portable specifications named \emph{DynPort} files.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
25 DynPort files are stored in a repository that is installed as part of the package installation.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
26 When \code{dynport} processes a \emph{DynPort} file given by \code{portname},
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
27 an environment object is created, populated with R wrapper and helper objects
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
28 that make up the interface to the C library, and attached to the search path with the name \code{dynport:<PORTNAME>}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
29 Unloading of previously loaded dynport environments is achieved via \code{detach(dynport:<PORTNAME>)}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
30
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
31 Up to \pkg{rdyncall} version 0.7.4, R name space objects were used as containers as described in the article \emph{Foreign Library Interface}, thus
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
32 dynport \sQuote{packages} appeared as \code{"package:<PORTNAME>"} on the search path. The mechanism to create synthesized R packages at run-time
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
33 required the use of \code{.Internal} calls.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
34 But since the use of internal R functions is not permitted for packages distributed on CRAN we downgraded the package to use ordinary environment
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
35 objects starting with version 0.7.5 until a public interface for the creation of R namespace objects is available.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
36
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
37 The following gives a list of currently available \emph{DynPorts}:
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
38 \tabular{ll}{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
39 \strong{DynPort name/C Library} \tab \strong{Description} \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
40 \code{expat} \tab Expat XML Parser Library \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
41 \code{GL} \tab OpenGL 1.1 API \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
42 \code{GLU} \tab OpenGL Utility Library \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
43 \code{GLUT} \tab OpenGL Utility Toolkit Library \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
44 \code{SDL} \tab Simple DirectMedia Layer library \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
45 \code{SDL_image} \tab Loading of image files (png,jpeg..) \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
46 \code{SDL_mixer} \tab Loading/Playing of ogg/mp3/mod music files. \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
47 \code{SDL_ttf} \tab Loading/Rendering of True Type Fonts. \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
48 \code{SDL_net} \tab Networking library. \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
49 \code{glew} \tab OpenGL Extension Wrangler (includes OpenGL 3.0) \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
50 \code{glfw} \tab OpenGL Windowing/Setup Library \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
51 \code{gl3} \tab strict OpenGL 3 (untested) \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
52 \code{R} \tab R shared library \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
53 \code{ode} \tab Open Dynamics (Physics-) Engine (untested) \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
54 \code{cuda} \tab NVIDIA Cuda (untested) \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
55 \code{csound} \tab Sound programming language and library \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
56 \code{opencl} \tab OpenCL (untested) \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
57 \code{stdio} \tab C Standard Library I/O Functions \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
58 \code{glpk} \tab GNU Linear Programming Kit \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
59 \code{EGL} \tab Embedded Systems Graphics Library \cr
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
60 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
61
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
62 As of the current implementation \emph{DynPort} files are R scripts
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
63 that perform up to three tasks:
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
64
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
65 \itemize{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
66 \item Functions (and pointer-to-function variables) are mapped via \code{\link{dynbind}} and a description of the C library using a \emph{library signatures}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
67 \item Symbolic names are assigned to its values for object-like macro defines and C enum types.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
68 \item Run-time type-information objects for aggregate C data types (struct and union) are registered via \code{\link{parseStructInfos}} and \code{\link{parseUnionInfos}}.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
69 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
70
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
71 The file path to the \emph{DynPort} file is derived from
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
72 \code{portname} per default. This would refer to \code{"<repo>/<portname>.R"}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
73 where \code{repo} usually refers to the initial \emph{DynPort} repository
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
74 located at the sub-folder \code{"dynports/"} of the package.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
75 If \code{portfile} is given, then this value is taken as file path (usually
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
76 for testing purpose).
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
77
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
78 A tool suite, comprising AWK (was boost wave), GCC Preprocessor, GCC-XML and XSLT, was used to generate the available \emph{DynPort} files automatically
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
79 by extracting type information from C library header files.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
80
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
81 In a future release, the DynPort format will be changed to
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
82 a language-neutral text file document. For the interested reader:
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
83 A first prototyp is currently available in an FFI extension to the Lua
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
84 programming language (see \code{luadyncall} subversion sub-tree).
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
85 A third revision (including function types in call signatures, bitfields, arrays, etc..)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
86 is currently in development.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
87 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
88 \references{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
89 Adler, D. (2012) \dQuote{Foreign Library Interface}, \emph{The R Journal}, \bold{4(1)}, 30--40, June 2012.
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
90 \url{http://journal.r-project.org/archive/2012-1/RJournal_2012-1_Adler.pdf}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
91
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
92 Adler, D., Philipp, T. (2008) \emph{DynCall Project}. \url{http://dyncall.org}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
93
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
94 Clark, J. (1998). expat - XML Parser Toolkit. \url{http://expat.sourceforge.net}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
95
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
96 Ikits, M. and Magallon, M. (2002). The OpenGL Extension Wrangler Library. \url{http://glew.sourceforge.net}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
97
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
98 Latinga, S. (1998). The Simple DirectMedia Layer Library. \url{http://www.libsdl.org}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
99
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
100 Segal, M. and Akeley, K. (1992). The OpenGL Graphics System. A Specification, Version 1.0. \url{http://www.opengl.org}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
101
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
102 Smith, R. (2001). Open Dynamics Engine. \url{http://www.ode.org}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
103 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
104 \examples{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
105 \donttest{
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
106 # Using SDL and OpenGL in R
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
107 dynport(SDL)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
108 dynport(GL)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
109 # Initialize Video Sub-system
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
110 SDL_Init(SDL_INIT_VIDEO)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
111 # Initialize Screen with OpenGL Context and Double Buffering
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
112 SDL_SetVideoMode(320,256,32,SDL_OPENGL+SDL_DOUBLEBUF)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
113 # Clear Color and Clear Screen
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
114 glClearColor(0,0,1,0) # blue
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
115 glClear(GL_COLOR_BUFFER_BIT)
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
116 # Flip Double-Buffer
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
117 SDL_GL_SwapBuffers()
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
118 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
119 }
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
120 \keyword{programming}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
121 \keyword{interface}
0cfcc391201f initial from svn dyncall-1745
Daniel Adler
parents:
diff changeset
122