| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <head> |
| <title>SWIG and R</title> |
| <link rel="stylesheet" type="text/css" href="style.css"> |
| <meta http-equiv="content-type" content="text/html; charset=UTF-8"> |
| </head> |
| |
| <body bgcolor="#ffffff"> |
| <H1><a name="R">33 SWIG and R</a></H1> |
| <!-- INDEX --> |
| <div class="sectiontoc"> |
| <ul> |
| <li><a href="#R_nn2">Bugs</a> |
| <li><a href="#R_nn3">Using R and SWIG</a> |
| <li><a href="#R_nn4">Precompiling large R files</a> |
| <li><a href="#R_nn5">General policy</a> |
| <li><a href="#R_language_conventions">Language conventions</a> |
| <li><a href="#R_nn6">C++ classes</a> |
| <ul> |
| <li><a href="#R_class_examples">Examples</a> |
| </ul> |
| <li><a href="#R_nn7">Enumerations</a> |
| </ul> |
| </div> |
| <!-- INDEX --> |
| |
| |
| |
| <p> |
| R is a GPL'ed open source statistical and plotting environment. |
| Information about R can be found at <a |
| href="http://www.r-project.org/">www.r-project.org</a>. |
| </p> |
| |
| <p> |
| The R bindings are under active development. They have been used to |
| compile and run an R interface to QuantLib running on Mandriva Linux |
| with gcc. They are also used to create the SimpleITK R package, which |
| runs on Linux and MacOS. SWIG is used to create all wrapper |
| interfaces |
| to <a href="http://http://www.simpleitk.org/">SimpleITK</a>. The R |
| bindings also work on Microsoft Windows using Visual C++. |
| </p> |
| |
| <H2><a name="R_nn2">33.1 Bugs</a></H2> |
| |
| |
| <p> |
| Currently the following features are not implemented or broken: |
| </p> |
| |
| <ul> |
| <li>Garbage collection of some created objects. Finalizers are |
| available for wrapped C++ classes and are called by the |
| garbage collection system. |
| <li>C Array wrappings |
| </ul> |
| |
| <H2><a name="R_nn3">33.2 Using R and SWIG</a></H2> |
| |
| |
| <p> |
| To use R and SWIG in C mode, execute the following commands where |
| example.c is the name of the file with the functions in them |
| </p> |
| |
| <div class="shell"> |
| <pre> |
| swig -r example.i |
| R CMD SHLIB example_wrap.c example.c |
| </pre> |
| </div> |
| |
| <p> |
| The corresponding options for C++ mode are |
| </p> |
| |
| <div class="shell"> |
| <pre> |
| swig -c++ -r -o example_wrap.cpp example.i |
| R CMD SHLIB example_wrap.cpp example.cpp |
| </pre> |
| </div> |
| |
| <p> |
| Note that R is sensitive to the names of the files. |
| The name of the wrapper file must be the |
| name of the library unless you use the -o option to R when building the library, for example: |
| </p> |
| |
| <div class="shell"> |
| <pre> |
| swig -c++ -r -o example_wrap.cpp example.i |
| R CMD SHLIB -o example.so example_wrap.cpp example.cpp |
| </pre> |
| </div> |
| |
| <p> |
| R is also sensitive to the name of the file |
| extension in C and C++ mode. In C++ mode, the file extension must be .cpp |
| rather than .cxx for the R compile command to recognize it. If your C++ code is |
| in a file using something other than a .cpp extension, then it may still work using PKG_LIBS: |
| </p> |
| |
| <div class="shell"> |
| <pre> |
| swig -c++ -r -o example_wrap.cpp example.i |
| PKG_LIBS="example.cxx" R CMD SHLIB -o example example_wrap.cpp |
| </pre> |
| </div> |
| |
| <p> |
| The commands produces two files. A dynamic shared object file called |
| example.so, or example.dll, and an R wrapper file called example.R. To load these |
| files, start up R and type in the following commands |
| </p> |
| |
| <div class="shell"> |
| <pre> |
| dyn.load(paste("example", .Platform$dynlib.ext, sep="")) |
| source("example.R") |
| cacheMetaData(1) |
| </pre> |
| </div> |
| |
| <p> |
| The cacheMetaData(1) will cause R to refresh its object tables. |
| Without it, inheritance of wrapped objects may fail. |
| These two files can be loaded in any order. |
| </p> |
| |
| <p> |
| If you are compiling code yourself (not using R itself), there are a few things to watch out for: |
| </p> |
| |
| <ul> |
| <li>The output shared library name (to the left of the file extension) MUST match the module name, or alternatively, you can also set the -package NAME command line argument. See swig -r -help for more information |
| <li>If you do not set the output file name appropriately, you might see errors like |
| <div class="shell"> |
| <pre> |
| > fact(4) |
| Error in .Call("R_swig_fact", s_arg1, as.logical(.copy), PACKAGE = "example") : |
| "R_swig_fact" not available for .Call() for package "example" |
| </pre> |
| </div> |
| <li>Make sure the architecture of the shared library(x64 for instance), matches the architecture of the R program you want to load your shared library into |
| </ul> |
| |
| <H2><a name="R_nn4">33.3 Precompiling large R files</a></H2> |
| |
| |
| <p> |
| In cases where the R file is large, one make save a lot of loading |
| time by precompiling the R wrapper. This can be done by creating the |
| file makeRData.R which contains the following |
| </p> |
| |
| <div class="code"><pre> |
| source('BigFile.R') |
| save(list=ls(all=TRUE), file="BigFile.RData", compress=TRUE) |
| q(save="no") |
| </pre></div> |
| |
| <p> |
| This will generate a compiled R file called BigFile.RData that |
| will save a large amount of loading time. |
| </p> |
| |
| <p> |
| There is no need to precompile large R files if the SWIG-generated code is being included |
| in an R package. The package infrastructure provides this service during package installation. |
| </p> |
| |
| <H2><a name="R_nn5">33.4 General policy</a></H2> |
| |
| |
| <p> |
| The general policy of the module is to treat the C/C++ as a basic |
| wrapping over the underlying functions and rely on the R type system |
| to provide R syntax. |
| </p> |
| |
| <H2><a name="R_language_conventions">33.5 Language conventions</a></H2> |
| |
| |
| <p> |
| getitem and setitem use C++ conventions (i.e. zero based indices). [<- |
| and [ are overloaded to allow for R syntax (one based indices and |
| slices) |
| </p> |
| |
| <H2><a name="R_nn6">33.6 C++ classes</a></H2> |
| |
| |
| <p> |
| Wrapping of C++ classes for R works quite well. R has a special |
| type, known as an external reference, that can be used as a pointer |
| to arbitary things, including C++ classes. The proxy layers generated |
| for other classes are not required. |
| </p> |
| |
| <p> |
| SWIG currently creates a custom hierarchy of R classes derived from the |
| external reference type and implements |
| type checking and function overloading in the R code it generates. In |
| the future we hope to utilise the built in R6 class structures. |
| </p> |
| |
| <p> |
| The R interface has the following capabilities: |
| </p> |
| <ul> |
| <li> Destructor methods are registered and called automatically by the R garbage collector. |
| <li> A range of std::vector types are converted automatically to R equivalents via the std_vector.i library. |
| <li> The $ operator is used for method access. |
| <li> Variable accessors are automatically generated and called via the $, [, [[, $<-, [<-, [[<- operators. |
| </ul> |
| |
| <H3><a name="R_class_examples">34.6.1 Examples</a></H3> |
| |
| |
| <p> |
| Consider the following simple example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| class Vehicle { |
| private: |
| int m_axles; |
| |
| public: |
| int Axles() { |
| return(m_axles); |
| } |
| |
| bool Available; |
| |
| Vehicle() { |
| Available=false; |
| m_axles=2; |
| } |
| |
| Vehicle(int ax) { |
| Available=false; |
| m_axles=ax; |
| } |
| }; |
| </pre> |
| </div> |
| |
| <p> |
| The following options are available in R: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| v1 <- Vehicle() |
| v2 <- Vehicle(4) |
| # access members |
| v1$Axles() |
| [1] 2 |
| v2$Axles |
| [1] 4 |
| v1$Available |
| [1] FALSE |
| # Set availabilty |
| v1$Available <- TRUE |
| v1$Available |
| [1] TRUE |
| </pre> |
| </div> |
| |
| <p> |
| A useful trick to determine the methods that are available is to |
| query the R method definition as follows: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| # display the methods for the class |
| getMethod("$", class(v1)) |
| |
| Method Definition: |
| |
| function (x, name) |
| { |
| accessorFuns = list(Axles = Vehicle_Axles, Available = Vehicle_Available_get) |
| vaccessors = c("Available") |
| idx = pmatch(name, names(accessorFuns)) |
| if (is.na(idx)) |
| return(callNextMethod(x, name)) |
| f = accessorFuns[[idx]] |
| if (is.na(match(name, vaccessors))) |
| function(...) { |
| f(x, ...) |
| } |
| else f(x) |
| } |
| |
| Signatures: |
| x |
| target "_p_Vehicle" |
| defined "_p_Vehicle" |
| |
| </pre> |
| </div> |
| <p> |
| The names in the <tt>accessorFuns</tt> list correspond to class methods while names in the <tt>vaccessors</tt> section |
| correspond to variables that may be modified. |
| </p> |
| <H2><a name="R_nn7">33.7 Enumerations</a></H2> |
| |
| |
| <p> |
| R doesn't have a native enumeration type. Enumerations are represented |
| as character strings in R, with calls to R functions that convert back |
| and forth between integers. |
| </p> |
| |
| <p> |
| The details of enumeration names and contents are stored in hidden R |
| environments, which are named according the the enumeration name - for |
| example, an enumeration colour: |
| </p> |
| |
| <div class="code"><pre> |
| enum colour { red=-1, blue, green = 10 }; |
| </pre></div> |
| |
| <p> |
| will be initialized by the following call in R: |
| </p> |
| |
| <div class="code"><pre> |
| defineEnumeration("_colour", |
| .values=c("red" = .Call('R_swig_colour_red_get',FALSE, PACKAGE='enum_thorough'), |
| "blue" = .Call('R_swig_colour_blue_get',FALSE, PACKAGE='enum_thorough'), |
| "green" = .Call('R_swig_colour_green_get',FALSE, PACKAGE='enum_thorough'))) |
| </pre></div> |
| |
| <p> |
| which will create an environment named <tt>.__E___colour</tt>. The enumeration |
| values are initialised via calls to C/C++ code, allowing complex |
| values for enumerations to be used. Calls to the C/C++ code require |
| the compiled library to be loaded, so a <tt>delayedAssign</tt> is employed |
| within <tt>defineEnumeration</tt> in order to allow the code to be easily used in R |
| packages. |
| </p> |
| |
| <p> |
| The user typically does not need to access the enumeration lookup |
| functions or know the name of the enumeration type used by |
| R. Attributes containing the type information are attached by swig to |
| functions requiring enumeration arguments or returning enumeration |
| values, and those attributes are used to identify and access the |
| appropriate environments and thus translate between characters |
| and integers. |
| </p> |
| |
| <p> |
| The relevant functions, for debugging purposes, are <tt>enumToInteger</tt> and |
| <tt>enumFromInteger</tt>. |
| </p> |
| |
| <p> |
| Anonymous enumerations are ignored by the binding generation process, |
| leaving no way of accessing the value of anonymous enumerations from R |
| code. |
| </p> |
| |
| </body> |
| </html> |