hacking
roxyPackage: a workflow utility to maintain R packages
roxyPackage is an R1 package which helps package authors to build and share their R packages. it uses the fantastic roxygen22 package for the creation of documentation, but tries to keep any further dependencies to a minimum.
as of version 0.03-11, roxyPackage is no longer hosted on CRAN (see below). the most recent release of roxyPackage can be installed from my own package repository https://reaktanz.de/R
, e.g. directly from an R session:
#development:
install.packages("roxyPackage", repo=c(getOption("repos"), reaktanz="https://reaktanz.de/R"))
- download: roxyPackage_0.10-1.tar.gz (03.03.2023, 283,1 kb)
- source code: https://github.com/unDocUMeantIt/roxyPackage
- debian/ubuntu package (depends on recent R packages from CRAN)
- NEWS/ChangeLog
- license: GPL >= 33
- documentation: roxyPackage.pdf
- vignette: Managing R Packages with roxyPackage
features
the package provides basically one function, roxy.package()
, which can automate the following actions, individually or in combination:
- generate *-package.R, DESCRIPTION files
- generate CITATION files
- roxygenize() the package to generate docs
- generate PDF documentation (incl. vignettes)
- initialize and update/manage ChangeLog files
- generate NEWS.Rd from ChangeLog files
- generate README.md including Flattr button
- manage .Rbuildignore and .Rinstignore files
- check source packages
- build source packages
- create binary packages for windows and mac OS X (pure R code only, though)
- create debian source and binary packages (including debianizing the R sources and maintainance of a repository)
- build against multiple installations of R in one go
- create a local repository for source and binary packages
- keep PACKAGES files of the repository up to date (handles multiple packages in one repository)
- create and update archives of older packages (via
archive.packages()
) - generate HTML index and info pages for all maintained packages (pages were automatically generated by roxyPackage)
- generate NEWS.html and RSS feeds from NEWS.Rd files and include them in the package HTML index
- run all tasks in sandbox mode
- translate *.Rnw (SWeave) vignettes into *.Rmd (RMwardown; via
rnw2rmd()
) - generate roxygen2 documentation templates for your code (via
templateFile()
)
in other words: except for your actual coding of the package, roxy.package()
should take over the complete workflow from packaging to updating your personal repository. i've been using earlier versions of this function since about 2009, and have now packed it for this release, in case others find such a thing useful, too.
note that the package doesn't upload anything anywhere (yet?). so if you want your packages to be publicly available, you still have to, e.g., rsync the local repository root directory with a web server or your webspace at a hosting provider.
citation information
in case you need to cite roxyPackage for reference, consider the CITATION file, or one of the following:
Michalke, M. (2015, March). Make packages, not scripts! How roxyPackage makes sharing your code a no-brainer. Paper presented at the Tagung experimentell arbeitender Psychologen (TeaP), Hildesheim.
Michalke, M. (2013, February). roxyPackage -- und R-Pakete bauen sich von selbst. Paper presented at the Köln R User Group (KölnRUG), Köln.
why roxyPackage is no longer on CRAN
one particular feature of this package (the generation of NEWS.Rd files) relies on an unexported function of the tools package, tools:::news2Rd()
. calling an internal function is considered unsuitable for packages on CRAN, even though tools:::news2Rd()
is the standard method for producing NEWS.Rd files, as recommended to packagers in the very manual page for news()
. so there were three ways to deal with the issue:
- ignore the recommendation in
?news()
and re-implementnews2Rd()
myself - keep compliance with CRAN standards and remove all features relying on
tools:::news2Rd()
(including generation of RSS feeds and NEWS.html) - leave all working code untouched and redraw the package from CRAN
i hope you agree with me that i did the right call. even though the package itself is therefore no longer accepted on CRAN, i will always try to see to it it builds CRANable packages from your code.
feedback
although roxyPackage does a flawless job for me personally (the package built this very repository it's hosted on itself ;-)), you might of course run into problems if you try to do things i just haven't thought of (hence for the same reason i can't name examples...). please think of backups, and let me know if you discover bugs or miss helpful features. as always, any feedback is most welcome!
a token of gratitude
if you appreciate my work an want to say "thanks", please check my wantlist on discogs4 (just have records sent to the address you find in the imprint/impressum). you're awesome!