davisvaughan / cbuild

Tools to Make Developing R Packages Interfacing with C Easier

cbuild

The goal of cbuild is to provide tools for working with C both interactively and when constructing an R package. The two broad goals are:

• Provide a way to interactively source C code into your R session. See source_function() and source_code() to get started.

• Provide an automatic registration system for R package developers that use C, see process_attributes(). It can automatically generate the init.c file for you, using a comment system similar to Rcpp::export. For example, the following would generate an entry for the C function fn() in init.c, and generate the glue code to export it as an R routine named fn, which you could call from the R side with .Call(fn, 1):

  // [[ export() ]]
  SEXP fn(SEXP x) {
    return x;
  }
  

Installation

You can install the development version from GitHub with:

# install.packages("devtools")
devtools::install_github("DavisVaughan/cbuild")

Examples

library(cbuild)

The easiest way to get started is with source_function(), which allows you to source a C function from text. It automatically includes R.h and Rinternals.h for you to use.

fn <- source_function("
  SEXP fn(SEXP x) {
    return x;
  }
")

fn(1)
#> [1] 1

From there, you can use source_code() to source larger chunks of code. Tag functions that you want to export with // [[ export() ]].

fns <- source_code("
  static SEXP helper(SEXP x) {
    return x;
  }
  
  // [[ export() ]]
  SEXP fn1(SEXP x) {
    return helper(x);
  }
  
  // [[ export() ]]
  SEXP fn2(SEXP x, SEXP y) {
    double result = REAL(x)[0] + REAL(y)[0];
    return Rf_ScalarReal(result);
  }
")

fns$fn1(1)
#> [1] 1

fns$fn2(1, 2)
#> [1] 3

If you have a full file to source, you can use source_file().

cbuild's Issues

Generate the `inst/include` directory for API bindings

For non-hidden callables. What is the "preferred" way to write the API file? There are two main methods, one that writing r extensions recommends, and one that we do in vctrs that requires slightly more user effort. Maybe support both with some way to specify that you want to use one or the other for the entire package? Maybe something in the DESCRIPTION file like roxygen2 does?

Need to record types for `callable()`

The generated callable forward declaration is wrong for callable() lines because it assumes they all have SEXP arguments. If we record the types while parsing we can use them here to generate the correct declaration https://github.com/DavisVaughan/vctrs/blob/69f839f41975871edfd40604b71ea44938f9061a/src/init.c#L188

Make tests from everything in `pkg1/` test directory

And then delete it

Default to using R_forceSymbols(dll, TRUE)

Consider special casing function pointer arguments

https://github.com/r-lib/cleancall/blob/f7fd3ae996ac890dd1fc8ef109d3a6ac48968675/src/cleancall.c#L63

For example, you register a callable with a function pointer as argument, like done in cleancall

Should hook functions use ... as the first arg?

If we make ... the first argument then we can force named arguments for the options. We can also generate good error messages for any typos or incorrectly options by capturing anything that ends up in the dots