Writing a package that uses \pkg{Rcpp} • Rcpp

Abstract

This document provides a short overview of how to use when writing an package. It shows how usage of the function which creates a complete and self-sufficient example package using . All components of the directory tree created by are discussed in detail. This document thereby complements the manual which is the authoritative source on how to extend in general.

Introduction

is an extension package for which offers an easy-to-use yet featureful interface between and . However, it is somewhat different from a traditional package because its key component is a library. A client package that wants to make use of the features must link against the library provided by .

It should be noted that has only limited support for -level dependencies between packages . The LinkingTo declaration in the package DESCRIPTION file allows the client package to retrieve the headers of the target package (here ), but support for linking against a library is not provided by and has to be added manually.

This document follows the steps of the function to illustrate a recommended way of using from a client package. We illustrate this using a simple function which will be called by an function.

We strongly encourage the reader to become familiar with the material in the manual , as well as with other documents on package creation such as . Given a basic understanding of how to create package, the present document aims to provide the additional information on how to use in such add-on packages.

Using `Rcpp.package.skeleton`

Overview

provides a function , modeled after the base function , which facilitates creation of a skeleton package using .

has a number of arguments documented on its help page (and similar to those of ). The main argument is the first one which provides the name of the package one aims to create by invoking the function. An illustration of a call using an argument mypackage is provided below.

Rcpp.package.skeleton("mypackage")

Using is by far the simplest approach as it fulfils two roles. It creates the complete set of files needed for a package, and it also includes the different components needed for using that we discuss in the following sections.

code

If the attributes argument is set to TRUE¹, the following file is included in the src/ directory:

#include <Rcpp.h>
using namespace Rcpp;

// [[Rcpp::export]]
List rcpp_hello_world() {

    CharacterVector x = 
        CharacterVector::create("foo", "bar");
    NumericVector y   = 
        NumericVector::create( 0.0, 1.0 ) ;
    List z            = List::create( x, y ) ;

    return z ;
}

The file defines the simple rcpp_hello_world function that uses a few classes and returns a List.

This function is preceded by the Rcpp::export attribute to automatically handle argument conversion because has to be taught how to e.g. handle the List class.

then invokes on the package, which generates the RcppExports.cpp file (where we indented the first two lines for the more compact display here):

// Generated by using Rcpp::compileAttributes() \
//        -> do not edit by hand
// Generator token: \
//        10BE3573-1514-4C36-9D1C-5A225CD40393

#include <Rcpp.h>

using namespace Rcpp;

// rcpp_hello_world
List rcpp_hello_world();
RcppExport SEXP mypackage_rcpp_hello_world() {
BEGIN_RCPP
    Rcpp::RObject rcpp_result_gen;
    Rcpp::RNGScope rcpp_rngScope_gen;
    rcpp_result_gen =
           Rcpp::wrap(rcpp_hello_world());
    return rcpp_result_gen;
END_RCPP
}

This file defines a function with the appropriate calling convention, suitable for . It needs to be regenerated each time functions exposed by attributes are modified. This is the task of the function. A discussion on attributes is beyond the scope of this document and more information is available in the attributes vignette .

code

The also generates code that uses the function.

# Generated by using Rcpp::compileAttributes() \
#        -> do not edit by hand
# Generator token: \
#        10BE3573-1514-4C36-9D1C-5A225CD40393

rcpp_hello_world <- function() {
    .Call('mypackage_rcpp_hello_world', 
          PACKAGE = 'mypackage')
}

This is also a generated file so it should not be modified manually, rather regenerated as needed by .

`DESCRIPTION`

The skeleton generates an appropriate DESCRIPTION file, using both Imports: and LinkingTo for :

adds the three last lines to the DESCRIPTION file generated by .

The Imports declaration indicates -level dependency between the client package and ; code from the latter is being imported into the package described here. The LinkingTo declaration indicates that the client package needs to use header files exposed by .

Now optional: `Makevars` and `Makevars.win`

This behaviour changed with release 0.11.0. These files used to be mandatory, now they are merely optional.

We will describe the old setting first as it was in use for a few years. The new standard, however, is much easier and is described below.

Releases up until 0.10.6

Unfortunately, the LinkingTo declaration in itself was not enough to link to the user library of . Until more explicit support for libraries is added to , ones needs to manually add the library to the PKG_LIBS variable in the Makevars and Makevars.win files. (This has now changed with release 0.11.0; see below). provides the unexported function Rcpp:::LdFlags() to ease the process:

## Use the R_HOME indirection to support
## installations of multiple R version
##
## NB: No longer needed, see below
PKG_LIBS = `$(R_HOME)/bin/Rscript -e \
                      "Rcpp:::LdFlags()"`

The Makevars.win is the equivalent, targeting windows.

## Use the R_HOME indirection to support
## installations of multiple R version
##
## NB: No longer needed, see below
PKG_LIBS = $(shell \
   "${R_HOME}/bin${R_ARCH_BIN}/Rscript.exe" \
   -e "Rcpp:::LdFlags()")

Releases since 0.11.0

As of release 0.11.0, this is no longer needed as client packages obtain the required code from via explicit function registration. The user does not have to do anything.

This means that PKG_LIBS can now be empty—unless some client libraries are needed. For example, needs compression support and hence uses PKG_LIBS= -lz. Similarly, when a third-party library is required, it can and should be set here.

`NAMESPACE`

The function also creates a file NAMESPACE.

useDynLib(mypackage)
exportPattern("^[[:alpha:]]+")
importFrom(Rcpp, evalCpp)

This file serves three purposes. First, it ensure that the dynamic library contained in the package we are creating via will be loaded and thereby made available to the newly created package.

Second, it declares which functions should be globally visible from the namespace of this package. As a reasonable default, we export all functions.

Third, it instructs R to import a symbol from . This sets up the import of all registered function and, together with the Imports: statement in DESCRIPTION, provides what is needed for client packages to access functionality.

Help files

Also created is a directory man containing two help files. One is for the package itself, the other for the (single) function being provided and exported.

The manual provides the complete documentation on how to create suitable content for help files.

`mypackage-package.Rd`

The help file mypackage-package.Rd can be used to describe the new package (and we once again indented some lines):

\name{mypackage-package}
\alias{mypackage-package}
\alias{mypackage}
\docType{package}
\title{
What the package does (short line)
}
\description{
More about what it does (maybe more than one line)
~~ A concise (1-5 lines) description of the
package ~~
}
\details{
\tabular{ll}{
Package: \tab mypackage\cr
Type: \tab Package\cr
Version: \tab 1.0\cr
Date: \tab 2013-09-17\cr
License: \tab What license is it under?\cr
}
~~ An overview of how to use the package,
including the most important functions ~~
}
\author{
Who wrote it

Maintainer: Who <yourfault@somewhere.net>
}
\references{
~~ Literature or other references for
background information ~~
}
~~ Optionally other standard keywords, one per
line, from file KEYWORDS in the R
documentation directory ~~
\keyword{ package }
\seealso{
~~ Optional links to other man pages, e.g. ~~
~~ \code{\link[<pkg>:<pkg>-package]{<pkg>}} ~~
}
\examples{
%% ~~ simple examples of the most important
%% functions ~~
}

`rcpp_hello_world.Rd`

The help file rcpp_hello_world.Rd serves as documentation for the example function.

\name{rcpp_hello_world}
\alias{rcpp_hello_world}
\docType{package}
\title{
Simple function using Rcpp
}
\description{
Simple function using Rcpp
}
\usage{
rcpp_hello_world()
}
\examples{
\dontrun{
rcpp_hello_world()
}
}

Using modules

This document does not cover the use of the module argument of . It is covered in the modules vignette .

Further examples

The canonical example of a package that uses is the package. contains various examples of using . Hence, the package is provided as a template for employing in packages.

Other CRAN packages using the package are , and . Several other packages follow older (but still supported and appropriate) instructions. They can serve examples on how to get data to and from routines, but should not be considered templates for how to connect to . The full list of packages using can be found at the CRAN page of .

Other compilers

Less experienced users on the Windows platform frequently ask about using with the Visual Studio toolchain. That is simply not possible as is built with the compiler. Different compilers have different linking conventions. These conventions are particularly hairy when it comes to using . In short, it is not possible to simply drop sources (or header files) from into a project built with Visual Studio, and this note makes no attempt at claiming otherwise.

is fully usable on Windows provided the standard Windows toolchain for is used. See the manual for details.

Summary

This document described how to use the package for and integration when writing an extension package. The use of the was shown in detail, and references to further examples were provided.

Setting attributes to TRUE is the default. This document does not cover the behavior of Rcpp.package.skeleton when attributes is set to FALSE as we try to encourage package developers to use attributes.↩︎

Writing a package that uses

Dirk Eddelbuettel

Romain François

Introduction

Using `Rcpp.package.skeleton`

Overview

code

code

`DESCRIPTION`

Now optional: `Makevars` and `Makevars.win`

Releases up until 0.10.6

Releases since 0.11.0

`NAMESPACE`

Help files

`mypackage-package.Rd`

`rcpp_hello_world.Rd`

Using modules

Further examples

Other compilers

Summary

Writing a package that uses

Dirk Eddelbuettel

Romain François

Introduction

Using Rcpp.package.skeleton

Overview

code

code

DESCRIPTION

Now optional: Makevars and Makevars.win

Releases up until 0.10.6

Releases since 0.11.0

NAMESPACE

Help files

mypackage-package.Rd

rcpp_hello_world.Rd

Using modules

Further examples

Other compilers

Summary

Using `Rcpp.package.skeleton`

`DESCRIPTION`

Now optional: `Makevars` and `Makevars.win`

`NAMESPACE`

`mypackage-package.Rd`

`rcpp_hello_world.Rd`