Dear R experts---
after many years, I am planning to give in and write my first R
package. I want to combine my collection of collected useful utility
routines.
as my guide, I am planning to use Friedrich Leisch's "Creating R
Packages: A Tutorial" from Sep 2009. Is there a newer or better
tutorial? this one is 4 years old.
I also plan on one change---given that the package.skeleton() function
writes all the individual man[ual] functions, I am thinking it would
be a good idea to put the doc and the R code together in the same
file, one for each function. Interestingly enough, the code is by
default in the \examples{} section, so I am thinking of writing a perl
program that takes every .Rd file and writes the function into the R/
directory, overwriting anything else that is already there. this way,
I maintain only one file for each function, and the docs and code are
together. sort of like knuth's literate programming and the
numerical-recipees approach to keeping each function in its own file
with equal name.
I believe my "try-out and debug cycle" will then be
$ cd iaw ## the package name and top directory is iaw
$ perl weaveall.pl ## extract all man/*.Rd files code examples
and place them in R/
$ R CMD INSTALL iaw
$ R CMD check iaw
good idea? bad idea? common? uncommon?
I do not understand the namespace mechanism yet. I understand the
NAMESPACE file, and I think this lists the routines that become
visible when a later program of mine contains 'library(iaw)'. I think
I want to explicitly declare what packages are actually imported.
?importIntoEnv tells me that it is not intended to be used. how can
another program declare exactly what functions it wants to import?
(frankly, I would love to turn all default autovivification off in my
program, but that's not possible.)
/iaw
----
Ivo Welch (ivo.welch at gmail.com)
My short answer is to watch this video by Jeffrey Horner http://youtu.be/ScV7XXlBZww and learn roxygen2. And the long answer is to read the manual which has everything you need: http://cran.r-project.org/doc/manuals/r-release/R-exts.html Regards, Yihui -- Yihui Xie <xieyihui at gmail.com> Phone: 515-294-2465 Web: http://yihui.name Department of Statistics, Iowa State University 2215 Snedecor Hall, Ames, IA On Tue, Feb 5, 2013 at 6:43 PM, ivo welch <ivo.welch at anderson.ucla.edu> wrote:> Dear R experts--- > > after many years, I am planning to give in and write my first R > package. I want to combine my collection of collected useful utility > routines. > > as my guide, I am planning to use Friedrich Leisch's "Creating R > Packages: A Tutorial" from Sep 2009. Is there a newer or better > tutorial? this one is 4 years old. > > I also plan on one change---given that the package.skeleton() function > writes all the individual man[ual] functions, I am thinking it would > be a good idea to put the doc and the R code together in the same > file, one for each function. Interestingly enough, the code is by > default in the \examples{} section, so I am thinking of writing a perl > program that takes every .Rd file and writes the function into the R/ > directory, overwriting anything else that is already there. this way, > I maintain only one file for each function, and the docs and code are > together. sort of like knuth's literate programming and the > numerical-recipees approach to keeping each function in its own file > with equal name. > > I believe my "try-out and debug cycle" will then be > > $ cd iaw ## the package name and top directory is iaw > $ perl weaveall.pl ## extract all man/*.Rd files code examples > and place them in R/ > $ R CMD INSTALL iaw > $ R CMD check iaw > > good idea? bad idea? common? uncommon? > > I do not understand the namespace mechanism yet. I understand the > NAMESPACE file, and I think this lists the routines that become > visible when a later program of mine contains 'library(iaw)'. I think > I want to explicitly declare what packages are actually imported. > ?importIntoEnv tells me that it is not intended to be used. how can > another program declare exactly what functions it wants to import? > (frankly, I would love to turn all default autovivification off in my > program, but that's not possible.) > > /iaw > ---- > Ivo Welch (ivo.welch at gmail.com) > > ______________________________________________ > R-help at r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-help > PLEASE do read the posting guide http://www.R-project.org/posting-guide.html > and provide commented, minimal, self-contained, reproducible code.
thanks for the responses. this is what I have learned so far: primarily, I need to learn roxygen2 and devtools, because they do what I was planning to reinvent. roxygen2 allows R users to write R code that embeds its documentation. the .R user source file has a family semblance with POD (perl's plain old documentation), although pod looks cleaner because it does not need the '#' comments. all roxygen2 documentation commands are interspersed as comments, and presumably devtools creates the .Rd files from such .R files in devtool's package build stage. it is not clear to me whether every function must or should get its own .R file now (just like each R function has its own .Rd file). in "Getting Started with RStudio", there is a brief 1-pager on roxygen2, which gave me a flavor of what it is. there is also a stackoverflow with links at http://stackoverflow.com/questions/4523513/good-reference-for-roxygen , but this is for oxygen not oxygen2, I think. then there is the standard roxygen2 standard documentation, but this is just the function man set and not a "how to get started" description. I don't think roxygen2 has a vignette, either. right now, I am wondering whether there is a skeleton creator for an existing function for roxygen2, which generates all the required .Rd fields as appropriate '#@' directives in the comments, just like the vanilla package skeleton creator in R creates them in the .Rd files. devtools is a package that can take roxygen2 .R files, compile the embedded comments into .Rd files into the man/ directory, and then rebuilds and reloads the package on the fly. (possibly also repackages them.) roughly speaking, I think it translates the more convenient new doc format into the old standard basic way to package packages, and also obviates the need to restart R. again, this is what I gleamed from the rstudio guide. so, the combination of devtools and oxygen2 seem to be exactly what I wanted, but I did not find the starter docs. what I would love to see is someone pointing me to a 1-page example of how a new user should take two real simple functions, say # my old sum remark sum1 <- function(x,y) (x+y) # my old difference remark difference1 <- function(x,y) (x-y) stopifnot( sum1(5,5) == 10 ) ## should become a testthat and make a (silly) package out of it. this intro should describe how the user should start by creating the package skeleton (say, package sumdiff), how one gets the roxygen2 skeletons for the two functions, how one builds and loads it (for testing), then how one would change it, e.g., by changing both functions to square the inputs, rebuild and reload. someone has probably already written this up, but it is difficult to find. I read some other package introductions, too, but they end up overbuilding the example and/or are better references than "get started guides." for example, the Leisch packaging introduction spends more than half of its space and the user's attention span (and in my case, brain cells) on peripheral aspects. yes, S3 and S4 functions, extending lm() etc., is all nice and useful, but teaching the basic logic of the R packaging system may be better done with functions that do almost nothing. contemplating the core logic of lm() extensions is distracting at the first baby steps. similarly, rstudio is a really nice IDE, but I don't think that roxygen2 and devtools need rstudio. could someone point me to a simpler "starting" document for roxygen2 and devtools, if such exists? regards, /iaw ---- Ivo Welch (ivo.welch at gmail.com) http://www.ivo-welch.info/ J. Fred Weston Professor of Finance Anderson School at UCLA, C519 Director, UCLA Anderson Fink Center for Finance and Investments Free Finance Textbook, http://book.ivo-welch.info/ Editor, Critical Finance Review, http://www.critical-finance-review.org/ On Tue, Feb 5, 2013 at 4:43 PM, ivo welch <ivo.welch at anderson.ucla.edu> wrote:> Dear R experts--- > > after many years, I am planning to give in and write my first R > package. I want to combine my collection of collected useful utility > routines. > > as my guide, I am planning to use Friedrich Leisch's "Creating R > Packages: A Tutorial" from Sep 2009. Is there a newer or better > tutorial? this one is 4 years old. > > I also plan on one change---given that the package.skeleton() function > writes all the individual man[ual] functions, I am thinking it would > be a good idea to put the doc and the R code together in the same > file, one for each function. Interestingly enough, the code is by > default in the \examples{} section, so I am thinking of writing a perl > program that takes every .Rd file and writes the function into the R/ > directory, overwriting anything else that is already there. this way, > I maintain only one file for each function, and the docs and code are > together. sort of like knuth's literate programming and the > numerical-recipees approach to keeping each function in its own file > with equal name. > > I believe my "try-out and debug cycle" will then be > > $ cd iaw ## the package name and top directory is iaw > $ perl weaveall.pl ## extract all man/*.Rd files code examples > and place them in R/ > $ R CMD INSTALL iaw > $ R CMD check iaw > > good idea? bad idea? common? uncommon? > > I do not understand the namespace mechanism yet. I understand the > NAMESPACE file, and I think this lists the routines that become > visible when a later program of mine contains 'library(iaw)'. I think > I want to explicitly declare what packages are actually imported. > ?importIntoEnv tells me that it is not intended to be used. how can > another program declare exactly what functions it wants to import? > (frankly, I would love to turn all default autovivification off in my > program, but that's not possible.) > > /iaw > ---- > Ivo Welch (ivo.welch at gmail.com)
actually, I may have found what I was looking for in https://github.com/hadley/devtools/wiki/Philosophy --- Ivo Welch (ivo.welch at gmail.com)
I have a "minimal" package here based on roxygen2: https://github.com/yihui/rmini Regards, Yihui -- Yihui Xie <xieyihui at gmail.com> Phone: 515-294-2465 Web: http://yihui.name Department of Statistics, Iowa State University 2215 Snedecor Hall, Ames, IA On Tue, Feb 5, 2013 at 11:49 PM, ivo welch <ivo.welch at anderson.ucla.edu> wrote:> actually, I may have found what I was looking for in > > https://github.com/hadley/devtools/wiki/Philosophy > > --- > Ivo Welch (ivo.welch at gmail.com) > > ______________________________________________ > R-help at r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-help > PLEASE do read the posting guide http://www.R-project.org/posting-guide.html > and provide commented, minimal, self-contained, reproducible code.
On 13-02-05 7:43 PM, ivo welch wrote:> Dear R experts--- > > after many years, I am planning to give in and write my first R > package. I want to combine my collection of collected useful utility > routines. > > as my guide, I am planning to use Friedrich Leisch's "Creating R > Packages: A Tutorial" from Sep 2009. Is there a newer or better > tutorial? this one is 4 years old. > > I also plan on one change---given that the package.skeleton() function > writes all the individual man[ual] functions, I am thinking it would > be a good idea to put the doc and the R code together in the same > file, one for each function. Interestingly enough, the code is by > default in the \examples{} section, so I am thinking of writing a perl > program that takes every .Rd file and writes the function into the R/ > directory, overwriting anything else that is already there. this way, > I maintain only one file for each function, and the docs and code are > together. sort of like knuth's literate programming and the > numerical-recipees approach to keeping each function in its own file > with equal name.I have heard of people using noweb to do this, but I can't point to any examples. I'd actually recommend against it. Good documentation files don't make good source files. If you really want close connections between your source and the user documentation, I think that's the job of your IDE. (I don't find this to be a problem, so I don't use an IDE that attempts this, but I believe they exist: I'd look at ESS, RStudio, RKWard if I was in the market for that.) Other people have recommended Roxygen, but honestly I haven't seen a package documented with Roxygen where the documentation was adequate. It looks as though it's great to get initial documentation created, but does not appear to encourage followup.> > I believe my "try-out and debug cycle" will then be > > $ cd iaw ## the package name and top directory is iaw > $ perl weaveall.pl ## extract all man/*.Rd files code examples > and place them in R/ > $ R CMD INSTALL iaw > $ R CMD check iawI wouldn't put the last step in this cycle. Have a separate check cycle, which includes a build step, and checks the built tarball.> > good idea? bad idea? common? uncommon? > > I do not understand the namespace mechanism yet. I understand the > NAMESPACE file, and I think this lists the routines that become > visible when a later program of mine contains 'library(iaw)'. I think > I want to explicitly declare what packages are actually imported. > ?importIntoEnv tells me that it is not intended to be used. how can > another program declare exactly what functions it wants to import? > (frankly, I would love to turn all default autovivification off in my > program, but that's not possible.)I am not sure I know what you mean by "program", but the NAMESPACE file allows you to declare which functions you want to import from other packages. I think it is not as strict as you want: if you don't declare it, you might still find it, but if you do declare it, you'll find that version before any user-created or other-package-created one. It might be a good idea for R to allow a package to request the strict declaration model, where you need to declare *every* import. I don't know how difficult a change that would be. Duncan Murdoch> > /iaw > ---- > Ivo Welch (ivo.welch at gmail.com) > > ______________________________________________ > R-help at r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-help > PLEASE do read the posting guide http://www.R-project.org/posting-guide.html > and provide commented, minimal, self-contained, reproducible code. >