cpp11 internals

Initial setup and dev workflow

First install any dependencies needed for development.

install.packages("remotes")
remotes::install_deps(dependencies = TRUE)

You can load the package in an interactive R session

devtools::load_all()

Or run the cpp11 tests with

devtools::test()

There are more extensive tests in the cpp11test directory. Generally when developing the C++ headers I run R with its working directory in the cpp11test directory and use devtools::test() to run the cpp11tests.

If you change the cpp11 headers you will need to install the new version of cpp11 and then clean and recompile the cpp11test package:

# Assuming your working directory is `cpp11test/`
devtools::clean_dll()
devtools::load_all()

To calculate code coverage of the cpp11 package run the following from the cpp11 root directory.

covr::report(cpp11_coverage())

Code formatting

This project uses clang-format (version 10) to automatically format the c++ code.

You can run make format to re-format all code in the project. If your system does not have clang-format version 10, this can be installed using a homebrew tap at the command line with brew install r-lib/taps/clang-format@10.

You may need to link the newly installed version 10. To do so, run brew unlink clang-format followed by brew link clang-format@10.

Alternatively many IDEs support automatically running clang-format every time files are written.

Code organization

cpp11 is a header only library, so all source code exposed to users lives in inst/include. R code used to register functions and for cpp11::cpp_source() is in R/. Tests for only the code in R/ is in tests/testthat/. The rest of the code is in a separate cpp11test/ package included in the source tree. Inside cpp11test/src the files that start with test- are C++ tests using the Catch support in testthat. In addition there are some regular R tests in cpp11test/tests/testthat/.

Naming conventions

• All header files are named with a .hpp extension.
• All source files are named with a .cpp extension.
• Public header files should be put in inst/include/cpp11
• Read only r_vector classes and free functions should be put in the cpp11 namespace.
• Writable r_vector class should be put in the cpp11::writable namespace.
• Private classes and functions should be put in the cpp11::internal namespace.

Vector classes

All of the basic r_vector classes are class templates, the base template is defined in cpp11/r_vector.hpp. The template parameter is the type of value the particular R vector stores, e.g. double for cpp11::doubles. This differs from Rcpp, whose first template parameter is the R vector type, e.g. REALSXP.

The file first has the class declarations, then function definitions further down in the file. Specializations for the various types are in separate files, e.g. cpp11/doubles.hpp, cpp11/integers.hpp

Coercion functions

There are two different coercion functions

as_sexp() takes a C++ object and coerces it to a SEXP object, so it can be used in R. as_cpp<>() is a template function that takes a SEXP and creates a C++ object from it

The various methods for both functions are defined in cpp11/as.hpp

This is definitely the most complex part of the cpp11 code, with extensive use of template metaprogramming. In particular the substitution failure is not an error (SFINAE) technique is used to control overloading of the functions. If we could use C++20 a lot of this code would be made simpler with Concepts, but alas.

The most common C++ types are included in the test suite and should work without issues, as more exotic types are used in real projects additional issues may arise.

Some useful links on SFINAE

• https://www.fluentcpp.com/2018/05/15/make-sfinae-pretty-1-what-value-sfinae-brings-to-code/, https://www.fluentcpp.com/2018/05/18/make-sfinae-pretty-2-hidden-beauty-sfinae/

Protection