Thanks for your convincing comment, but it seems the R core team has a different opinion... A few hours ago, src/include/R_ext/Altrep.h got this comment:
/* Not part of the API, subject to change at any time. */ commit: https://github.com/r-devel/r-svn/commit/2059bffde642f8426d1f39ab5dd995d19a575d4d While I'm glad to see their attempt to make it clear, I'm confused. That commit marks many other files as "not API," but I think it's a bit inconsistent with what Writing R Extension says. For example, src/include/R_ext/Parse.h got a comment "So not API," but the entry point R_ParseVector is explained in Writing R Extension[1]. So, I believe it's clearly an "API" both in the sense of WRE's dialect and in an ordinary sense. Which should I believe? WRE? The source code? It might be just a coincidence, but I'm sorry if my question drove the R core team to such a too-quick clarification. I just wanted to discuss how to fix the current inconsistencies. I think the R core needs a proper definition of "API" first. In my opinion, it makes little sense to call it "non-API" just to show the possibility of future breaking changes. Whether you call it API or non-API, clever users will still accept the breaking changes on it if it's reasonable. For example, how about "experimental API" or "unstable API"? They sound better to me. Best, Yutani [1]: https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Parsing-R-code-from-C 2024年4月22日(月) 16:37 Gabriel Becker <gabembec...@gmail.com>: > Hi Yutani, > > ALTREP is part of the official R api, as illustrated by the presence of > src/include/R_ext/Altrep.h. Everything declared in the header files in that > directory is official API AFAIK (and I believe that is more definitive than > the manuals). > > The documentation of ALTREP has lagged behind its implementation > unfortunately, which may partially my fault for not submitting doc > patches for it against the manuals. Sorry for my contribution to that, I'll > see if I can loop back around to contributing documentation for ALTREP. > > Best, > ~G > > On Sun, Apr 21, 2024 at 6:36 PM Hiroaki Yutani <yutani....@gmail.com> > wrote: > >> Thanks, Hernando, >> >> Sorry, "API" is a bit confusing term in this context, but what I want to >> discuss is the "API" that Writing R Extension defines as quoted in my >> previous email. It's probably different from an ordinary sense when we >> casually say "R C API". >> >> You might wonder why I care about such a difference. This is because >> calling a "non-API" is considered a violation of CRAN repository policy, >> which means CRAN will kick out the R package. I know many CRAN packages >> use >> ALTREP, but just being accepted by CRAN at the moment doesn't mean CRAN >> will keep accepting it. So, I want to clarify the current status of >> ALTREP. >> >> Best, >> Yutani >> >> 2024年4月22日(月) 10:17 <hcortin...@gmail.com>: >> >> > Hello, I don't believe it is illegal, as ALTREP "implements an >> abstraction >> > underneath the C API". And is "compatible with all code which uses the >> > API". >> > >> > Please see slide deck by Gabriel Becker, with L Tierney, M Lawrence >> and T >> > Kalibera. >> > >> > >> > >> https://bioconductor.org/help/course-materials/2020/BiocDevelForum/16-ALTREP >> > .pdf >> > < >> https://bioconductor.org/help/course-materials/2020/BiocDevelForum/16-ALTREP.pdf >> > >> > >> > ALTREP framework implements an abstraction underneath traditional R C >> API >> > - Generalizes whats underneath the API >> > - Without changing how data are accessed >> > - Compatible with all C code which uses the API >> > - Compatible with R internals >> > >> > >> > I hope this helps, >> > Hernando >> > >> > >> > -----Original Message----- >> > From: R-devel <r-devel-boun...@r-project.org> On Behalf Of Hiroaki >> Yutani >> > Sent: Sunday, April 21, 2024 8:48 PM >> > To: r-devel <r-devel@r-project.org> >> > Subject: [Rd] Is ALTREP "non-API"? >> > >> > Writing R Extension[1] defines "API" as: >> > >> > Entry points which are documented in this manual and declared in an >> > installed header file. These can be used in distributed packages and >> will >> > only be changed after deprecation. >> > >> > But, the document (WRE) doesn't have even a single mention of ALTREP, >> the >> > term "ALTREP" itself or any entry points related to ALTREP. Does this >> mean, >> > despite the widespread use of it on R packages including CRAN ones, >> ALTREP >> > is not the API and accordingly using it in distributed packages is >> > considered illegal? >> > >> > Best, >> > Yutani >> > >> > [1]: >> > https://cran.r-project.org/doc/manuals/r-release/R-exts.html#The-R-API >> > >> > [[alternative HTML version deleted]] >> > >> > ______________________________________________ >> > R-devel@r-project.org mailing list >> > https://stat.ethz.ch/mailman/listinfo/r-devel >> > >> > >> >> [[alternative HTML version deleted]] >> >> ______________________________________________ >> R-devel@r-project.org mailing list >> https://stat.ethz.ch/mailman/listinfo/r-devel >> > [[alternative HTML version deleted]] ______________________________________________ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel