Writing A Package That Uses RCPP: Dirk Eddelbuettel and Romain François
Writing A Package That Uses RCPP: Dirk Eddelbuettel and Romain François
Writing A Package That Uses RCPP: Dirk Eddelbuettel and Romain François
This document provides a short overview of how to use Rcpp (Ed- NAMESPACE
delbuettel et al., 2019; Eddelbuettel and François, 2011; Eddelbuettel, R
2013) when writing an R package. It shows how usage of the function Read-and-delete-me
Rcpp.package.skeleton which creates a complete and self-sufficient man
example package using Rcpp. All components of the directory tree cre- src
ated by Rcpp.package.skeleton are discussed in detail. This document
thereby complements the Writing R Extensions manual (R Core Team, mypackage/R:
2018) which is the authoritative source on how to extend R in general. RcppExports.R
Rcpp | package | R | C++
mypackage/man:
mypackage-package.Rd
1. Introduction rcpp_hello_world.Rd
Rcpp (Eddelbuettel et al., 2019; Eddelbuettel and François, 2011;
Eddelbuettel, 2013) is an extension package for R which offers an mypackage/src:
easy-to-use yet featureful interface between C++ and R. However, it Makevars # until Rcpp 0.10.6, see below
is somewhat different from a traditional R package because its key Makevars.win # until Rcpp 0.10.6, see below
component is a C++ library. A client package that wants to make RcppExports.cpp
use of the Rcpp features must link against the library provided by rcpp_hello_world.cpp
Rcpp. $
It should be noted that R has only limited support for C(++)-
level dependencies between packages (R Core Team, 2018). The Using Rcpp.package.skeleton is by far the simplest approach
LinkingTo declaration in the package DESCRIPTION file allows the as it fulfills two roles. It creates the complete set of files needed for
client package to retrieve the headers of the target package (here a package, and it also includes the different components needed
Rcpp), but support for linking against a library is not provided by for using Rcpp that we discuss in the following sections.
R and has to be added manually.
This document follows the steps of the 2.2. C++ code. If the attributes argument is set to TRUE1 , the
Rcpp.package.skeleton function to illustrate a recommended following C++ file is included in the src/ directory:
way of using Rcpp from a client package. We illustrate this using
#include <Rcpp.h>
a simple C++ function which will be called by an R function.
using namespace Rcpp;
We strongly encourage the reader to become familiar with the
material in the Writing R Extensions manual (R Core Team, 2018),
// [[Rcpp::export]]
as well as with other documents on R package creation such as
List rcpp_hello_world() {
Leisch (2008). Given a basic understanding of how to create R
package, the present document aims to provide the additional
CharacterVector x =
information on how to use Rcpp in such add-on packages.
CharacterVector::create("foo", "bar");
NumericVector y =
2. Using Rcpp.package.skeleton NumericVector::create( 0.0, 1.0 ) ;
2.1. Overview. Rcpp provides a function List z = List::create( x, y ) ;
Rcpp.package.skeleton, modeled after the base R func-
tion package.skeleton, which facilitates creation of a skeleton return z ;
package using Rcpp. }
Rcpp.package.skeleton has a number of arguments
documented on its help page (and similar to those of The file defines the simple rcpp_hello_world function that
package.skeleton). The main argument is the first one uses a few Rcpp classes and returns a List.
which provides the name of the package one aims to create by This function is preceded by the Rcpp::export attribute to
invoking the function. An illustration of a call using an argument automatically handle argument conversion because R has to be
mypackage is provided below. taught how to e.g. handle the List class.
Rcpp.package.skeleton then invokes compileAttributes
Rcpp.package.skeleton("mypackage")
on the package, which generates the RcppExports.cpp file (where
we indented the first two lines for the more compact display here):
$ ls -1R mypackage/ 1
Setting attributes to TRUE is the default. This document does not cover the behavior of
DESCRIPTION Rcpp.package.skeleton when attributes is set to FALSE as we try to encourage package de-
veloppers to use attributes.
This file defines a function with the appropriate calling con- ## Use the R_HOME indirection to support
vention, suitable for .Call. It needs to be regenerated each time ## installations of multiple R version
functions exposed by attributes are modified. This is the task of ##
the compileAttributes function. A discussion on attributes is be- ## NB: No longer needed, see below
yond the scope of this document and more information is available PKG_LIBS = ‘$(R_HOME)/bin/Rscript -e \
in the attributes vignette (Allaire et al., 2018). "Rcpp:::LdFlags()"‘
2.3. R code. The compileAttributes also generates R code that The Makevars.win is the equivalent, targeting windows.
uses the C++ function. ## Use the R_HOME indirection to support
# Generated by using Rcpp::compileAttributes() \ ## installations of multiple R version
# -> do not edit by hand ##
# Generator token: \ ## NB: No longer needed, see below
# 10BE3573-1514-4C36-9D1C-5A225CD40393 PKG_LIBS = $(shell \
"${R_HOME}/bin${R_ARCH_BIN}/Rscript.exe" \
rcpp_hello_world <- function() { -e "Rcpp:::LdFlags()")
.Call(’mypackage_rcpp_hello_world’,
PACKAGE = ’mypackage’) 2.7. Releases since 0.11.0. As of release 0.11.0, this is no longer
} needed as client packages obtain the required code from Rcpp
via explicit function registration. The user does not have to do
This is also a generated file so it should not be modified manually, anything.
rather regenerated as needed by compileAttributes. This means that PKG_LIBS can now be empty—unless some
client libraries are needed. For example, RcppCNPy needs com-
2.4. DESCRIPTION. The skeleton generates an appropriate pression support and hence uses PKG_LIBS= -lz. Similarly, when
DESCRIPTION file, using both Imports: and LinkingTo for a third-party library is required, it can and should be set here.
Rcpp:
2.8. NAMESPACE. The Rcpp.package.skeleton function also cre-
Package: mypackage
ates a file NAMESPACE.
Type: Package
Title: What the package does (short line) useDynLib(mypackage)
Version: 1.0 exportPattern("^[[:alpha:]]+")
Date: 2013-09-17 importFrom(Rcpp, evalCpp)
Author: Who wrote it
Maintainer: Who <[email protected]> This file serves three purposes. First, it ensure that the
Description: More about what it does (maybe dynamic library contained in the package we are creating via
more than one line) Rcpp.package.skeleton will be loaded and thereby made avail-
License: What Licence is it under ? able to the newly created R package.
Imports: Rcpp (>= 0.11.0) Second, it declares which functions should be globally visible
LinkingTo: Rcpp from the namespace of this package. As a reasonable default, we
export all functions.
Rcpp.package.skeleton adds the three last lines to the Third, it instructs R to import a symbol from Rcpp. This sets
DESCRIPTION file generated by package.skeleton. up the import of all registered function and, together with the