updateR: A flexible R package updater.

In drmjc/updateR: Package development toolkit

Description

This function can be used to roxygenize, check source, build (source/binary/windows binary), check bundle, install, reload in active R session (see notes), test and deploy R packages. Under-the-hood, it calls a shell script, which in turn calls various “R CMD” programs, like R CMD CHECK,BUILD,INSTALL, as well as roxygen2 & testthat. This function assumes that you develop your R packages within a top level directory, eg ~/src/R given by the options("src.root") option.

Usage

  updateR(package, src.root = getOption("src.root"),
    lib.loc = NULL, warn.conflicts = TRUE, roxygen = FALSE,
    check.source = FALSE, source = TRUE, binary = FALSE,
    winbinary = FALSE, no.vignettes = FALSE,
    no.manual = FALSE, no.docs = FALSE,
    no.examples = FALSE, check.bundle = FALSE,
    install = TRUE, test = FALSE, deploy = NULL)

Arguments

package	the name of the package to be updated. either quoted, or unquoted.
src.root	the path to the root of the src files.
lib.loc	where to install the library. Defaults to .libPaths()[1]
warn.conflicts	see relibrary
roxygen	logical: roxygenize the package (generate Rd files on the fly)?
check.source	logical: R CMD CHECK the package prior to building it?
source	logical: Build a source package? If “TRUE”, and “install=TRUE”, then this is the package that will be installed.
binary	logical: Build a binary package?
winbinary	logical: Build a windows binary package?
deploy	either NULL, or the hostname to SCP and R CMD INSTALL the package bundle to. see details.
no.vignettes	logical: if “TRUE”, turn off the creation of vignettes
no.manual	logical: if “TRUE”, turn off the creation of PDF manuals
no.docs	logical: if “TRUE”, turn off the creation of documentation
no.examples	logical: if “TRUE”, turn off the CHECK-ing of examples during check.bundle and check.source
check.bundle	logical: R CMD CHECK --as-cran the package bundle after building it?
install	logical: R CMD INSTALL the package?
test	logical: run a testthat::test_package suite, on the installed version of the package? Note this is done after this function is given the opportunity to install the package.

Details

Example workflow: These are the steps during a typical package development cycle, which are supported by updateR:
roxygenize mypackage (roxygenize)
R CMD CHECK mypackage (check.source)
R CMD BUILD mypackage (source)
R CMD INSTALL –binary mypackage (binary)
R CMD CHECK mypackage.tar.gz (check.bundle)
R CMD INSTALL mypackage.tar.gz (install)
testthat::test_package("mypackage") (test)
reload package in current R session (reload)
deploy to remote host (SCP and R CMD INSTALL on host: deploy)
Typically, a simple updateR("my.package", source=TRUE, install=TRUE), causes the package to be built, installed & reloaded.
or from the command line, updateR.sh -r -s -i ./mypackage.

roxygenize

roxygen2 is an inline documentation engine which builds Rd files from structured comment headers above each function. roxygen2 creates Rd files, and updates the NAMESPACE and the Date and Collates fields in the DESCRIPTION files, however it normally does this in a separate copy of the package. updateR removes all previously existing Rd files & replaces them with new Rd files, and merges the changes made to NAMESPACE and DESCRIPTION into the package directory. WARNING this will delete any files which are only encoded in the Rd format, and not in roxygen comments. Try the Rd2roxygen package for converting from Rd to roxygen comments.

CHECKing

R CMD CHECK is run either on the source code (check.source), or the built package bundle (check.source). In the latter case, R CMD CHECK --as-cran is used. The tests which are OK are hidden from the user; only the notes, warnings and errors are printed.

INSTALLing

R CMD INSTALL will be run as the current user, thus the package will be installed to the typical location where you have permission. On Linux this is usually a user-specific R-library, but on OSX, this is usually the global R-library.

BUILDing

The package source can be BUILT into a source, or binary bundle, or both. Currently building a windows binary (winbinary) package is unsupported. If you need a windows binary from a non-windows machine, then check out http://win-builder.r-project.org/. Note that since R-2.14, building binary packages is always preceded by installing the package. See REFERENCES in updateR.sh for more info.

Testing

If the package contains a testthat package suite, then selecting test=TRUE will run a test_package on the package.

Deploy

if deploy="hostname", then the newly built package bundle will be deployed, ie SCP'ed and installed to that host. Note that if you run updateR with source=FALSE, binary=FALSE, then the existing package bundle will be deployed.
This handles a few scenarios:
[1] local and remote usernames are identical, and you have setup password-less authentication, then just set deploy="hostname".
[2] local and remote usernames differ, and you have setup password-less authentication, then set deploy="username@hostname"
[3] you have to enter an SCP and SSH password, then
set deploy="username@hostname -p mypassword"
All of these scenario's will install the package to whereever you have rights to do so.

relibrary

Once code has been updated, and INSTALLed, you can reload the package in the current R session. Note this can't be done from the commandline. This generally works well, but since the R documentation files are cached in a lazyload db, it's impossible to update the documents in the same R-session, and you will get this error:
“Error in fetch(key) : internal error -3 in R_decompress1”
see reload for more info.

TODO

devtools

Investigate more of Hadley's devtools functions for build/check/install.

Author(s)

Mark Cowley

See Also

relibrary, roxygenize, test_package, .Rprofile, install.packages

Examples

## Not run: 
# build a source package, and install.
updateR("updateR", "~/src/R")
updateR("updateR", "~/src/R", source=TRUE, install=TRUE)
# roxygenize, check.source, and then build a source package, and install.
updateR("updateR", "~/src/R", roxygen=TRUE, check.source=TRUE, source=TRUE, install=TRUE)
# roxygenize, check.source, and then build a source package, and install + test & deploy.
updateR("updateR", "~/src/R", roxygen=TRUE, check.source=TRUE, source=TRUE, install=TRUE, test=TRUE, deploy="enzo")

## End(Not run)

drmjc/updateR documentation built on May 15, 2019, 2:41 p.m.