Non-API R Functions Tracking

This document tracks usage of non-API R functions in miniextendr. Non-API functions are detected by R CMD check via tools:::.check_so_symbols.

Reference: https://svn.r-project.org/R/trunk/src/library/tools/R/sotools.R

🔗Currently Used Non-API Functions

🔗Feature-Gated Non-API Functions

Locations intentionally omit line numbers (they drift); use search on the symbol name.

Note: miniextendr-engine is entirely non-API (uses Rembedded.h/Rinterface.h for embedding R) and is not tracked here.

🔗Test Utilities (Not Part of R Package)

The file miniextendr-api/tests/r_test_utils.rs contains a disable_r_stack_checking() function that directly accesses R_CStackLimit. This code is never part of the R package because:

1. It’s in the tests/ directory of miniextendr-api, which is only compiled for cargo test
2. It uses miniextendr-engine to embed R for Rust unit tests
3. The example R package (rpkg/) only vendors miniextendr-api/src/ and miniextendr-macros/src/
4. Test directories are excluded from vendoring

This test utility exists because cargo test embeds R in a non-standard way (not via R CMD). It is test-harness infrastructure, not permission for an R package to call R APIs from secondary threads. The package-facing helpers and fixtures that currently suggest otherwise are tracked for removal in #1352.

🔗API Functions (Safe to Use)

These functions are NOT in the non-API list and are safe:

TRUELENGTH is not declared at all: R 4.5’s R CMD check reports it as non-API, and R 4.6’s libR no longer exports it, so a package referencing it cannot load there.

🔗Choosing between ANY_ATTRIB and attributes()

Writing R Extensions recommends ANY_ATTRIB (added in R 4.5.0) in place of ATTRIB for testing whether an object has attributes. miniextendr supports R 4.4, whose libR does not export ANY_ATTRIB, and R loads a package’s shared object with every symbol resolved up front. A safe wrapper that called ANY_ATTRIB would make every package built with it fail to load on R 4.4, whether or not the wrapper ever ran. So SexpExt::has_attributes() evaluates attributes(quote(x)) on every R version. That allocates a call and, when attributes exist, the list attributes() returns.

The two answers differ in two cases. attributes() reports the tag names of a pairlist as a names attribute, while ANY_ATTRIB ignores them; has_attributes() follows attributes(), so pairlist(a = 1) has attributes. A CHARSXP keeps R’s string-cache chain in its attribute slot, so ANY_ATTRIB can be non-zero for one; has_attributes() returns false, as identical() skips that slot too.

To reproduce identical(x, FALSE), call x.is_identical(SEXP::scalar_logical(false)) rather than combining a value check with an attribute check.

🔗Full Non-API List (R 4.5.x trunk)

🔗Feature Gate Strategy

When using non-API functions, wrap them in a nonapi feature:

#[cfg(feature = "nonapi")]
pub fn DATAPTR(x: SEXP) -> *mut c_void;

This allows users to opt-in to non-API usage while keeping the default build CRAN-compatible.

🔗R-version cfgs

A package is compiled against the R it installs into, so the build knows the R version. miniextendr-api’s build.rs reads R_MAJOR / R_MINOR from $R_HOME/include/Rversion.h and sets one cfg per listed version at or below it, cumulatively: r_4_5 on R 4.5 and later, r_4_6 on R 4.6 and later (#1905). A build that finds no header (a wasm32 target, CI’s lint job with an empty R_HOME) sets them all.

Use them for an entry point that a newer R adds, or that a newer R makes API:

• R adds it. Gate the binding in sys.rs on the cfg (ANY_ATTRIB and R_getVarEx are #[cfg(r_4_5)]), and keep a fallback beside every use for the older R. Referencing an entry point the R lacks fails at load, because packages load with dyn.load(now = TRUE).
• R makes it API. The entry point exists before that version, but R CMD check notes it as non-API there. Gate the call on the cfg when the older R offers another route to the same result, and keep the entry point on the newer side: connection/access.rs reads a connection through R_GetConnection under r_4_6 and through summary.connection() / readBin() / writeBin() before.

Gate a public item on a cfg only in the first case. There a missing entry point would fail at load, and the gate turns that into a compile error. In the second, the entry point works on the older R, so keep the public signature the same on every R and switch the implementation inside it: packages compile on each user’s machine against that user’s R, so an item that exists only on newer R breaks the install for a user on an older R while its author, on a newer one, never sees it. Gate a public item there only when the older R has no route to what it returns at all (get_connection, the raw handle, is R >= 4.6 only).

To add a version, append it to R_VERSION_CFGS in miniextendr-api/build.rs. Test both sides: CI runs R CMD check on R 4.4 and release on every PR, and on oldrel too on main or when the PR carries the oldrel label (add it to a PR that touches these cfgs). The lint job compiles the newest side.