[R-pkg-devel] Using RC_fopen in a CRAN package

I?d like to ask for clarification about CRAN policies regarding usage
of functions that start with "RC_*", such as "RC_fopen".

I'm trying to upload a package which is meant for reading and writing
data from text files in a certain format, for which I want to use a C
file pointer which I obtain through "RC_fopen". The R extensions manual
says the following:
"... there are other header files there that can be included too, but
many of the features they contain should be regarded as undocumented
and unstable."

Since "RC_fopen" is present in a header file, I would guess it should
be classified as "public" within the entry points classification
(between API/public/private/hidden). This is the description for such
entry points in the manual:
"Entry points declared in an installed header file that are exported on
all R platforms but are not documented and subject to change without
notice."

As I understand it, there is nothing that would forbid using public
entry points compared to the explicit point made about "private" entry
points. However, when I try to submit the package to CRAN, it doesn't
make it past the automated checks due to a NOTE:
Check: compiled code, Result: NOTE
   File 'readsparse/libs/readsparse.so':
     Found non-API call to R: 'RC_fopen'
   
   Compiled code should not call non-API entry points in R.
   
   See 'Writing portable packages' in the 'Writing R Extensions' manual.


Is it allowed to use such functions in packages? I see a few packages
currently in CRAN have the same note in the checks, such as "iotools",
and am wondering if I should just email the CRAN maintainer explaining
that I intend to use the function anyway, since it's just a note rather
than a warning or error.

The CRAN policy document is quite clear on this: "CRAN packages should 
use only the public API. Hence they should not use entry points not 
declared as API in installed headers nor .Internal() nor .Call() etc 
calls to base packages. Also, ::: should not be used to access 
undocumented/internal objects in base packages (nor should other means 
of access be employed). Such usages can cause packages to break at any 
time, even in patched versions of R. "

So you are free to use that function, but CRAN won't publish your 
package if you do.

Duncan Murdoch

Duncan Murdoch

| > Is it allowed to use such functions in packages? I see a few packages
| > currently in CRAN have the same note in the checks, such as "iotools",
| > and am wondering if I should just email the CRAN maintainer explaining
| > that I intend to use the function anyway, since it's just a note rather
| > than a warning or error.
| 
| The CRAN policy document is quite clear on this: "CRAN packages should 
| use only the public API. Hence they should not use entry points not 
| declared as API in installed headers nor .Internal() nor .Call() etc 
| calls to base packages. Also, ::: should not be used to access 
| undocumented/internal objects in base packages (nor should other means 
| of access be employed). Such usages can cause packages to break at any 
| time, even in patched versions of R. "
| 
| So you are free to use that function, but CRAN won't publish your 
| package if you do.

What you can do is to republish the functions in a package you own and
maintain, and then export them from there. I have done that in RApiDatetime
for some date/time parsing code, and in RApiSerialize for serialization.

It is not ideal as your copies may become stale over time. But it gives you a
way forward as long as R Core exercises their right to have non-public APIs.
As R Core has demonstrated exemplary fidelity to the parts of the API that
are public, we should not be too grumpy that they reserve this option.

Dirk

https://dirk.eddelbuettel.com | @eddelbuettel | edd at debian.org