## Friday, December 16, 2005

### Creating a R Package in Win XP with Cygwin

The short answer you can't build packages using Cygwin tools and a Windows installation of R. Building a package with R requires certain Unix tools and trying to set the Windows Path environment variable to include cygwin\bin does not work because the programs are not compiled in a way R can use them.
Necessary Tools

The tools you'll need to create the package (these are all required)

1. The Unix utilities, Rtools, by Brian Ripley and Duncan Murdoch. A batch file later in this article requires the zip file to be placed in C:\Program Files\R\R_VERSION\Rtools
2. If the package contains C/C++/Fortran code you will need the MinGW GNU compiler set.
3. ActiveState Perl
4. A version of TeX (MikTex)
Creating Package Structure
A basic R package requires two files in the top level directory. Throughout this article packagename refers both to the name of the package and the name of the top level folder when used with Rcmd.exe.

DESCRIPTION
NAMESPACE
And two subdirectories
man:     Documentation
R:    R functions
The DESCRIPTION file has the following format:
Package: pkgname
Version: PROGRAMVERSION
Date: DATE
Title: TITLE
Author: Joe Developer , with contributions from A. User .
Maintainer: Joe Developer
Depends: R (>= R_VERSION)
Description: A short (one paragraph) description of what the package does and why it may be useful.
URL: http://www.r-project.org, http://www.another.url
The NAMESPACE file contains a list of functions in your package which will be available to the user:
export( function1, function2, ... )
The man folder contains documentation for R objects written in "R documentation" (Rd) format that is similar to LaTeX. The man\packagename.Rd file has the following format:
\name{packagename}
\alias{packagename}
\title{Title}
\description{...}
\usage{function(arg1, arg2, ...)}
\arguments{
\item{arg_i}{arg_i description}
}
\examples{...}
\seealso{...}
\keyword{key}
The R folder contains R code to be included in the package:
function_name=
function(arg) {...}
Setting Up Tools

The following batch script masks a Cygwin installation from R by setting the PATH environment variable to only the directories necessary to build or install an R package. All R CMD commands should be run in the command prompt the following batch file creates.

NOTE: This scripts works even if Cygwin is installed. HOWEVER, you can not have any Cygwin applications running (not even a shell or XEmacs for Cygwin) at the same time you try to run RCMD.
@echo off
rem ###################################################
rem # Usage: RCMDprompt.bat [path]
rem #
rem # This script opens a MS-DOS prompt with a enviroment variables
rem # set such that R can be ran and packages can be build.
rem # If 'path' is given, the working directory will be set accordingly.
rem #
rem # NOTE: This scripts works even if Cygwin is installed.
rem # HOWEVER, you can not have any Cygwin applications
rem # 
running (not even a shell or XEmacs for Cygwin) at the same
rem #
time you try to run RCMD.
rem #
rem # Requires:
rem # To build and install packages two things must be installed, i.e.
rem # exists in the PATH. First, the Rtools compilation [1] by B.
rem # Ripley must exists. The path (R_TOOLS) to it is set below.
rem #
Second, Perl (must not be Cygwin/Perl) must also exists. The
rem #
path to it is set below.
rem #
rem # Reference:
rem # [1] http://www.stats.ox.ac.uk/pub/Rtools/
rem #
rem # Henrik Bengtsson, hb at maths.lth.se, Mar-04
rem # Modified by Augustin Luna, augustin at mail.nih.gov, Dec-05
rem ###################################################

rem # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
rem # 1. "Global" environment variables
rem # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
rem # Short version of PROGRAMFILES, e.g. 'C:\Progra~1' instead of
rem # 'C:\Program Files\', which contains spaces that are BAD for R
set PROGRAMFILES_SHORT=C:\Progra~1

rem # Directory where user directories are
set USERSDIR=C:\Docume~1

rem # Set the main R directory
set R_ROOT=%PROGRAMFILES_SHORT%\R

rem # Set the R_HOME directory (THIS LOCATION MAY BE DIFFERENT)
set R_HOME=%R_ROOT%\rw2011
rem set R_HOME=%R_ROOT%\rw2011

rem # Set the HOME directory. This is the directory where R looks
rem # for the .Rprofile and .Renviron files. See ?Startup.
rem # Set TMPDIR to a temporary directory
set TMPDIR=%TEMP%

rem # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
rem # 2. Setup the PATH
rem # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
rem # Clear the PATH (making the main Cygwin installation
rem # "invisible")
path ;

rem # Set the LaTeX directory (Using default installation parameters)
path C:\texmf\miktex\bin;%PATH%

rem # Set the Microsoft HTML Help Compiler directory
path %PROGRAMFILES%\HTML Help Workshop;%PATH%

rem # Set the Perl directory
path C:\Perl\bin;%PATH%

rem # Set the Rtools\bin directory
rem # (THIS LOCATION MAY BE DIFFERENT)
path %R_HOME%\Rtools\bin;%PATH%

rem # Set the R_HOME directory
path %R_HOME%\bin;%PATH%

rem # Set the WINDOWS directory
path %SystemRoot%;%PATH%

rem # Set the WINDOWS/system32 directory
path %SystemRoot%\system32;%PATH%

rem # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
rem # 3. Start the MSDOS prompt in the given directory
rem # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
rem # Change directory according to argument 1
cd %1%

rem # Start the MSDOS commando prompt
%SystemRoot%\system32\cmd.exe
Modifications from the original RCMDprompt.bat script
Checking Package Documentation

The CHECK parmeter is used to check the documentation of the package for any errors.

Rcmd.exe CHECK packagename
You may see the following error:
* checking packagename-manual.tex ... ERROR
LaTeX errors when creating DVI version.
This typically indicates Rd problems.
Typically, but not always and not in this case. You now need to do the following

After doing this re-run Rcmd.exe CHECK packagename. Most likely you will get a popup titled "Package Installation" attempting to install the following packages:
upquote and lm
Click Change; Select Internet; Choose a Package Repository and click Finish. Click Install. The popup will reappear if you there are any other necessary packages that need to be installed.

Building Package
Rcmd.exe BUILD packagename
Installing Package
Rcmd.exe INSTALL packagename_version.tar.gz
References
Making R Packages Under Windows by Peter Rossi (PDF)
http://cran.r-project.org/doc/manuals/R-exts.html
http://www.murdoch-sutherland.com/Rtools/
https://stat.ethz.ch/pipermail/r-devel/2004-March/029152.html