Building packages for R on Windows: project setup

11 Januar 2016

This post will show how to prepare a package build project in R. The build itself will be demonstrated in the next post.

Prerequisites

To build a custom R package the following tools have to be installed (or provided using e.g. a portable version).

  1. R runtime environment https://cran.r-project.org/

  2. RTools - a collection of libraries, tools and compilers to build a package https://cran.r-project.org/bin/windows/Rtools/

  3. A LaTeX destribution such as MiKTeX to create the documentation (usually in PDF) https://miktex.org/download

Project Structure

Package Structure

All required R sources are located in package root/R`whereas for each R source a documentation exists in `package root/man (file suffix is .Rd). Each R package requires DESCRIPTION and NAMESPACE files. The R package to build in this example will have only 2 functions. The idea is, to provide randomized statements on demand based on a pool of predefined words. Therefore a DESCRIPTION may look as follows:

Package: StatementR
Type: Package
Title: A random statement generator
Version: 0.1
Date: 2016-01-11
Author: Oliver Loeffler
Maintainer: <oliver.loeffler@mail-domain.tld>
Description: provides methods to generate random statements.
License: MIT

The NAMESPACE defines which functions are imported and exported. There is no need to manually create this file, as the great roxygen2 package by Hadley Wickham provides an automated solution for this.

Step-by-Step

Follow next steps to create a project dir using bash or CMD. First cd into a directory of your choice.

cd StatementR
md StatementR\R StatementR\man StatementR\inst\extdata
echo "Package: StatementR" > DESCRIPTION

The contents of the DESCRIPTION example stated above can be pasted into the newly created file.

Now some R code is needed: getRandomValue.R to pick a random value from any given vector.

getRandomValue <- function(values) {
	x <- ceiling(runif(1,1,length(values)))
	values[x]
}

This function is then used to pick words from predefined vectors. Finally there will be a random statement. randomStatement.R

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
}

R returns the value of the last statements in a function when no return(…​) is defined. As we would like to make the statement generator public available, our NAMESPACE must be adjusted accordingly:

export(saySomething)
importFrom(stats, runif)

saySomething denotes the single function implemented in saySomething.R. This function will become available to users when calling library("StatementR") in R. But, to execute properly our package imports the function runif from package stats.