[R] First R Package --- Advice?
Martin Morgan
mtmorgan at fhcrc.org
Wed Feb 6 15:44:03 CET 2013
On 02/06/2013 03:31 AM, Duncan Murdoch wrote:
> 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.
the compiler package in base R is, apparently, developed using noweb
https://svn.r-project.org/R/trunk/src/library/compiler/noweb, which provide
excellent documentation of the code for other developers and is not quite what
Ivo was suggesting.
>
> 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 iaw
>
> I 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.
This sounds like codetools' findGlobals, which has problems with idioms like
subset() and with() at least. One would want a general solution for this, rather
than the current utils::globalVariables.
Martin
>
> 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.
>>
>
> ______________________________________________
> 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.
--
Computational Biology / Fred Hutchinson Cancer Research Center
1100 Fairview Ave. N.
PO Box 19024 Seattle, WA 98109
Location: Arnold Building M1 B861
Phone: (206) 667-2793
More information about the R-help
mailing list