Package Skeleton

Motivation

Vaughan, Hester, and François (2024) is better used when adding C++ code to R packages, as it allows for proper script organization and documentation. The reference for this chapter is Wickham et al. (2024).

Loading the Required R Packages

This chapter and the next use the following R packages:

library(cpp11)
library(devtools)
library(bench)
library(usethis)

Running a single function

It is possible to run a single function in C++ using the cpp11::cpp_source() function. For example, to create a function that adds one to a number, you can run:

cpp11::cpp_source(
  code = "
    #include <cpp11.hpp>

    using namespace cpp11;

    [[cpp11::register]] int plusone(int x) {
      return x + 1;
    }",
  quiet = FALSE
)

using C++ compiler: ‘g++ (Ubuntu 11.4.0-1ubuntu1~22.04) 11.4.0’
using C++11
g++ -std=gnu++11 -I"/usr/share/R/include" -DNDEBUG -I'/home/pacha/R/x86_64-pc-linux-gnu-library/4.4/cpp11/include'      -fpic  -g -O2 -ffile-prefix-map=/build/r-base-2y82rL/r-base-4.4.1=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2   -c /tmp/RtmpPVofZ2/file420f1c480e9/src/code_420f16bb38b82.cpp -o /tmp/RtmpPVofZ2/file420f1c480e9/src/code_420f16bb38b82.o
g++ -std=gnu++11 -I"/usr/share/R/include" -DNDEBUG -I'/home/pacha/R/x86_64-pc-linux-gnu-library/4.4/cpp11/include'      -fpic  -g -O2 -ffile-prefix-map=/build/r-base-2y82rL/r-base-4.4.1=. -fstack-protector-strong -Wformat -Werror=format-security -Wdate-time -D_FORTIFY_SOURCE=2   -c /tmp/RtmpPVofZ2/file420f1c480e9/src/cpp11.cpp -o /tmp/RtmpPVofZ2/file420f1c480e9/src/cpp11.o
g++ -std=gnu++11 -shared -L/usr/lib/R/lib -Wl,-Bsymbolic-functions -flto=auto -ffat-lto-objects -flto=auto -Wl,-z,relro -o /tmp/RtmpPVofZ2/file420f1c480e9/src/code_420f16bb38b82.so /tmp/RtmpPVofZ2/file420f1c480e9/src/code_420f16bb38b82.o /tmp/RtmpPVofZ2/file420f1c480e9/src/cpp11.o -L/usr/lib/R/lib -lR

This function can be called from R by running plusone(2), which should return 3, or with any other integer.

However, it is a much better practice to organize C++ code in an R package.

Creating a Dummy Package

I created a new package in RStudio (or VSCode) by running:

create_package("~/github/cpp-for-r-users/ece244")

This command created a new folder named ece244. Afterward, I ran use_cpp11() to add the necessary files for using C++ code within R.

Print a Number

I created a new R script by running use_r("ece244-package"). I added the following code to the file:

#' @useDynLib ece244, .registration = TRUE
NULL

The usethis package automatically created the file src/code.cpp. I modified it to include a simple function that prints the number 1:

#include "cpp11.hpp"

using namespace cpp11;

[[cpp11::register]] int one_cpp_() { 
  return 1; 
}

Within R, there is no need to create a main() function in C++.

The R version of the function is as follows:

#' Return 1 (R)
#' @export
one_r <- function() {
    1L
}

To export the C++ function, I added the following lines to ece244-package.R, which documents the function and allows for defining default argument values:

#' Return 1 (C++)
#' @export
one_cpp <- function() {
  one_cpp_()
}

Number’s Sign

A more complex function is one that returns the sign of a number:

[[cpp11::register]] int sign_cpp_(double x) {
  if (x > 0) {
    return 1;
  } else if (x == 0) {
    return 0;
  } else {
    return -1;
  }
}

Here is the R version of the function:

#' Return the sign of a number (R)
#' @param x integer
#' @export
sign_r <- function(x) {
  if (x > 0) {
    1
  } else if (x == 0) {
    0
  } else {
    -1
  }
}

I also added the corresponding auxiliary function for documentation:

#' Return the sign of a number (C++)
#' @inheritParams sum_r
#' @export
sign_cpp <- function(x) {
  sign_cpp_(x)
}

Installing the Package

To document and install the package as an R library, I ran the next functions:

cpp_register()
document()
install()

Afterward, I could access the functions by loading the package with library(ece244).

For development and live testing, I used the load_all() function:

load_all()

Each time I had to make changes to the C++ code, I ran load_all() again to test and then reinstalled the package.

Good Practice

It is good practice to include a license for your code. For example, you can use the Apache license by running:

use_apache_license()

Additionally, it is recommended to use use_build_ignore() to ignore files that are unnecessary for package installation. For example, to ignore the docs folder, you can run:

use_build_ignore("docs")

My .Rbuildignore file includes the following lines, which I edited manually to exclude specific files and directories:

^\.vscode$
^LICENSE\.md$
^ece244\.Rproj$

References

Vaughan, Davis, Jim Hester, and Romain François. 2024. Cpp11: A c++11 Interface for r’s c Interface. https://CRAN.R-project.org/package=cpp11.

Wickham, Hadley, Jenny Bryan, Malcolm Barrett, and Andy Teucher. 2024. “Automate Package and Project Setup.” https://usethis.r-lib.org/.