Building packages for R on Windows: create documentation and NAMESPACEs automatically

10 Oktober 2017

As the first 3 posts demonstrated how to build a package, this post will show how to create the NAMESPACE file and appropriate package documentation automatically.

Hadley Wickham created a package named roxygen2 which can be downloaded using R package manager, via GUI or via R command line. Using the library() function roxygen2 can be loaded.

install.packages("roxygen2")
library(roxygen2)

Creating NAMESPACE

A package NAMESPACE file can be created as follows:

setwd(choose.dir())   # change dir to project workspace
list.files()          # ensure that youre inside the proper folder
roxygenise("StatementR")

Possibly roxygen2 will complain about an incomplete final line at the end of DESCRIPTION. What it actually does, it adds a note to DESCRIPTION RoxygenNote: 6.0.1 which states the version of roxygen2 used. Note that roxygen2 will not modify the NAMESPACE file if it exists and was not created by roxygen2.

The newly created NAMESPACE will look like:

# Generated by roxygen2: do not edit by hand

export(saySomething)

Creating documentation (.Rd files)

The documentation works similar to the concept used in Java Development Kits (JDK), where a small tool called javadoc parses the sources for annotated comments and builds the API documentation from them. A comment in R is indicated by a leading #. roxygen2 considers all # followed by ' as documentation comment. For our function defined in R/saySomething.R the annotated comments would look as follows:

#' Creates a statment consisting of a pronoun, a verb, a subject and an attribute, where each of them is chosen randomly.
#' @return character
#' @author Your Name \email{maintainer@@mail.domain}
#' @references \url{http://www.raumzeitfalle.net}
#' @keywords random statement words pronouns verbs subjects
#' @examples
#' # just type:
#' saySomething()
#' @export
saySomething <- function() {
	pronouns <- c("My","Your","The","This","That","Those","These","Jack's")
	verbs <- c("is","was","will be","was never","was always")
	subjects <- c("weather","storm","tree","car")
	attribute <- c("green","red","ugly","fast","slow")

	statement <- paste(
		getRandomValue(pronouns),
		getRandomValue(subjects),
		getRandomValue(verbs),
		getRandomValue(attribute),
		"."
	)
	statement
}

Also our function R/getRandomValue() will be modified accordingly:

#' Returns a random value from given vector.
#' @return single element
#' @author Your Name \email{maintainer@@mail.domain}
#' @keywords runif ceiling
#'
#' @examples
#' # just type:
#' a <- c(7,5,1,22,31)
#' x <- getRandomValue(a)
#'
#' @importFrom stats runif
#' @export
getRandomValue <- function(values) {
	x <- ceiling(runif(1,1,length(values)))
	values[x]
}

Having the R sources modified accordingly, the NAMESPACE file deleted and the note from DESCRIPTION removed, running roxygenise("StatementR") results in follwing output:

> roxygenise("StatementR")
First time using roxygen2. Upgrading automatically...
Writing NAMESPACE
Writing getRandomValue.Rd
Writing saySomething.Rd

In some cases, the sequence of importing functions into the package is crucial. Here the roxygen2 call would look as follows:

roxygenise("StatementR",roclets=c("collate","namespace","rd"))

Collate will ensure that imports are defined in their appropriate order in NAMESPACE.

With having now all .Rd files and NAMESPACE written, the package can be build:

R CMD build StatementR
R CMD check StatementR
R CMD INSTALL --build StatementR

Executing ??StatementR now opens the help specific to our new installed packaged.

library(StatementR)
?saySomething		# after loading the library, function help also works

Automate it!

Instead of running roxygenise() manually within R GUI followed by R CMD commands for build, everything can be run from one build script. First, a new file in project workspace root BuildDoc.R has to be created.

library(roxygen2)
roxygenise("StatementR",roclets=c("collate","namespace","rd"))

Then the a new file make.cmd must be created. On my system this file looks as follows:

@echo off
setlocal
set path=%path%;"C:\Program Files\R\R-3.3.2\bin\x64";
set path=%path%;C:\tools\Rtools33;C:\tools\Rtools33\bin;C:\tools\Rtools33\gcc-4.6.3;
set path=%path%;"C:\Program Files\MiKTeX 2.9\miktex\bin\x64";
R CMD BATCH BuildDoc.R
R CMD build %1
R CMD check %1
R CMD INSTALL --build %1
endlocal

Then, from within the workspace root running make.cmd at the command line will execute the creation of all documentation files, the actual package build, the package check and the package installation.

Where to continue?

More details about roxygen2, how it works, what it is capable to do, is available at GitHub and CRAN. The documentation on writing extensions at R-Project.org is very comprehensive and details. Another recommendation is a very good article on building and testing of packages at RStudio.com. Yes, testing of packages. Testing is one crucial aspect of software development and according to my experience alway underestimated where R is used.

Well, also to mention as a great source of information is r-bloggers.com, where the following article about package building is located: https://www.r-bloggers.com/building-a-package-in-rstudio-is-actually-very-easy/

Conclusion

Its not difficult to build packages for R. All required tools are available at r-project.org. Extensions provide convinient mechanisms to automate documentation and parts of the package setup. I actually think that, in conjunction with a version control system and nicely implemented tests, R package building would be more fun when executed continuously using Jenkins, Travis CI or GoCD. But this would fill another post.

Well, I hope you enjoyed reading these posts and it was helpful and/or interesting. Feedback is always welcome.