I'm writing an R package making use of Rcpp to call functions written in C++ into the R code. Some of these functions and templates are written in files with a .hpp extension following the convention used by boost (and also discussed here).
This does not result in an error when building (R CMD build .) and checking (R CMD check --as-cran package.tar.gz) the package, but it returns the next warning:
Subdirectory ‘src’ contains:
file.hpp example.hpp
These are unlikely file names for src files
Ok, this is not a big issue, but my concern is, why the warning? is naming *hpp files considered a bad practice in the R community? Are there objective or community reasons why I should use *cpp/*h files instead of *hpp for the templates?
I originally left this information as a comment, but realized it actually answers your question I think, so here goes:
As Dirk Eddelbuettel points out in the comments, when you have a question about an R Core Team policy on R extension packages, your best bet is to look through their excellent Writing R Extensions manual. This manual tells you almost anything you could ever need to know.
In your case specifically, you needed to look at Section 1.1.5, which explains that "[the R Core Team] recommend[s] using .h for headers" because (as they explain in footnote 18) "Using .hpp is not guaranteed to be portable."
Related
I have already made a simple R package (pure R) to solve a problem with brute force then I tried to faster the code by writing the Rcpp script. I wrote a script to compare the running time with the "bench" library. now, how can I add this script to my package? I tried to add
#'#importFrom Rcpp cppFunction
on top of my R script and inserting the Rcpp file in the scr folder but didn't work. Is there a way to add it to my r package without creating the package from scratch? sorry if it has already been asked but I am new to all this and completely lost.
That conversion is actually (still) surprisingly difficult (in the sense of requiring more than just one file). It is easy to overlook details. Let me walk you through why.
Let us assume for a second that you started a working package using the R package package.skeleton(). That is the simplest and most general case. The package will work (yet have warning, see my pkgKitten package for a wrapper than cleans up, and a dozen other package helping functions and packages on CRAN). Note in particular that I have said nothing about roxygen2 which at this point is a just an added complication so let's focus on just .Rd files.
You can now contrast your simplest package with one built by and for Rcpp, namely by using Rcpp.package.skeleton(). You will see at least these differences in
DESCRIPTION for LinkingTo: and Imports
NAMESPACE for importFrom as well as the useDynLib line
a new src directory and a possible need for src/Makevars
All of which make it easier to (basically) start a new package via Rcpp.package.skeleton() and copy your existing package code into that package. We simply do not have a conversion helper. I still do the "manual conversion" you tried every now and then, and even I need a try or two and I have seen all the error messages a few times over...
So even if you don't want to "copy everything over" I think the simplest way is to
create two packages with and without Rcpp
do a recursive diff
ensure the difference is applied in your original package.
PS And remember that when you use roxygen2 and have documentation in the src/ directory to always first run Rcpp::compileAttributes() before running roxygen2::roxygenize(). RStudio and other helpers do that for you but it is still easy to forget...
I am currently developing an R package and want it to be as clean as possible, so I try to resolve all WARNINGs and NOTEs displayed by devtools::check().
One of these notes is related to some code I use for generating sample data to go with the package:
checking top-level files ... NOTE
Non-standard file/directory found at top level:
'generate_sample_data.R'
It's an R script currently placed in the package root directory and not meant to be distributed with the package (because it doesn't really seem useful to include)
So here's my question:
Where should I put such a file or how do I tell R to leave it be?
Is .Rbuildignore the right way to go?
Currently devtools::build() puts the R script in the final package, so I shouldn't just ignore the NOTE.
As suggested in http://r-pkgs.had.co.nz/data.html, it makes sense to use ./data-raw/ for scripts/functions that are necessary for creating/updating data but not something you need in the package itself. After adding ./data-raw/ to ./.Rbuildignore, the package generation should ignore anything within that directory. (And, as you commented, there is a helper-function devtools::use_data_raw().)
Roxygen is inspired by the Doxygen documentation system that is used by C, C++ programmers. I have used Doxygen and I find it really easy to document any program as long as you have the doxygen comment. It also generate call graphs for functions and classes. I thought roxygen would work the same way but when I search for roxygen help, I only find solution to documenting R packages.
I have checked Hadley Wickham's online roxygen2 help but that does not describe anything about the R script documentation.
My scripts sometimes become 500-1000 lines and have several functions which I always document with the comments. I want to generate PDF or HTML documentation with graph-viz diagrams. Is Roxygen capable of making call-graph and document standalone R scripts?
No, roxygen2 will work only for writing package documentation. Sounds to me you're after a report generating tool. You can use knitr for that. You can include code, comments, text, MathJax, or even use LaTeX. It also supports table of contents and references. This is by no means an exhaustive list of functionality. With some logical limitations, you can produce pdf and html documents, among others.
Though this is an old thread, for future reference, the following library is able to achieve that:
https://rdrr.io/cran/document/
From its docs: Have you ever been tempted to create 'roxygen2'-style documentation comments for one of your functions that was not part of one of your packages (yet)? This is exactly what this package is about: running 'roxygen2' on (chunks of) a single code file.
I'm planning to condense some of my code into a package, and was looking at the source of a few published packages on CRAN as a guide. I notice many packages include the file R\zzz.R, so I presume there must be some convention surrounding this.
However, I cannot find any mention of zzz.R in the official Writing R Extensions guide. What is this file for, and do I need to include one in my package? Why is it named the way it is - why not zzzz.R?
It's a file where one usually puts actions on load of the package. It is tradition/convention that it's called zzz.R and could be called anything.R
You only need to include this if you want you package to do something out of the ordinary when it loads. Keep looking at what people put in there and you'll begin to get a sense of what they're used for.
This zzz.R file was also mentioned by Hadley Wickham in his book "R packages", at the bottom of "When you do need side-effects" section.
https://r-pkgs.org/Code.html#when-you-do-need-side-effects
If you use .onLoad(), consider using .onUnload() to clean up any side effects. By convention, .onLoad() and friends are usually saved in a file called R/zzz.R. (Note that .First.lib() and .Last.lib() are old versions of .onLoad() and .onUnload() and should no longer be used.)
I'm writing a R package which begins to grow in size, and so would really appreciate to use a custom structure in folders pkg/R/ and (especially) in pkg/src/.
For example, let's say I have two families of algorithms of some type A, and some functions of type B, and a main entry point. Ideally R/ or src/ folders would be organized as follow:
typeA/
algorithms1/
algo11.ext
...
algorithms2/
algo21.ext
...
typeB/
function1.ext
...
main.ext
with "ext" in {R,cpp,c,f,...}, and potentially two files having the same name.
Is it possible ? If yes, how can I do that ?
Thanks in advance !
[2012-12-31] EDIT: an idea would be to write a few scripts - maybe inside another R package - to (un)flatten a structured package for tests or diffusion. But there is probably a better solution, so I will wait a bit.
As the 'Writing R extensions' manual indicates here, a Makevars file under pkg/src allows to have nested subfolders for C/C++/Fortran code. (See e.g. RSiena package).
However, I didn't find anything concerning a custom structure in pkg/R. So I wrote a little package (usable, although needing improvements) which accomplish the following tasks:
Load/Unload a package having (potentially) nested folders under pkg/R
Launch R and/or C unit tests on it [basic framework, to be replaced (e.g. RUnit and check)]
Export the package to be CRAN-compatible (flatten R code, generate Makevars file)
I will link it here if it reaches a publishable state. (For the moment I could send it by email).
The official package documentation https://cran.r-project.org/doc/manuals/r-devel/R-exts.html, section 1.1.5 contains this quote:
The R and man subdirectories may contain OS-specific subdirectories named unix or windows.
I've tried creating a simple test package with subdirectories in R-3.5.1 and it did not work properly.
Nor devtools::load_all() nor R CMD build successfully exported code from subdirectories in R.