Interfacing C, C++ and Fortran

Source: Writing R Extensions: System and foreign language interfaces

The rest of the page follows that order: the C route with .Call() first, because everything else is a variation of it, then .C() and .Fortran(), .External(), and finally C++ and Rcpp.

A function called through .Call() takes R objects as arguments and returns one. In C, an R object of any type is a SEXP (a pointer to R’s internal node type, described in the next section), so the function takes SEXP arguments and returns a SEXP. The smallest useful function adds two numbers. Rf_asReal() coerces the first element of its argument to a C double, and Rf_ScalarReal() builds a length-one numeric vector from a double; the header Rinternals.h declares both, and R.h the rest of the common API.

Source: Writing R Extensions: Calling .Call

R CMD SHLIB turns the source file into a shared object. It calls make with R’s own rules, so it uses the compiler, the flags and the link line recorded when R was built. The transcript shows the two commands it runs, with the flags shortened (the real lines carry the include directory of this R installation and about a dozen hardening and diagnostic flags) and without the first line it prints, which names the compiler version and the operating system.

Source: R documentation: SHLIB

The first command compiles add.c into an object file; the second links the object file into add.so against libR. The options come from R CMD SHLIB --help; the transcript is the complete help except its last line, which gives the address for bug reports (the odd "alsp" in the --use-C17 line is in R’s own text).

Source: R documentation: SHLIB

R CMD SHLIB accepts C (.c), C++ (.cc, .cpp), fixed-form Fortran (.f), free-form Fortran (.f90, .f95), Objective C and Objective C++ sources, or object files, or linker options. Files for the Fortran preprocessor (.F) are not accepted. The name of the shared object is taken from the first file unless -o is given. Two details from the manual are worth keeping in mind: make does not rebuild when only the flags changed (use --preclean), and a file named test.c next to test.f makes R CMD SHLIB test.f compile the C file instead (Writing R Extensions: Creating shared objects).

dyn.load() loads a shared object into the running R process, and .Call() then finds the C function by its name. The manual advises against assuming a file extension, and recommends file.path(path1, path2, paste0("mylib", .Platform$dynlib.ext)). The script loads add.so, calls the function with doubles, integers and a missing value, shows that only the first element of each argument is used (because the C code reads it with Rf_asReal()), and shows the two ways to be exact about which shared object a name belongs to: the PACKAGE argument, and a native symbol object from getNativeSymbolInfo().

Source: R documentation: dyn.load

The loaded shared object is listed by getLoadedDLLs(), whose elements are named after the file without the extension. dyn.unload() removes it; the manual calls unloading unnecessary and not safe in general, but needed on some platforms (Windows) to allow the DLL to be rebuilt. Unloading a DLL and reloading a rebuilt one with the same name may not work on every platform (Writing R Extensions: dyn.load and dyn.unload). In practice, when you edit a C file during development, restart R after rebuilding, or use pkgload::load_all() (below), which handles unloading for a package.

PACKAGE matters more than it looks. A bare .Call("add", x, y) asks R to search every loaded shared object, and R’s search order is most recently loaded first; if two packages define a C function called add, the wrong one can be called, with the wrong number of arguments, and that normally crashes R. Writing R Extensions explains that PACKAGE confines the search and speeds it up, and the help page of .Call recommends it or a native symbol object for anything called often. The manual’s timing section measured the difference as small but real for functions called millions of times (Writing R Extensions: Registering native routines).

When the name cannot be found, R says so in a message that is the same on every platform. These are the real texts, captured by tryCatch() (the container’s directory is replaced by <dir> so that the script, not the page, hides the path). The last three lines show the same failure for .C(), .Fortran() and .External(); only .Fortran() says "Fortran symbol name".

Source: R documentation: .Call

The second line of the dyn.load() message is the operating system’s own text (this one is glibc’s), so it differs on macOS and Windows. All four lookup errors have the same remedy: check the spelling, check that the shared object was built from the current source and loaded, and check that the function is not static and, in C++, is declared extern "C".

Every R object that C code touches is a SEXP, a pointer to a structure the headers call SEXPREC. Think of it as a variant type: the same pointer type refers to a numeric vector, a list, a function, an environment, a call or NULL, and TYPEOF(x) returns a code that says which. C code must therefore check the type before it uses the data, and it gets at the data through accessor functions, never by looking inside the structure (the structure is not part of the API and its layout is allowed to change). The types that package code meets most often are these.

Source: Writing R Extensions: Details of R types

Two types in that table deserve a remark. A CHARSXP is not an R-level object but the immutable, shared element of a character vector: R keeps one copy of each distinct string in a global cache, so C code must never modify the bytes behind CHAR(). And LISTSXP is the old Lisp-style pairlist; an R list is a VECSXP, which is why the test for an R list is Rf_isNewList() and not Rf_isList() (Writing R Extensions: Handling lists). R Internals describes all the types, including the ones that are not for packages (R Internals: SEXPs).

The functions in the manual’s examples carry an Rf_ prefix (Rf_allocVector, Rf_error, Rf_ScalarReal), and so do all the examples on this page. R’s headers also define short names for many of them (allocVector, error, length), which are macros that expand to the prefixed names, and those short names clash easily with system headers and other libraries. Defining R_NO_REMAP before any R header removes the macros and leaves only the prefixed names. The manual states the facts that matter: the prefix is optional in C code and recommended for new C code; since R 4.5.0 R_NO_REMAP is always defined when the R headers are included from C++, so C++ code must use the Rf_ names; and a package that defines it itself should guard it with #ifndef R_NO_REMAP to avoid compiler warnings about redefinition (Writing R Extensions: The R API).

The NEWS entries behind that: R 4.4.0 added the environment variable _R_CXX_USE_NO_REMAP_, which makes R CMD INSTALL (and so R CMD check) compile C++ code with -DR_NO_REMAP, and said that this was planned to become the default; R 4.5.0 made it the default and revised the manual to describe the remapped entry points (R NEWS: Changes in R 4.4.0 and 4.5.0). usethis::use_c() writes a template that starts with #define R_NO_REMAP, as the shelf example later shows. Two related switches exist for other headers: R_NO_REMAP_RMATH does the same for Rmath.h (the distribution functions), and STRICT_R_HEADERS, which removes the old S-compatibility definitions (PI, Calloc, Realloc, Free and the DOUBLE_* constants), has been the default since R 4.5.0, with R_Calloc, R_Realloc, R_Free and M_PI as the replacements.

The next file has three functions that show the pattern every .Call() routine follows: check or coerce the arguments, allocate the result, fill it through a pointer, copy the attributes that should survive, and return. overdue_days() requires a double vector and returns the days beyond the loan limit element by element; is_late() coerces to integers and returns a logical vector; count_late() calls is_late() and counts.

Source: Writing R Extensions: Handling R objects in C

Several points in the file are worth a line each.

The script builds the R wrappers, calls the functions on a vector of loan durations that contains a missing value (NA) and a not-a-number (NaN), and shows what the type check does. storage.mode<- in the wrapper converts to double while keeping the names, which as.double() would drop.

Source: R documentation: mode and storage.mode

overdue_days() passes both NA and NaN through unchanged because it copies the element when ISNAN() is true. That is a deliberate choice: the next table shows that C distinguishes the two only with ISNA(), and it is easy to turn every NaN into NA by writing NA_REAL where the input should have been kept.

R’s missing values are values of the C types, and each type has its own constant and its own test.

Source: Writing R Extensions: Missing and IEEE special values

The manual adds that these tests apply to doubles only, that isfinite() should not be used in place of R_FINITE(), and that Inf and -Inf are tested by comparing with R_PosInf and R_NegInf. .Call() passes missing values straight into the C code; it is .C() that refuses them unless NAOK = TRUE, as a later section shows.

A character vector is a STRSXP: a vector whose elements are CHARSXP nodes. Reading goes through STRING_ELT() and CHAR(); writing builds a CHARSXP with Rf_mkChar() (from a NUL-terminated C string), Rf_mkCharLen() (from part of a buffer) or Rf_mkCharLenCE() (with an encoding mark) and stores it with SET_STRING_ELT(). Rf_mkString() makes a whole length-one character vector from a C string, and Rf_ScalarString() from a CHARSXP. The function below keeps the first blank-delimited word of each string, passes NA through, and, because it copies the bytes of an element it did not interpret, copies the encoding mark of the original with it.

Source: Writing R Extensions: Handling character data

The encoding rules are the part of this that goes wrong in practice. A CHARSXP can be marked as UTF-8 or Latin-1, and the bytes behind CHAR() are in whatever encoding the mark says. When C code needs to interpret the characters, the manual recommends Rf_translateChar() (to the current locale’s encoding) or Rf_translateCharUTF8() (to UTF-8, which almost always represents the string faithfully), because both handle any input and allocate with R_alloc(); and when it only moves a string unchanged, as here, it should keep the mark with Rf_getCharCE() and Rf_mkCharLenCE() (Writing R Extensions: Character encoding issues). The help page of .C() adds a reason to prefer .Call() for text: a missing string reaches .C() code as the text "NA", which cannot be told from a real "NA".

Lists, classes and dimensions are all attributes and vectors of vectors. loan_stats() below builds a named list with Rf_mkNamed() (which takes a C array of names ended by an empty string), fills its three elements with SET_VECTOR_ELT(), and sets the class attribute with Rf_classgets(). day_gaps() allocates a matrix with Rf_allocMatrix() (column-major, like R) and sets dimnames to a two-element list, reusing the names of the input for both dimensions. A data frame is a list of equal-length columns with names, row.names and class attributes; it is simplest to build the columns in C and call as.data.frame() or data.frame() in the R wrapper (Rcpp, later, does it in one expression).

Source: Writing R Extensions: Attributes

Both functions follow the protection rule: every object that is created and then kept while something else is allocated is protected, and the count of UNPROTECT() matches. In loan_stats() the three scalars are not protected separately because they are handed to SET_VECTOR_ELT() immediately, and the list that now owns them is protected. The manual explains this: protecting an object protects everything it points to, so the elements of a protected list are protected. In day_gaps() the dimnames list is protected with its own PROTECT() and released with an UNPROTECT(1) as soon as it has been attached.

One script exercises both strings.c and structures.c. It feeds first_word() an ASCII vector with an NA and an empty string, then an accented name written as a UTF-8 string literal: the result is still marked UTF-8. It then prints the list from loan_stats() and gives the class a print method in R, and finally shows the dimnames of the matrix.

Source: Writing R Extensions: Classes

C code reports problems to R with Rf_error() and Rf_warning(), which take a printf-style format and have the same effect as stop() and warning() in R code. Output goes through Rprintf() (R’s standard output, which a GUI console, sink() or a parallel worker may redirect) and REprintf() (R’s error stream), never printf() to the C library’s stdout, whose text may not appear in the console at all; writing complete lines is advised. A long loop should call R_CheckUserInterrupt() now and then, because no part of R can be interrupted while it runs compiled code otherwise.

Source: Writing R Extensions: Error signaling

There are rules to follow in these functions. Rf_error() never returns: R implements it as a non-local jump (a longjmp) to the nearest tryCatch() or the top level, skipping the C code between, so nothing after the call runs: memory from R_alloc() is reclaimed by R on an error, memory from R_Calloc() is not, and R restores the protect stack by itself. The format string is a template, so a message that comes from data must go through "%s" (Rf_error("%s", msg)), or a % in it will be interpreted. Rf_errorcall(call, ...) and Rf_warningcall(call, ...) take the call to blame, and R_NilValue omits it. The script shows what R makes of them. The error is an ordinary simpleError whose call is that of the R function that called .Call(); capture.output() sees the Rprintf() line, and its type = "message" form sees the REprintf() line.

Source: R documentation: capture.output

The call shown in deparse(conditionCall(err)) is checked_sqrt(-4), the wrapper, which is what a user of the function wants in the message; the unwrapped .Call("checked_sqrt", x, PACKAGE = "conditions") would not help them. The last lines run busy(), the loop with R_CheckUserInterrupt(); it finishes here because nobody presses Ctrl-C. The manual gives a version for Fortran, rchkusr(), and adds that the code behind many API entry points can itself be interrupted or raise an error, so any C code that holds a resource should be written with that in mind (Writing R Extensions: Allowing interrupts).

When the resource is a file, a lock, or a buffer from R_Calloc(), the tools for a clean exit are in the manual’s section on condition handling and cleanup code: R_UnwindProtect() runs a cleanup function on both normal return and non-local jumps, R_ExecWithCleanup() is the older and simpler form, and R_tryCatch() and R_tryEval() catch conditions (Writing R Extensions: Condition handling and cleanup code). An alternative that avoids the problem is to keep the allocation in R: allocate the buffer in R (numeric(n)) and pass it in.

C code can call back into R. The routine below receives a function f, a vector and an environment, and applies the function to each element with Rf_lang2() (which builds the call f(arg)) and Rf_eval(). Each intermediate object is protected, and the check of the result’s type is made in C, since the function could return anything. The environment rho is passed from R as environment() because the API has no supported entry point for the current environment (the manual’s table of replacements tells packages to call environment() in R and pass the result).

Source: Writing R Extensions: Evaluating R expressions from C

An error inside f is an ordinary R error: it unwinds through the C function and arrives at the caller’s tryCatch(), so the message is the one that f raised. The two checks in the C code give the other two messages.

Source: Writing R Extensions: Evaluating R expressions from C

A callback costs as much as an R function call, so a loop that calls R on every element gives back most of what the C code saved. Callbacks are for the occasional call (an objective function in an optimiser, a user hook) rather than for the inner loop.

The manual’s rules for .Call() and .External() code can be written as a short list.

R frees the memory of objects automatically, by garbage collection, and it can run the collector whenever it allocates anything. An object that C code has just created and holds only in a local variable is invisible to the collector: nothing in R’s own data structures refers to it, so the next allocation can free it, and the pointer in the C variable then points at memory that may be reused. The result is not an error but corrupt output or a crash, often much later and somewhere else. PROTECT() puts the object on a stack that the collector treats as a root, and UNPROTECT(n) pops the last n entries. Writing R Extensions states the rule precisely: it is the object that is protected, not the pointer variable, so assigning a different object to p after PROTECT(p) leaves the new object unprotected (Writing R Extensions: Handling the effects of garbage collection).

The protect stack has rules, and the manual lists four of them for functions that cooperate.

The simplest style follows from them: SEXP x = PROTECT(Rf_allocVector(...)); on creation, one UNPROTECT(n) before every return, with n the number of objects protected in that function. The stack has a fixed size (10,000 entries by default), so a loop must not protect something new on every iteration without releasing it, and the better design is to store objects in a protected container (a list) or to unprotect them immediately after use. callback.c above does exactly that: it protects three objects inside the loop and UNPROTECT(3) at the end of each iteration. Anything allocated and handed straight to SET_VECTOR_ELT() or SET_STRING_ELT() is safe from then on, as loan_stats() shows.

The rule that the object is protected, and not the pointer, means that code that replaces a protected object (by coercing, duplicating or growing it) must protect the replacement. When the old object is no longer needed, PROTECT_WITH_INDEX(s, &ipx) records the stack position and REPROTECT(s, ipx) stores a new object in that position, so the stack does not grow. total_days() below coerces an integer argument to double only if it needs to, and keeps whichever object it ends up using protected under one index.

Source: Writing R Extensions: Handling the effects of garbage collection

The file also contains the two classic mistakes, in functions that compile without a warning and return the right number: leaky() has one PROTECT() too many (it forgot UNPROTECT(1)), and too_many() has one UNPROTECT() too many. .Call() checks the protect stack when a routine returns, and when the count has changed it prints a warning. The text of that warning is real; the two numbers are the size of the protect stack before and after the call, so they depend on how deeply R is nested at that moment, and the values below are the ones from a top-level Rscript run. A leak makes the second number larger, an excess UNPROTECT() makes it smaller. The messages are written directly to the error stream when the routine returns, before the value is printed, so they are not conditions: tryCatch(..., warning = ) and withCallingHandlers() do not see them (in this test the handler did not run). The wrong routines still return 2.

Source: Writing R Extensions: Handling the effects of garbage collection

The messages catch only a mismatch in the count. A missing PROTECT() is silent until the collector runs at the wrong moment, and that is much harder to find. R has two tools for it. gctorture(TRUE) makes the collector run on nearly every allocation, so an unprotected object is freed at once and the crash happens close to its cause; R CMD check --use-gct runs a package’s examples, tests and vignettes that way (R documentation: gctorture). A build of R configured with --enable-strict-barrier also marks freed nodes, so touching one raises an error that names the old type. The sections on checking memory access in Writing R Extensions describe these, Valgrind and the address sanitizer (Writing R Extensions: Checking memory access).

PROTECT() is for the duration of one call. An object that has to survive between calls (a cache, a handle returned to R as an external pointer) is kept alive with R_PreserveObject(x) and released with R_ReleaseObject(x); the manual calls this less efficient than normal protection and to be used sparingly, because releasing it is then the author’s responsibility, usually from a finalizer. For parsers there is a multi-set interface (R_NewPreciousMSet, R_PreserveInMSet, R_ReleaseFromMSet), and the old UNPROTECT_PTR() is dangerous to mix with UNPROTECT() and is not for new code. External pointers, which wrap a C pointer in an R object with a finalizer, are the way to return a C data structure to R, and have their own section (Writing R Extensions: External pointers and weak references).

So far every routine was found by its name, by searching the symbols of the shared object. The rest of the page uses one routine as its running example: the ISBN-13 check of the shelf package. It takes a character vector and returns a logical vector. Its rule is the one is_valid_isbn13() implements in R: keep the digits, reject an X, require exactly 13 digits, and require that the digits multiplied alternately by 1 and 3 add up to a multiple of 10. NA and the empty string are FALSE. The file has a header with the prototype, and starts with #define R_NO_REMAP, so every R function in it carries the Rf_ prefix. The constant ISBN_DIGITS has a default and can be overridden from the compiler command line, which the src/Makevars section uses.

Source: Writing R Extensions: Handling R objects in C

Source: Writing R Extensions: Registering native routines

Built with R CMD SHLIB isbn.c and loaded as before, the routine agrees with the R version on a vector that contains valid ISBNs in hyphenated and bare forms, one with a wrong check digit, the empty string, NA, a ten-digit ISBN-10 and a string with an X. The comparison function is the R version from the shelf package, copied into the script because the script runs in the directory of the compiled objects.

Source: R documentation: .Call

Registration replaces the search by a table that the shared object builds when it is loaded. When R loads foo.so, it looks for a function named R_init_foo and calls it with a DllInfo pointer; when it unloads the object, it calls R_unload_foo if there is one. The name is made from the file name without its extension, so it must be a valid part of a C identifier: the manual advises ASCII letters, digits and underscores only. The initialiser calls R_registerRoutines() with five arguments: the DllInfo, and one NULL-terminated array for each interface, in the order .C(), .Call(), .Fortran(), .External(). The array element types are R_CMethodDef, R_CallMethodDef, R_FortranMethodDef and R_ExternalMethodDef. Each entry holds the name by which R refers to the routine, a function pointer cast to DL_FUNC, and the number of arguments; .External() routines use -1 for "any number". The entries for .C() and .Fortran() may add an array of argument types (REALSXP, INTSXP, LGLSXP, STRSXP, VECSXP, SINGLESXP) that R checks on every call.

Source: Writing R Extensions: Registering native routines

Two more calls close the loophole of finding things by string. R_useDynamicSymbols(dll, FALSE) says that the shared object is not to be searched for symbols not in the table, so .Call("name") finds only registered names. R_forceSymbols(dll, TRUE) says that foreign function calls into this object must name the entry point with an R object (a native symbol object), and not with a character string at all. The manual’s example uses a package mypkg with a registered routine reg and an unregistered unreg: without registration both .Call("reg") and .Call("unreg") work; with R_useDynamicSymbols(dll, FALSE) only the first does; with useDynLib(mypkg, .registration = TRUE, .fixes = "C_") in NAMESPACE, .Call(C_reg) works too; and with R_forceSymbols(dll, TRUE) only .Call(C_reg) works. That last arrangement is what a package normally wants: all its own calls go directly to its own code, and nobody finds its entry points by accident. A user who needs one from outside, for debugging, can write .Call(mypkg:::C_reg).

The next script builds this object as shelf.so (R CMD SHLIB -o shelf.so isbn.c init.c; the file name makes R_init_shelf() the initialiser), loads it next to the unregistered isbn.so, and shows the registered routine as an R object, the call by object, the call by string on the unregistered object, and what the two registered-only settings do to the string calls and to a wrong number of arguments. The object returned by getDLLRegisteredRoutines() lists the table; routines$.Call$isbn13_valid is a native symbol object.

Source: R documentation: getDLLRegisteredRoutines

Both error messages are R’s. The string call to the forced object says that the name is not available "for package shelf", although the routine exists, because the object refuses string lookups; and a wrong number of arguments is an error that names the routine and both counts, instead of undefined behaviour in C.

tools::package_native_routine_registration_skeleton() writes the init.c for you. It reads the R code of a package for .C(), .Call(), .Fortran() and .External() calls, takes the routine names and the number of arguments from the calls, and prints C source with the FIXME comment that reminds you to check the declarations against the C code. NEWS for R 3.4.0 says it automated registration for over 90% of the CRAN packages that lacked it, and that many of its failures were real bugs in the packages: dozens called entry points with varying numbers of arguments or entry points that were not there. The script builds a throwaway package whose R code still calls .Call("isbn13_valid", x, PACKAGE = "shelf") and runs the tool on it.

Source: R documentation: package_native_routine_registration_skeleton

The output is the starting point, not the end: the prototype extern SEXP isbn13_valid(SEXP); is guessed from the call and belongs in a header (as isbn.h here), the argument counts have to be checked, and R_forceSymbols() is not added. The manual’s walk-through of converting the splines package lists the remaining steps: add useDynLib(pkg, .registration = TRUE) to NAMESPACE; change .Call("name", ..., PACKAGE = "pkg") calls to .Call(name, ...) with the R object; add R_useDynamicSymbols(dll, FALSE) and then R_forceSymbols(dll, TRUE); and consider hiding the C functions from the symbol table (Writing R Extensions: Example: converting a package to use registration). Hiding is done with attribute_hidden on each function, or with PKG_CFLAGS = $(C_VISIBILITY) in src/Makevars together with attribute_visible on R_init_pkg alone (Writing R Extensions: Controlling visibility); it removes any chance of a name clash and speeds up loading slightly. Fortran entry points cannot use attribute_hidden; the variable F_VISIBILITY does the job for them.

The NAMESPACE file loads the shared object and, with .registration = TRUE, creates in the package’s namespace one R variable for each registered routine. The directive has more forms, all from the manual.

Source: Writing R Extensions: useDynLib

The manual adds a caution: using .registration or .fixes for a package that does not register its routines only slows loading, and once routines are registered, the new R variables must not be exported by accident by an exportPattern() in NAMESPACE. With roxygen2 the directive is written in the R sources as @useDynLib shelf, .registration = TRUE (and the same for the .fixes argument), usually in the package-level help file, and devtools::document() copies it into NAMESPACE. The next section does exactly that, and usethis::use_c() and usethis::use_rcpp() print the lines to paste.

R also checks all of this. R CMD check tests every foreign function call for a PACKAGE argument, or a way to deduce the DLL, and tools::checkFF() reports the cases that need attention (R documentation: checkFF). Since R 3.4.0, R CMD check --as-cran notes a package that neither registers its routines nor declares what it does about symbol search. The environment variable _R_CHECK_NATIVE_ROUTINE_REGISTRATION_ makes R CMD check report packages whose DLL lacks the registration entry points (it needs the nm utility on the PATH, and objdump on Windows); the section on tools in R Internals documents it (R Internals: Tools). The real report is shown in the section on the C API, from a package that fails it.

usethis::use_c() creates src/, a .gitignore inside it that keeps the compiled .o, .so and .dll files out of version control, and a template source file. It prints the lines to paste into the package-level R file. Both in this transcript and below, the path is shortened.

Source: usethis package documentation: use_c

The template src/isbn.c has three lines (#define R_NO_REMAP, #include <R.h> and #include <Rinternals.h>); it was replaced by the isbn.c shown earlier. The R file named in the message holds the roxygen tag, and a second file has the wrapper. The wrapper coerces with as.character() in R, where a factor is converted properly, and passes the registered symbol object to .Call(); because NAMESPACE has .registration = TRUE, the variable isbn13_valid exists in the namespace.

Source: roxygen2 package documentation: Managing imports and exports

Source: Writing R Extensions: Calling .Call

devtools::document() runs roxygen2, which loads the package first, so it compiles src/. pkgload::load_all() (called by devtools::load_all()) compiles src/ with pkgbuild::compile_dll() when a source file is newer than the object, and loads the result with the R code, which is the edit-compile-test loop of package development. It builds with debugging flags (-UNDEBUG -Wall -pedantic -g -O0), so compiler warnings appear while you work, and the transcript below shows them quiet because the code compiles cleanly. Two details are visible in the output: the -DISBN_DIGITS=13 that comes from src/Makevars, and that Writing 'NAMESPACE' appears twice, once before the package is compiled and loaded and once after. The compiler lines are shortened, the first line that names the compiler is omitted, and so is the line that prints the temporary library the package is installed into.

Source: devtools package documentation: document

The generated NAMESPACE gains two lines, the export of the new function and the useDynLib() directive; the rest is the file of the earlier pages.

Source: Writing R Extensions: useDynLib

One practical trap is worth knowing. make knows which .c file produced which .o file, but not which headers a file includes. If only isbn.h changes, nothing is rebuilt, and the second R CMD INSTALL of an unchanged tree says so, with this real line in place of the compiler lines:

Source: Writing R Extensions: Creating shared objects

Delete the .o and .so files in src/ (or use R CMD INSTALL --preclean, or pkgbuild::clean_dll()) after changing a header, a Makevars file or the compiler flags. R CMD build cleans src/ itself when it makes the tarball (the build prints * cleaning src), which is why compiled objects never belong in a source package.

The command a user types is R CMD INSTALL shelf in the directory that contains the package. It compiles src/ with R’s own flags (not the debug flags of load_all()), installs, and tests that the installed package loads. The transcript keeps the lines that concern the compiled code, shortens the compiler lines as before, and marks the omitted ones with [...]; the container’s temporary paths in the other lines are dropped.

Source: R documentation: INSTALL

With the package installed, the script loads it and checks the compiled function against the R one on the books data set of the package, and looks at what registration created: the routine in the registration table with its arity, the R variable isbn13_valid in the namespace, and the loaded DLL.

Source: R documentation: getLoadedDLLs

The compiled function and the R function return the same logical vector on the sixteen ISBNs of the data set, of which fourteen are valid. tools::checkFF() found nothing to report.

R CMD check has several checks for compiled code. The transcript is the relevant part of R CMD check --as-cran --no-manual --no-tests --ignore-vignettes on the built tarball, with the remote CRAN-incoming checks off and the header that names the platform removed. Every line shown is OK. The checks that did not appear are those about the quick options used here (vignettes and tests were skipped, so this is not the full check of the earlier pages).

Source: Writing R Extensions: Checking and building packages

Two of those lines concern files you write for compiled code: "checking compilation flags in Makevars" (the check that rejects -Wall and friends in PKG_CFLAGS, shown to fail in the section on src/Makevars) and "checking compiled code" (the check of the API usage, shown to fail in the section on the C API). The container’s R was built with distribution flags, so the full check also reported a NOTE that the compilation used non-portable flags such as -Wformat; it comes from how this R was built, not from the package, and is not shown.

The manual says in so many words not to put compiler-specific diagnostic flags in a distributed Makevars: -O2, -Wall, -pedantic and every other -W flag are specific to GCC and compilers that copy its options (for Oracle’s compilers, -W flags passed arguments to compiler phases). Variables such as CPPFLAGS and CFLAGS themselves must not be set at all, because users and sites set them. R CMD check enforces this. This is the real output of R CMD check --as-cran on a deliberately wrong tiny package (probe, shown in the section on the C API) whose src/Makevars is the single line PKG_CFLAGS = -Wall -O3:

Source: Writing R Extensions: Using Makevars

The right place for warnings is the developer’s own Makevars file. The manual encourages package developers to enable a reasonable amount of compiler diagnostics this way, for example -Wall -pedantic for GCC and LLVM. The personal file is ~/.R/Makevars (or ~/.R/Makevars-<platform>, or Makevars.win on Windows), or any file named by the environment variable R_MAKEVARS_USER; there is also a site-wide Makevars.site and R_MAKEVARS_SITE; the R FAQ answers the question of changing flags in one short entry that points to the same manual section (R FAQ 8.4: How can I change compilation flags?). The file used for every example on this page (its path given with R_MAKEVARS_USER for the test run) is:

Source: R Installation and Administration: Customizing package compilation

It sets the flags for all four compilers (the variables are CFLAGS, CXXFLAGS, FFLAGS and FCFLAGS) and switches off optimisation so that the compiler’s analysis is simple. When the C standard or C++ standard is non-default the matching variable (C17FLAGS, CXX20FLAGS, and so on) must be set instead. The effect is easy to see on a file that is sloppy in the way -Wall catches:

Source: Writing R Extensions: Using Makevars

Source: R Installation and Administration: Customizing package compilation

The -Wextra flag is stricter than -Wall and is worth trying, with one known exception: the idiom (DL_FUNC) &name in a registration table converts a function pointer to another function pointer type, and -Wextra (through -Wcast-function-type) reports it on each entry. That is why the file above uses -Wall -pedantic. All the C, C++ and Fortran files in this page were built with these flags and produced no warning.

R compiles package C++ code with a standard that depends on the R version, and the manual’s advice is to say which standard the code needs. The NEWS entries are: R 4.3.0 changed the default to C++17 where available (C++14 or C++11 otherwise); the manual says that from R 4.4.0 only a C++17 compiler is selected as the default; R 4.6.0 changed the default to C++20 where available, and otherwise C++17, and C++11 and C++14 are no longer supported; and packages can request C++17 if they need it. Newer standards (C++23, C++26) can be requested as the compiler allows. The request is made in two places that must agree: CXX_STD = CXX17 in src/Makevars (and Makevars.win, Makevars.ucrt), and SystemRequirements: C++17 in DESCRIPTION; if they differ, SystemRequirements wins, and R CMD check checks that they match. Code that wants a feature of a newer standard should test for it, with the standard’s feature-test macros, rather than assume it.

The next pair of runs makes this visible. std.cpp returns the value of __cplusplus that its compiler saw, and a constant that comes from the command line.

Source: Writing R Extensions: Using C++ code

Source: Writing R Extensions: Using Makevars

Built in a directory with no Makevars, the compiler uses R’s default; built in a directory with the file above, R CMD SHLIB honours CXX_STD and PKG_CPPFLAGS. The compile line of the second build is

Source: Writing R Extensions: Using C++ code

(without the line that names the compiler and the system, and with the flags shortened as before; specified C++17 and using C++17 are R’s own lines, and the -DLOAN_DAYS=28 comes from PKG_CPPFLAGS). The script loads whichever std.so is in the current directory and asks it. Run in the directory that was built without a Makevars, it prints the lines shown after the code.

Source: Writing R Extensions: Using C++ code

Run in the directory that has the Makevars (the previous script, saved as check-standard.R one directory up), it reports the standard and the constant that the file asked for:

Source: Writing R Extensions: Using C++ code

The numbers are the values of __cplusplus: 202002 is C++20 (the R 4.6 default) and 201703 is C++17. For a package that has src/Makefile instead of Makevars, the manual shows how to take the compiler from R CMD config CXX20 and its relatives; a configure script must do the same, and must not hard-code g++.

For C, R 4.5.0 made the configure script choose a compiler option that selects C23 when one is available (gcc 15 defaults to C23 on its own). The effect on package code is stricter C: bool, true and false are keywords, K&R-style declarations are gone, and an empty parameter list now means no parameters, so code that relied on an unprototyped declaration can stop compiling. A package that cannot move can ask for an older standard with USE_C17 (or USE_C99, USE_C90) in SystemRequirements, and a user can force one when installing with R CMD INSTALL --use-C17; the same option exists for R CMD SHLIB, as its help shows. The __STDC_VERSION__ macro tells which standard the compiler claims (202311L for C23; some compilers used 202000L for a draft), but the manual advises testing for the feature the code needs and not the version (Writing R Extensions: C standards). The Fortran side has its own page in this section, and the Fortran Reference covers the language.

OpenMP is the usual way to use several threads inside compiled code. The compiler flag differs between compilers, so a package takes it from R: it puts $(SHLIB_OPENMP_CFLAGS) in both PKG_CFLAGS and PKG_LIBS for C code (and SHLIB_OPENMP_CXXFLAGS and SHLIB_OPENMP_FFLAGS for the other two languages, with a different recipe for Fortran), guards OpenMP-specific code with #ifdef _OPENMP, and includes the macros only when the code really uses OpenMP. Some toolchains, Apple’s clang among them, have no OpenMP support at all, and a note in the manual says that the C++ macro applies to the default C++ compiler and not necessarily to the one selected for C++17 or C++20, for which a configure check is advised. Writing -fopenmp directly into PKG_CXXFLAGS works with gcc and fails elsewhere, which is why R CMD check has a check named "checking use of SHLIB_OPENMP_*FLAGS in Makefiles" (it appears in the transcript of the earlier section). Calling the R API from threaded code is, in the manual’s words, for experts only and strongly discouraged: the R API changes internal data structures, and errors must be signalled only from the main thread. The threading model of R’s parallel packages is the subject of Parallel and Asynchronous Computing; the manual’s section is OpenMP support.

.C() is the traditional interface and the simplest to write for: the C function takes pointers to plain C data and returns void. R copies each argument, passes a pointer to the copy, and returns a list of the (possibly modified) copies, with the names that were given to the arguments. No R header is needed, and the C function does not have to know it is called from R. The mapping from R storage modes to C types is fixed.

Source: R documentation: .C

A logical is sent as 0, 1 or INT_MIN (the last only when NAOK = TRUE), and the code should return one of the three values. The C type for an R integer is int, which is 32 bits on every platform R runs on, and not long: code ported from S-PLUS that used long * is wrong on most 64-bit platforms (Writing R Extensions: Interface functions .C and .Fortran). Strings need most care. On entry the contents of a character vector are copied to a char ** array; the C code can shorten a string by writing a '\0', but it cannot lengthen one, and a missing string arrives as the text "NA". For anything that is not plain numbers, use .Call().

The convolution of two sequences, the manual’s own example, makes the routine. convolve() takes the two sequences and their lengths as pointers and fills a result array that the caller allocated, since a C function cannot return a vector through .C(); the R wrapper allocates it with double(length(a) + length(b) - 1) and names it so that $ab extracts it from the returned list. The file also registers a second name, convolve_checked, for the same function with its argument types, which is how the type check below is made.

Source: Writing R Extensions: Interface functions .C and .Fortran

The script shows the list that .C() returns, the refusal of missing values, the effect of a type mistake on an unregistered routine, the registered version of the check, and the old DUP argument. A few results need explaining.

Source: R documentation: .C

A fairly common cause of crashes in .C() and .Fortran() code is writing a little beyond the end of an argument, which corrupts something else and crashes R later. options(CBoundsCheck = TRUE) (or the environment variable R_C_BOUNDS_CHECK=yes) changes how R copies the arguments: it adds 64 guard bytes at both ends of each copy and checks them on return. overrun() below has the classic off-by-one, a loop that runs to i <= *n.

Source: Writing R Extensions: Debugging compiled code

Source: R documentation: .C

The message names the call, the type and the argument number. It is a debugging aid: it makes every call slower, it is off by default, and it detects only writes in the guard zones.

loan_totals adds up the days beyond the loan period and counts the late loans. Every argument is declared with its intent, which is how Fortran says "input" and "output", and the sizes come from the array lengths that R passes in. The -Wall -pedantic flags of the personal Makevars compile it without warnings.

Source: Writing R Extensions: Interface functions .C and .Fortran

Fortran print and write statements to the default unit are not guaranteed to appear in the R console, may not interleave with C output, and on Windows interfere with C’s own output (the manual describes how gfortran’s initialisation changes the line endings of C’s stdout and how to undo it in R_init_<pkg>). R therefore provides subroutines that print through R’s own channels: labelpr(label, nchar) prints a label, intpr1(label, nchar, var), realpr1() and dblepr1() print a labelled scalar, and intpr(), realpr() and dblepr() print a labelled array (label, nchar, data, ndata); nchar is the length of the label, or -1 for all of it. There is no check on the type: a real passed to dblepr prints nonsense. For conditions, rexit(message) signals an error and rwarn(message) a warning (messages are cut to 255 characters), and rchkusr() is the interrupt check. fortran_io.f90 uses all of them.

Source: Writing R Extensions: Printing from Fortran

Random numbers are the other thing Fortran code must not do itself. The Fortran 90 random_number and random_seed, GNU’s rand, and the C library’s rand all keep a state that is private to the library: packages cannot initialise it safely, two packages can interfere, and the user’s set.seed() does not reach it. The manual’s rule is to use R’s generator, which a routine reaches by bracketing the draws with GetRNGstate() and PutRNGstate() and calling unif_rand() (or norm_rand(), exp_rand()), and it shows how to bind those C entry points from Fortran with iso_c_binding (Writing R Extensions: Random-number generation from Fortran). rngdemo.f90 does this without a line of C.

Source: Writing R Extensions: Random-number generation from Fortran

For Fortran 90 and later code the help page of .Fortran() and the manual give the same advice: the most portable way is to give the subroutine a C interface with iso_c_binding and call it with .C(). With bind(C, name = "isbn_check_digit") the routine has exactly the C name given, the kinds c_int and c_double say exactly what C types the arguments are, and the compiler can check the declaration. isbn_check_digit computes the 13th digit of an ISBN from the first twelve.

Source: Writing R Extensions: Interface functions .C and .Fortran

The script calls all four Fortran files. In the results, late_total is 49 and late_count is 3 for five loans of 14, 35, 28, 21 and 49 days against a limit of 21; summarise prints through R (the label lines and the values), warns for a single loan with the message summarise: only one loan, and stops with summarise: no loans for none (the mean of 14, 35 and 28 appears as 25.7, not 25.66667: dblepr1 uses R’s internal real-vector printer, and in this script the preceding str(res) left that printer’s number of significant digits at 3, as format() with a digits argument does too; a print() call resets it to getOption("digits"), after which the same .Fortran() call prints 25.66667, which is what was observed when the three variants were run); the draws made in Fortran are identical to ceiling(28 * runif(5)) after the same set.seed(); and the ISBN of the Le Guin entry in the catalogue has check digit 7.

Source: R documentation: .Fortran

A registered .Fortran() routine needs a prototype in C, because the registration table is C. The prototype uses F77_NAME(loan_totals) for the name, with every argument a pointer; and a Fortran LOGICAL is declared int * in C, or better void *, because gfortran reports int_least32_t * and link-time optimisation would otherwise warn. The entry goes in an R_FortranMethodDef table, with the argument types, as the manual’s example for .C() did. R_init_<name> is named after the shared object, which is why the object is built as loantot.so.

Source: Writing R Extensions: Registering native routines

The registration table makes the same checks as for .C(), here with Fortran’s type names in the message. The script loads the object built with R CMD SHLIB -o loantot.so loan_totals.f90 fortran_init.c.

Source: R documentation: getDLLRegisteredRoutines

Two kinds of argument are not portable and need a special mention, and both are covered in the manual’s section on calling C from Fortran and vice versa.

Passing C functions to Fortran as arguments (callbacks) depends on the two compilers agreeing on the calling convention and has failed in practice; the manual’s most portable suggestion is to convert the Fortran to C. For everything about the Fortran language and about calling it from C, C++ and Python, the Fortran Reference section added by issue #277 has the pages Interoperability with C, Calling Fortran from C, C++ and Python and BLAS, LAPACK and Numerical Libraries, and the C build and tooling page explains the compilers and linkers involved.

The .Call() routines of the earlier sections have a lot of ceremony that is the same each time: the SEXP signature, the coercion, the allocation, the PROTECT() and UNPROTECT() bookkeeping, the loop over REAL(x), the wrapper that attaches the attributes, the registration table and the R_init function, and the R function that calls .Call(). Rcpp attributes generate all of them. A C++ function whose signature uses Rcpp types and which is marked with // [[Rcpp::export]] is turned into an R function with the same name and arguments, including default values; the glue is generated into a pair of files in a package (RcppExports.cpp and RcppExports.R) or compiled on the fly by cppFunction() and sourceCpp().

Source: Rcpp package documentation: Rcpp-introduction vignette

Rcpp also provides "sugar": vectorised expressions that look like R and run as C++ loops. sum(x), mean(x), ifelse(cond, a, b), is_na(x), any(...), cumsum(x), rev(x), x > limit, x - limit and many more are defined for the vector classes, so a loop can often be replaced by an expression; the sugar vignette lists them (Rcpp package documentation: Rcpp-sugar vignette).

evalCpp("2 + 2") compiles one C++ expression and returns its value, which is the quickest check that the toolchain works. cppFunction(code) takes the source of one function as a string, adds #include <Rcpp.h> and using namespace Rcpp;, compiles it with the C++ standard of the running R, and returns an R function. The arguments depends, plugins and includes add compile-time dependencies, plugin settings and extra includes; rebuild forces recompilation, and showOutput and verbose show what the compiler does (Rcpp package documentation: cppFunction). The script defines the two running examples, the overdue loop and the ISBN-13 check, from strings. The result of the second is compared with the C version above on the same five inputs.

Source: Rcpp package documentation: evalCpp

The default argument of the C++ function (double limit = 21) is carried over to the R function, which args() shows. Compilation is slow the first time, because the Rcpp headers are large, and the result is cached for the session: the same code string compiles once.

sourceCpp("file.cpp") does the same for a file that may define many functions and helpers. It parses the file for // [[Rcpp::export]] attributes (and for RCPP_MODULE declarations), builds a shared library in a temporary directory (the build is cached, and only redone when the file changes unless rebuild = TRUE), and defines the exported functions in the calling environment. /*** R blocks in the file are R code that runs after compilation, which turns the C++ file into a self-testing script. Attributes also exist for dependencies (// [[Rcpp::depends(RcppArmadillo)]] adds the include path and flags of a package) and for plugins (// [[Rcpp::plugins(cpp17)]] requests a standard; the installed plugins include cpp11 to cpp26, openmp and unwindProtect). Its help page lists the other arguments: embeddedR, cacheDir, showOutput, verbose, dryRun and echo (Rcpp package documentation: sourceCpp). The help page also says that sourceCpp() is for one file whose only dependencies are R packages; for more files or external libraries, make a package.

loans.cpp has five exported functions. overdue_days_loop() is the C++ version of the loop of vectors.c; overdue_days_sugar() is the same job in one sugar expression; loan_stats() builds the classed list of structures.c in one expression; flag_late() takes a data frame and returns a data frame with a logical column; and mean_days() writes to Rcout, warns and stops. Nothing in the file mentions SEXP, PROTECT or .Call.

Source: Rcpp package documentation: sourceCpp

A few lines of the script deserve a reading. The first printed block is the output of the /*** R block, echoed because echo = TRUE is the default, and printed by R as soon as the compilation finishes. The loop version keeps the names of the input (it copies the attribute) and the sugar version drops them, which is why only the first of the two printed vectors has a header line. loan_stats() returns what the C version returned, with the class attribute set from C++. flag_late() shows the data-frame round trip. And the last lines show what an error and a warning look like, which the next subsection explains.

Source: Rcpp package documentation: sourceCpp

Rcpp::stop("no loans") throws a C++ exception, the wrapper that Rcpp generates around every exported function catches it and calls R’s error machinery, and the result is an ordinary R error whose message is the text. It is a condition of class Rcpp::exception, C++Error, error, condition, as the last line of the output of the script shows, so tryCatch(..., error = ) handles it and conditionMessage() returns no loans. A C++ exception derived from std::exception is converted the same way, with the text of what(). Rcpp::warning() signals an R warning that withCallingHandlers() can handle, and Rcout writes through R’s output, so capture.output() and sink() see it. In the script, mean_days(c(14, 35)) prints averaging 2 loans through Rcout and returns 24.5; with c(14, NA, 35) the calling handler prints caught: missing days are ignored to the message stream and muffles the warning, and the function carries on and averages the two known values; and with numeric() the error is caught. Rcpp can also use R_UnwindProtect() so that C++ destructors run when an R error unwinds the stack, and has a plugin named unwindProtect for it.

Compiler errors come out as the compiler wrote them, and R adds its own short error. broken.cpp misspells days as day inside a loop.

Source: Rcpp package documentation: sourceCpp

The script runs sourceCpp() under tryCatch(). The compiler’s lines are written straight to the console, and the transcript keeps the part that matters: the command line is shortened (and its first line, which names the compiler and the system, is omitted), and <R_HOME> replaces the directory in the make line.

Source: Rcpp package documentation: sourceCpp

The R error is the short message that the final lines show, Error 1 occurred building shared library., and the information is in the compiler text before it; the function was not defined. Template errors can fill pages, and the useful line is nearly always the first one that contains error:. With cppFunction() the file name in the messages is a generated temporary file, since the code is a string.

For a package the same function is written in src/isbn.cpp, and compileAttributes() generates the glue. The steps are the ones of the C copy of shelf, with Rcpp in place of init.c. usethis::use_rcpp("isbn") adds Rcpp to the LinkingTo and Imports fields of DESCRIPTION, creates src/ with its .gitignore, writes a template src/isbn.cpp, and prints the two roxygen tags to paste. LinkingTo puts the Rcpp headers on the include path when the package is compiled. Imports makes sure the Rcpp namespace is loaded before the package’s shared object. The manual describes LinkingTo as the way to use the header files of other packages, and says that those packages must also be in Imports or Depends so that they are loaded first (Writing R Extensions: Linking to other packages). The transcript is the output of the call in a fresh copy of shelf, with the path shortened.

Source: usethis package documentation: use_rcpp

The DESCRIPTION of the copy differs from the earlier shelf package only by the two fields that were added at the end.

Source: Writing R Extensions: Package Dependencies

The two roxygen tags go into R/shelf-package.R. @importFrom Rcpp sourceCpp is the tag that usethis prints; it makes roxygen2 write importFrom(Rcpp,sourceCpp) into NAMESPACE, which loads the Rcpp namespace with the package. @useDynLib shelf, .registration = TRUE is the tag already met.

Source: roxygen2 package documentation: Managing imports and exports

src/isbn.cpp is the ISBN check as an exported C++ function. The roxygen comments are written with //' (the C++ form of #'), and compileAttributes() copies them into the generated R file, so the function is documented like any other. @export makes roxygen2 export the generated R function. The file is shorter than the C version because Rcpp supplies the loop over the vector, the allocation and the missing-value test.

Source: Rcpp package documentation: Rcpp-attributes vignette

src/Makevars contains a single line, the C++ standard. R’s own default would be C++20 on R 4.6; the line is shown because it is the form that a package states when it depends on a specific standard (and the SystemRequirements: C++17 field would carry the same requirement).

Source: Writing R Extensions: Using C++ code

Rcpp::compileAttributes() scans src/*.cpp for attributes and writes src/RcppExports.cpp and R/RcppExports.R. It prints what it found. This block is a fragment, not a script: it is run in the package directory and the call has no other lines.

Source: Rcpp package documentation: compileAttributes

(Paths shortened.) Both files are marked "do not edit by hand", and they hold what a hand-written package would have in init.c and in the R wrapper. RcppExports.R is the R function, with the roxygen block copied from the C++ comments and a .Call() to a registered symbol whose name starts with an underscore and the package name:

Source: Rcpp package documentation: compileAttributes

RcppExports.cpp holds the C-callable wrapper (_shelf_is_valid_isbn13_cpp), which converts the argument with Rcpp::traits::input_parameter, calls your function inside BEGIN_RCPP and END_RCPP (the macros that catch exceptions), and the registration: a CallEntries table and an R_init_shelf() that calls R_registerRoutines() and R_useDynamicSymbols(dll, FALSE). That is the registration section of this page, written for you.

Source: Rcpp package documentation: Rcpp-package vignette

After devtools::document() the NAMESPACE has the two directives that were put in the roxygen file, the export of the new function, and nothing else about Rcpp.

Source: Writing R Extensions: useDynLib

devtools::document() loads (compiles) the package, so the first build is part of it; the transcript is the same as for the C copy with C++ compiler lines, with specified C++17 and using C++17 lines from the CXX_STD setting. The compiler lines show the include path of the Rcpp headers, which LinkingTo provides.

Source: devtools package documentation: document

(Here <Rcpp> stands for the Rcpp directory in the library; the temporary-library line and the line that names the compiler are omitted, and the flags are shortened.) The script that follows runs after R CMD INSTALL shelf of this copy. It shows that the C++ function agrees with the R function on the data set, that the registration table lists the one routine, and that DESCRIPTION has Rcpp in both Imports and LinkingTo.

Source: R documentation: read.dcf

R CMD check on this copy passed the same compiled-code checks as the C copy (foreign function calls, compilation flags in Makevars, compiled code), and added a line of its own for the C++ standard, which reads:

Source: Writing R Extensions: Using C++ code

Two habits keep an Rcpp package healthy. Commit the generated RcppExports files, because CRAN and users compile the package without Rcpp’s tooling, and run compileAttributes() after every change of an exported signature (devtools::document() runs it as part of building, as the transcript shows); a stale RcppExports.cpp can fail to compile or to load. And do not define a second R_init_shelf() next to the generated one: two functions of the same name cannot link, so a package that uses Rcpp attributes and also has hand-written routines must register them from the generated initialiser (the attributes vignette documents the // [[Rcpp::init]] attribute for running your own initialisation code).

cpp11 (0.5.5 is installed; it was not run) is a header-only alternative in the r-lib family, with similar goals and a different design: C++11-style attributes ([[cpp11::register]]), LinkingTo: cpp11 only, copy-on-write semantics, UTF-8 everywhere, and no shared runtime library; its site describes the differences from Rcpp and how to convert (cpp11 package documentation). RcppArmadillo and RcppEigen add linear-algebra libraries to Rcpp, and RcppParallel adds threading; none of them is installed here, so they are only named. All build on the same R CMD SHLIB and LinkingTo machinery described above.

R has been tightening the API in steps, and the NEWS files of R 4.5.0 and 4.6.0 list them. The facts that matter for a package author, in the order they happened:

The table in the manual maps the non-API names to replacements. A selection:

Source: Writing R Extensions: Some API replacements for non-API entry points

Two experiments on R 4.6.1 show the result. The first file calls ATTRIB() and Rf_findVar(), two of the entry points that the NEWS of 4.5.0 and 4.6.0 single out.

Source: Writing R Extensions: Some API replacements for non-API entry points

Neither is declared by the installed headers any more, so the compiler does not know them. On gcc 13 with the C23 option this is a warning (an implicit declaration, which C99 already disallowed), and the call is compiled as a call to a function returning int, which is wrong for a pointer. Other compilers can reject the file outright.

Source: R NEWS: Changes in R 4.6.0

The second experiment is a package. Package authors whose code stopped compiling because the declarations went away sometimes add the prototype themselves, which makes the file compile and hides nothing from R CMD check. probe is a deliberately wrong package of one R function and one C file, which declares Rf_findVar() by hand, does not register its routine, and sets PKG_CFLAGS = -Wall -O3.

Source: Writing R Extensions: Moving into C API compliance

Source: Writing R Extensions: Using Makevars

The relevant part of R CMD check --as-cran --no-manual --no-tests on this package, with the other checks (all passing) left out, is below. It contains the text of the three findings. The compiled code check names the non-API call and the missing registration, says the entry point may be removed soon, and points to the two sections of the manual that matter.

Source: Writing R Extensions: Moving into C API compliance

(The platform header lines of the check log are not shown, and Rf_findVar was chosen because the NEWS names it among the non-API functions that R_getVar replaces; the replacement call is R_getVar(sym, rho, TRUE).) A WARNING from R CMD check does not stop a package from installing, but a package submitted to CRAN is expected to pass without WARNINGs (Publishing to CRAN covers the policy), and since R 4.6.0 the list of non-API entry points is long. The practical advice is to run R CMD check with the newest R, including R-devel, and to treat every line of "checking compiled code" as something to fix with the replacement table above. For an entry point that has no replacement, the manual’s section is the place to look first, since it is updated as the API is clarified.

Two toolchain facts interact with all this. First, the default C standard is C23 on R 4.5.0 and later where the compiler supports it, which rejects implicit function declarations and K&R-style definitions, so older C code needs fixing or USE_C17; and the default C++ standard is C++20 from R 4.6.0, which has removed some library features that C++17 still has (the manual gives std::uncaught_exception as an example and warns that some compilers accept removed features in C++17 mode). Second, Rtools is versioned with R: Rtools45 serves R 4.5.0 and every later R including R-devel, so the Windows toolchain of this page is the same GCC 14.2 for R 4.5 and 4.6; the version history is in the next section. R CMD config prints the compiler settings that R will use, and a CI job that checks packages on Windows, macOS and Linux with the current release and R-devel finds toolchain differences before CRAN’s checks do. How packages are checked and submitted is the subject of Publishing to CRAN.