title: \pkg{Rcpp} FAQ

author:

- name: Dirk Eddelbuettel

affiliation: a

- name: Romain François

affiliation: b

address:

- code: a

address: \url{http://dirk.eddelbuettel.com}

- code: b

address: \url{https://romain.rbind.io/}

lead_author_surname: Eddelbuettel and François

doi: "https://cran.r-project.org/package=Rcpp"

abstract: |

keywords:

- Rcpp

- FAQ

- R

- C++

fontsize: 9pt

numbersections: true

secnumdepth: 5

bibliography: Rcpp

footer_contents: "Rcpp Vignette"

skip_final_break: true

output:

pinp::pinp:

collapse: true

header-includes: >

vignette: >

\tableofcontents

```{r setup, include=FALSE}

If you have \pkg{Rcpp} installed, please execute the following command

in \proglang{R} to access the introductory vignette (which is a

variant of the \citet{JSS:Rcpp} and \citet{PeerJ:Rcpp,TAS:Rcpp} papers) for a

detailed introduction, ideally followed by at least the Rcpp

Attributes \citep{CRAN:Rcpp:Attributes} vignette:

```{r, eval=FALSE}

If you do not have \pkg{Rcpp} installed, these documents should also be available

whereever you found this document, \textsl{i.e.,} on every mirror site of CRAN.

Obviously, \proglang{R} must be installed. \pkg{Rcpp} provides a

\proglang{C++} API as an extension to the \proglang{R} system. As such, it

is bound by the choices made by \proglang{R} and is also influenced by how

\proglang{R} is configured.

In general, the standard environment for building a CRAN package from source

(particularly when it contains \proglang{C} or \proglang{C++} code) is required. This

means one needs:

- a development environment with a suitable compiler (see

below), header files and required libraries;

- \proglang{R} should be built in a way that permits linking and possibly

embedding of \proglang{R}; this is typically ensured by the

`--enable-shared-lib` option;

- standard development tools such as `make` etc.

Also see the [RStudio documentation](http://www.rstudio.com/ide/docs/packages/prerequisites)

on pre-requisites for R package development.

On almost all platforms, the GNU Compiler Collection (or `gcc`, which

is also the name of its \proglang{C} language compiler) has to be used along

with the corresponding `g++` compiler for the \proglang{C++} language.

A minimal suitable version is a final 4.2.* release; earlier 4.2.* were

lacking some \proglang{C++} features (and even 4.2.1, still used on OS X as the

last gcc release), has issues).

Generally speaking, the default compilers on all the common platforms are suitable.

Specific per-platform notes:

\begin{description}

\item[Windows] users need the \texttt{Rtools} package from the site maintained by

Duncan Murdoch which contains all the required tools in a single package;

complete instructions specific to Windows are in the `R Administration'

manual \citep[Appendix D]{R:Administration}. As of August 2014, it still

installs the \texttt{gcc/g++} 4.6.* compiler which limits the ability to use

modern C++ standards so only \code{s-std=c++0x} is supported. R 3.1.0 and

above detect this and set appropriate flags.

\item[OS X] users, as noted in the `R Administration' manual \citep[Appendix

C.4]{R:Administration}, need to install the Apple Developer Tools

(\textsl{e.g.}, \href{https://itunes.apple.com/us/app/xcode/id497799835?mt=12}{Xcode} (OS X $\le 10.8$) or \href{https://developer.apple.com/library/ios/technotes/tn2339/_index.html}{Xcode Command Line Tools} (OS X $\ge 10.9$) (as well as \texttt{gfortran} if \proglang{R} or

Fortran-using packages are to be built); also see \faq{q:OSX} and

\faq{q:OSXArma} below. Depending on whether on OS X release before or after

Mavericks is used, different additional installation may be needed. Consult

the \code{r-sig-mac} list (and its archives) for (current) details.

\item[Linux] user need to install the standard developement packages. Some

distributions provide helper packages which pull in all the required

packages; the \texttt{r-base-dev} package on Debian and Ubuntu is an example.

\end{description}

The `clang` and `clang++` compilers from the LLVM project can

also be used. On Linux, they are inter-operable with `gcc` et al. On

OS X, they are unfortunately not ABI compatible. The `clang++`

compiler is interesting as it emits much more comprehensible error messages

than `g++` (though `g++` 4.8 and 4.9 have caught up).

The Intel `icc` family has also been used successfully as its output

files can also be combined with those from `gcc`.

Additional packages that we have found useful are:

\begin{description}

\item[\pkg{inline}] which is invaluable for direct compilation, linking and loading

of short code snippets---but now effectively superseded by the Rcpp

Attributes (see \faq{using-attributes} and

\faq{prototype-using-attributes}) feature provided by \pkg{Rcpp};

\item[\pkg{RUnit}] is used for unit testing; the package is recommended and

will be needed to re-run some of our tests but it is not strictly required

during use of \pkg{Rcpp};

\item[\pkg{rbenchmark}] to run simple timing comparisons and benchmarks; it is also

recommended but not required.

\item[\pkg{microbenchmark}] is an alternative for benchmarking.

\item[\pkg{devtools}] can help the process of building, compiling and testing

a package but it too is entirely optional.

\end{description}

The \pkg{Rcpp} package is licensed under the terms of the

[GNU GPL 2 or later](http://www.gnu.org/licenses/gpl-2.0.html), just like

\proglang{R} itself. A key goal of the \pkg{Rcpp} package is to make

extending \proglang{R} more seamless. But by \textsl{linking} your code against

\proglang{R} (as well as \pkg{Rcpp}), the combination is bound by the GPL as

well. This is very clearly

stated at the

[FSF website](https://www.gnu.org/licenses/gpl-faq.html#GPLStaticVsDynamic):

So you are free to license your work under whichever terms you find suitable

(provided they are GPL-compatible, see the

[FSF site for details](http://www.gnu.org/licenses/licenses.html)). However,

the combined work will remain under the terms and conditions of the GNU General

Public License. This restriction comes from both \proglang{R} which is GPL-licensed

as well as from \pkg{Rcpp} and whichever other GPL-licensed components you may

be linking against.

\pkg{Rcpp} has been specifically designed to be used by other packages.

Making a package that uses \pkg{Rcpp} depends on the same mechanics that are

involved in making any \proglang{R} package that use compiled code --- so

reading the \textsl{Writing R Extensions} manual \citep{R:Extensions} is a required

first step.

Further steps, specific to \pkg{Rcpp}, are described in a separate vignette.

```{r, eval=FALSE}

There are two toolchains which can help with this:

- The older one is provided by the \pkg{inline} package and described in

Section~\ref{using-inline}.

- Starting with \pkg{Rcpp} 0.10.0, the Rcpp Attributes feature (described

in Section~\ref{using-attributes}) offered an even easier alternative via

the function \rdoc{Rcpp}{evalCpp}, \rdoc{Rcpp}{cppFunction} and

\rdoc{Rcpp}{sourceCpp}.

The next two subsections show an example each.

The \pkg{inline} package \citep{CRAN:inline} provides the functions

\rdoc{inline}{cfunction} and \rdoc{inline}{cxxfunction}. Below is a simple

function that uses `accumulate` from the (\proglang{C++}) Standard

Template Library to sum the elements of a numeric vector.

One might want to use code that lives in a \proglang{C++} file instead of writing

the code in a character string in R. This is easily achieved by using

\rdoc{base}{readLines}:

```{r, eval=FALSE}

The `verbose` argument of \rdoc{inline}{cxxfunction} is very

useful as it shows how \pkg{inline} runs the show.

Rcpp Attributes \citep{CRAN:Rcpp:Attributes}, and also discussed in

\faq{prototype-using-attributes} below, permits an even easier

route to integrating R and C++. It provides three key functions.

First, \rdoc{Rcpp}{evalCpp} provide a means to evaluate simple C++

expression which is often useful for small tests, or to simply check

if the toolchain is set up correctly. Second, \rdoc{Rcpp}{cppFunction}

can be used to create C++ functions for R use on the fly. Third,

`Rcpp::sourceCpp` can integrate entire files in order to define

multiple functions.

The example above can now be rewritten as:

The \rdoc{Rcpp}{cppFunction} parses the supplied text, extracts the desired

function names, creates the required scaffolding, compiles, links and loads

the supplied code and makes it available under the selected identifier.

Similarly, \rdoc{Rcpp}{sourceCpp} can read in a file and compile, link and load

the code therein.

Since release 0.3.5 of \pkg{inline}, one can combine \faq{using-inline} and

\faq{make-package}. See `help("package.skeleton-methods")` once

\pkg{inline} is loaded and use the skeleton-generating functionality to

transform a prototyped function into the minimal structure of a package.

After that you can proceed with working on the package in the spirit of

\faq{make-package}.

Rcpp Attributes \citep{CRAN:Rcpp:Attributes} also offers a means to convert

functions written using Rcpp Attributes into a function via the

\rdoc{Rdoc}{compileAttributes} function; see the vignette for details.

The simplest way may be to work directly with a package. Changes to both the

\proglang{R} and \proglang{C++} code can be compiled and tested from the

command line via:

```{bash, eval = FALSE}

This first installs the packages, and then uses the command-line tool

\rdoc{utils}{Rscript} (which ships with `R`) to load the package, and execute

the \proglang{R} expression following the `-e` switch. Such an

expression can contain multiple statements separated by semicolons.

\rdoc{utils}{Rscript} is available on all three core operating systems.

On Linux, one can also use `r` from the `littler` package by Horner

and Eddelbuettel which is an alternative front end to \proglang{R} designed

for both `#!` (hashbang) scripting and command-line use. It has slightly

faster start-up times than \rdoc{utils}{Rscript}; and both give a guaranteed clean

slate as a new session is created.

The example then becomes

```{bash, eval = FALSE}

The `-l` option calls 'suppressMessages(library(mypkg))' before executing the

\proglang{R} expression. Several packages can be listed, separated by a comma.

More choice are provide by the \pkg{devtools} package, and by using

RStudio. See the respective documentation for details.

The recommended way is to create a package and follow \faq{make-package}. The

alternate recommendation is to use \pkg{inline} and follow \faq{using-inline}

because it takes care of all the details.

However, some people have shown that they prefer not to follow recommended

guidelines and compile their code using the traditional `R CMD SHLIB`. To

do so, we need to help `SHLIB` and let it know about the header files

that \pkg{Rcpp} provides and the \proglang{C++} library the code must link

against.

On the Linux command-line, you can do the following:

```{bash, eval = FALSE}

which first defines and exports two relevant environment variables which

`R CMD SHLIB` then relies on. On other operating systems, appropriate

settings may have to be used to define the environment variables.

This approach corresponds to the very earliest ways of building programs and

can still be found in some deprecated documents (as _e.g._ some of

Dirk's older 'Intro to HPC with R' tutorial slides). It is still not

recommended as there are tools and automation mechanisms that can do the work

for you.

\pkg{Rcpp} versions 0.11.0 or later can do with the definition of

`PKG_LIBS` as a user-facing library is no longer needed (and hence no

longer shipped with the package). One still needs to set `PKG_CXXFLAGS`

to tell R where the \pkg{Rcpp} headers files are located.

Once `R CMD SHLIB` has created the dyanmically-loadable file (with

extension `.so` on Linux, `.dylib` on OS X or `.dll` on

Windows), it can be loaded in an R session via \rdoc{base}{dyn.load}, and the

function can be executed via \rdoc{base}{.Call}. Needless to say, we

\emph{strongly} recommend using a package, or at least Rcpp Attributes as

either approach takes care of a lot of these tedious and error-prone manual

steps.

We have had reports in the past where build failures occurred when users had

non-standard code in their `~/.Rprofile` or `Rprofile.site` (or

equivalent) files.

If such code emits text on `stdout`, the frequent and implicit

invocation of `Rscript -e "..."` (as in \faq{using-r-cmd-shlib}

above) to retrieve settings directly from \pkg{Rcpp} will fail.

You may need to uncomment such non-standard code, or protect it by wrapping

it inside `if (interactive())`, or possibly try to use

`Rscript --vanilla` instead of plain `Rscript`.

\proglang{R} has only limited support for cross-package linkage.

We now employ the `LinkingTo` field of the `DESCRIPTION` file

of packages using \pkg{Rcpp}. But this only helps in having \proglang{R}

compute the location of the header files for us.

The actual library location and argument still needs to be provided by the

user. How to do so has been shown above, and we recommned you use either

\faq{make-package} or \faq{using-inline} both which use the \pkg{Rcpp}

function `Rcpp:::LdFlags()`.

If and when `LinkingTo` changes and lives up to its name, we will be

sure to adapt \pkg{Rcpp} as well.

An important change arrive with \pkg{Rcpp} release 0.11.0 and concern the

automatic registration of functions; see Section~\ref{function-registration} below.

Yes of course. See the Windows binaries provided by CRAN.

Not a chance.

And that is not because we are meanies but because \proglang{R} and Visual

Studio simply do not get along. As \pkg{Rcpp} is all about extending

\proglang{R} with \proglang{C++} interfaces, we are bound by the available

toolchain. And \proglang{R} simply does not compile with Visual Studio. Go

complain to its vendor if you are still upset.

There are three known issues regarding Rcpp build problems on macOS. If you are

building packages with RcppArmadillo, there is yet another issue that is

addressed separately in \faq{q:OSXArma} below.

By default, macOS does not ship with an active compiler. Depending on the

\proglang{R} version being used, there are different development environment

setup procedures. For the current \proglang{R} version, we recommend observing

the official procedure used in

[Section 6.3.2 macOS](https://cran.r-project.org/doc/manuals/r-release/R-admin.html#macOS-packages)

and [Section C.3 macOS](https://cran.r-project.org/doc/manuals/r-release/R-admin.html#macOS)

of the [R Installation and Administration](https://cran.r-project.org/doc/manuals/r-release/R-admin.html)

manual.

There are currently _three_ distinct versions of R for macOS.

The first version is a legacy version meant for macOS 10.6 (Snow Leopard) -

10.8 (Mountain Lion). The second version is for more recent system

macOS 10.9 (Mavericks) and 10.10 (Yosemite). Finally, the third and most

up-to-date version supports macOS 10.11 (El Capitan), 10.12 (Sierra), and 10.13 (High Sierra).

The distinction comes as a result of a change in the compilers shipped with the

operating system as highlighted previously. As a result, avoid sending

\textbf{package binaries} to collaborators if they are working on older

operating systems as the \proglang{R} binaries for these versions will not be

able to mix. In such cases, it is better to provide collaborators with the

\textbf{package source} and allow them to build the package locally.

By default, the macOS operating environment lacks the ability to parallelize

sections of code using the \proglang{[OpenMP](http://openmp.org/wp/)}

standard. Within \proglang{R} 3.4.*, the default developer environment was

_changed_ to allow for \proglang{OpenMP} to be used on macOS by using

a non-default toolchain provided by R Core Team maintainers for macOS.

Having said this, it is still important to protect any reference to

\proglang{OpenMP} as some users may not yet have the ability to

use \proglang{OpenMP}.

To setup the appropriate protection for using \proglang{OpenMP}, the process

is two-fold. First, protect the inclusion of headers with:

#ifdef _OPENMP

#include <omp.h>

#endif

Second, when parallelizing portions of code use:

#ifdef _OPENMP

// multithreaded OpenMP version of code

#else

// single-threaded version of code

#endif

Under this approach, the code will be _safely_ parallelized when

support exists for \proglang{OpenMP} on Windows, macOS, and Linux.

Below are additional resources that provide information regarding compiling Rcpp code on macOS.

1. A helpful post was provided by Brian Ripley regarding the use of

compiling R code with macOS in April 2014

[on the `r-sig-mac` list](https://stat.ethz.ch/pipermail/r-sig-mac/2014-April/010835.html),

which is generally recommended for OS X-specific questions and further consultation.

2. Another helpful write-up for installation / compilation on OS X Mavericks is provided

[by the BioConductor project](http://www.bioconductor.org/developers/how-to/mavericks-howto/).

3. Lastly, another resource that exists for installation / compilation

help is provided at

<http://thecoatlessprofessor.com/programming/r-compiler-tools-for-rcpp-on-os-x/>.

\textbf{Note:} If you are running into trouble compiling code with \pkg{RcppArmadillo}, please also see \faq{q:OSXArma} listed below.

Yes, it generally does. But as we do not have access to such systems, some

issues persist on the CRAN test systems.

We have not tested it yet. \pkg{Rcpp} might need a few tweaks to work

with the compilers used by Revolution R (if those differ from the defaults).

Rho, previously known as CXXR, is an ambitious project that aims to

totally refactor the \proglang{R} interpreter in \proglang{C++}. There

are a few similaritites with \pkg{Rcpp} but the projects are

unrelated.

Rho / CXXR and \pkg{Rcpp} both want \proglang{R} to make more use of \proglang{C++}

but they do it in very different ways.

\pkg{Rcpp} version 0.10.0 and later offer a new feature 'Rcpp Attributes'

which is described in detail in its own vignette

\citep{CRAN:Rcpp:Attributes}. In short, it offers functions \rdoc{Rcpp}{evalCpp},

\rdoc{Rcpp}{cppFunction} and \rdoc{Rcpp}{sourceCpp} which extend the functionality of the

\rdoc{Rcpp}{cxxfunction} function.

Starting with \pkg{Rcpp} 0.11.0, functionality provided by \pkg{Rcpp} and

used by packages built with \pkg{Rcpp} accessed via the registration facility

offered by R (and which is used by \pkg{lme4} and \pkg{Matrix}, as well as by

\pkg{xts} and \pkg{zoo}). This requires no effort from the user /

programmer, and even frees us from explicit linking instruction. In most

cases, the files `src/Makevars` and `src/Makevars.win` can now be

removed. Exceptions are the use of \pkg{RcppArmadillo} (which needs an entry

`PKG_LIBS=$(LAPACK_LIBS) $(BLAS_LIBS) $(FLIBS)`) and packages linking

to external libraries they use.

But for most packages using \pkg{Rcpp}, only two things are required:

- an entry in `DESCRIPTION` such as `Imports: Rcpp` (which may

be versioned as in `Imports: Rcpp (>= 0.11.0)`), and

- an entry in `NAMESPACE` to ensure \pkg{Rcpp} is correctly

instantiated, for example `importFrom(Rcpp, evalCpp)`.

The name of the symbol does not really matter; once one symbol is imported all

symbols should be available.

Odds are your build failures are due to the absence of `gfortran`

and its associated libraries. The errors that you may receive are related to either

`-lgfortran` or `-lquadmath`.

To rectify the root of these errors, there are two options available. The first

option is to download and use a fixed set of `gfortran` binaries that are

used to compile R for macOS (e.g. given by the maintainers of the macOS build).

The second option is to either use pre-existing `gfortran` binaries on

your machine or download the latest. These options are described in-depth

in [Section C.3 macOS](https://cran.r-project.org/doc/manuals/r-release/R-admin.html#macOS)

of the [R Installation and Administration](https://cran.r-project.org/doc/manuals/r-release/R-admin.html)

manual. Please consult this manual for up-to-date information regarding `gfortran`

binaries on macOS. We have also documented _other_ common macOS compile

issues in Section \faq{q:OSX}.

The following questions were asked on the

[Rcpp-devel](https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/rcpp-devel)

mailing list, which is our preferred place to ask questions as it guarantees

exposure to a number of advanced Rcpp users. The

[StackOverflow tag for rcpp](http://stackoverflow.com/questions/tagged/rcpp)

is an alternative; that site is also easily searchable.

Several dozen fully documented examples are provided at the

[Rcpp Gallery](http://gallery.rcpp.org) -- which is also open for new contributions.

This question was initially about using templates with \pkg{inline}, and we

show that (older) answer first. It is also easy with Rcpp Attributes which is

what we show below.

Most certainly, consider this simple example of a templated class

which squares its argument:

We can also use 'Rcpp Attributes' \citep{CRAN:Rcpp:Attributes}---as described

in \faq{using-attributes} and \faq{prototype-using-attributes} above. Simply

place the following code into a file and use \rdoc{Rcpp}{sourceCpp} on it. It

will even run the R part at the end.

#include <Rcpp.h>

template <typename T> class square :

public std::unary_function<T,T> {

public:

T operator()( T t) const {

return t*t ;

}

};

// [[Rcpp::export]]

Rcpp::DataFrame fun(double x, int i) {

square<double> sqdbl;

square<int> sqint;

return Rcpp::DataFrame::create(

Rcpp::Named("x", sqdbl(x)),

Rcpp::Named("i", sqint(i)));

}

/*** R

fun(2.2, 3L)

*/

If stored in a file `myfile.cpp`, we can use it via \pkg{inline}:

```{r, eval = FALSE}

The focus is on the code `arma::trans(x) * arma::inv(Y) * z`, which

performs the same operation as the R code `t(x) %*% solve(Y) %*% z`,

although Armadillo turns it into only one operation, which makes it quite fast.

Armadillo benchmarks against other \proglang{C++} matrix algebra libraries

are provided on [the Armadillo website](http://arma.sourceforge.net/speed.html).

It should be noted that code below depends on the version `0.3.5` of

\pkg{inline} and the version `0.2.2` of \pkg{RcppArmadillo}.

We can also write the same example for use with Rcpp Attributes:

#include <RcppArmadillo.h>

double fx(arma::colvec x, arma::mat Y,

arma::colvec z) {

// calculate the result

double result = arma::as_scalar(

arma::trans(x) * arma::inv(Y) * z

);

return result;

}

/*** R

fx(1:4, diag(4), 1:4)

*/

Newer versions of Rcpp also provide the actual Rmath function in the `R`

namespace, \textsl{i.e.} as `R::rnorm(m,s)` to obtain a scalar

random variable distributed as $N(m,s)$.

Using Rcpp Attributes, this can be as simple as

This illustrates the Rcpp Attributes adds the required `RNGScope` object

for us. It also shows how setting the seed from R affects draws done via C++

as well as R, and that identical random number draws are obtained.

\noindent Yes, see the following example:

Similarly, for Rcpp Attributes:

#include <Rcpp.h>

Rcpp::NumericVector fun(void) {

Rcpp::NumericVector v(4);

v[0] = R_NegInf; // -Inf

v[1] = NA_REAL; // NA

v[2] = R_PosInf; // Inf

v[3] = 42; // c.f. Hitchhiker Guide

return v;

}

Armadillo supports a full range of common linear algebra operations.

The \pkg{RcppEigen} package provides an alternative using the

[Eigen](http://eigen.tuxfamily.org) template library.

Rcpp Attributes, once again, makes this even easier:

#include <RcppArmadillo.h>

arma::mat mult(arma::mat A, arma::mat B) {

return A*B;

}

/*** R

A <- matrix(1:9, 3, 3)

B <- matrix(9:1, 3, 3)

mult(A,B)

*/

Here the \pkg{Rcpp} function `Rcpp.plugin.maker` is used to create a

plugin 'plug' which is then registered, and subsequently used by \pkg{inline}.

The same plugins can be used by Rcpp Attributes as well.

The quickest way is to modify the return value from an existing plugin. Here

we use the default one from \pkg{Rcpp} itself in order to pass the new flag

`-std=c++0x`. As it does not set the `PKG_CXXFLAGS` variable, we

simply assign this. For other plugins, one may need to append to the existing

values instead.

```{r, eval=FALSE}

For Rcpp Attributes, the attributes `Rcpp::plugin()` can be

used. Currently supported plugins are for C++11 as well as for OpenMP.