Creating R packages

Creating R Packages...
  You are here:   Home • computer stuff • computer help • R help • R packages


Dan Bailey and I have spent a while banging our heads against the R extensions brick wall. After trawling through the various manuals, forums and websites giving help on making R packages, and still having some trouble understanding how to successfully create R extensions, we have decided to set out our own instructions, in the hope that people (of the not computer-minded variety) will be able to ignore all the confusing stuff which generally accompanies R help.

Please note that this information is mainly gleaned from a couple of useful websites, pointed to in what follows, and our experiences. We hope to add our own examples shortly to clarify things further. I try to update it when new information comes to me, mainly on the troubleshooting side of things. Thanks to all who have helped constructing this page. If you still have problems after this, then may God spare your sanity. Please feel free to email me, though. Good luck.


---Installing R packages---

If you already have an R package, and just want to install it, use the links below and follow steps 1,7,8 (Linux-Linux) for Linux [.tar] packages, or step 6 (Windows-Windows) for windows [.zip] R packages.


---Creating and installing R packages from scratch---

The instructions below come in a few different flavours. Building packages in...

• Linux for use in R for Linux • Linux for use in R for Windows • Windows for use in R for Windows • Windows for use in R for Linux • Mac OS •


Other stuff:

• Sample Windows build output • Troubleshooting •




Linux-Linux   [top]


This is mainly skinned from the tutorial by Wand and Nott. Use the files linked to their website for an example.

Or for the lazy, the links are here:

 [cuberoot.r]   [fourthroot.r]   [fifthroot.r]   [firstlib.r]   [fthrt.f]   [fifrt.c]   [table.of.roots.txt]   [cuberoot.rd]   [fourthroot.rd]   [fifthroot.rd]   [table.of.roots.rd]   [DESCRIPTION]

You may also want the following file (see step 8):

[zzz.r]

1. In a Linux command window, use cd and then pwd to find out your home filespace. This should be something like /c/userid or /home/maman. Then create two directories, named myrlibrary and myrpackages (eg mkdir myrpackages). myrpackages will contain the source files of your package, while myrlibrary will be where the package is built. Then using an text editor (vi, emacs etc) create a file named .Rprofile which contains the single line .libPaths("/home/maman/myrlibrary"). This says "/home/maman/myrlibrary is where my packages will be".

2. Go to your packages directory (cd myrpackages), and create a directory for your package (eg mkdir roots). If necessary, change the permissions of this directory to drwx r-x r-x. This is so that the directory is accessible: chmod 755 roots. This is equivalent to chmod go+rx roots if the user already have permissions [file permissions help]. Use ll to check the permissions. Create 2 directories called man and R. The man directory will contain your R (.Rd) help files, and the R directory will contain the code files for your R functions (generally .R).

If you also have datasets, create a directory in roots called data to put them in.

If you also have compiled code files (c or fortran files), create another directory in roots named src to put them in.

Change the permissions (if necessary) of all created directories in roots to rwx r-x r-x (chmod 755 *).

3. go to the man directory, and create a .Rd file for each of your functions or datasets in the package (R code, C code and Fortran code). Here are some tips for writing R documentation files.

Put the datasets, R code and compiled code in the relevant directories.

If you have C or Fortran code files (.c or .f files), add the file firstlib.R to your roots/R directory. Edit the code to have the name of your package instead of "roots". This file tells R to load in the compiled code contained in the src directory.

4. Go into each of the directories R, man (and data and src if you have them) in turn, and make sure that all the files in them are readable, by using chmod 644 *.

5. Go to the main roots directory and create a file called DESCRIPTION. The R extensions manual has good information on the layout of this file. Note that the first line (package) must have the same name as the package directory (eg. roots). Change the permissions of this file to readable: chmod 644 DESCRIPTION. Now the structure of the package is done.

6. Build the package. Go to the myrpackages directory and do R CMD build roots. This should go through some crap and then create a zipped file of your package roots_0.1-1.tar.gz in your myrpackages directory. Note that the underscored number will match whatever you put in the Version line of your DESCRIPTION file. This comes in handy if you want to make changes to your files or add extra functions etc, so you can keep track of what you are doing and how each version changes. You have now (hopefully successfully) created an R package. You can also use R CMD CHECK roots to locate any problems in the package structure.

7. To install the package, go into the myrpackages directory (where your package is) and type R CMD INSTALL -l /home/maman/myrlibrary roots_0.1-1.tar.gz (replacing roots with your package name to install a different package). By the way, that's the letter l, not the number 1. This says, "install my wonderful new package in my myrlibrary directory". You can check the DESCRIPTION file in the /myrlibrary/roots directory for a Built line to see if it has installed properly.

Tip: If, like me, you are constantly changing your code and building different package versions, you can install packages "tidily" by using the install command R CMD INSTALL --with-package-versions -l /home/maman/myrlibrary roots_0.1-1.tar.gz. This will install the package as /myrlibrary/roots_0.1-1, and has the effect that you can load packages by version with e.g. library(roots, version="0.1-1").

Note: If you do this, then a simple library(roots) command will load the latest package version. However, BEWARE of doing a mixture of installing --with-package-versions and not; if you do, a simple library(roots) command will load the package without a version number.

8. To see if the package works, start R from whichever directory you want, and type library(roots). A sometimes useful addition to the package structure is to add the file zzz.r (above) to your package subdirectory R. This prints a message to tell you when your package has loaded. Then test out your functions, eg. fifthroot(32).


Linux-Windows   [top]


If you DO NOT have C or Fortran files, the easy way of doing this is follow the instructions above for Linux packages, and then simply copy the built package directory roots (from the myrlibrary directory) into Windows somewhere. Then zip it (we recommend using Winzip) as a .zip file. This can then be installed into R by using the Packages -> Install package(s) from local .zip files tab. library(roots) will make the package available in the workspace as usual. Note the library(roots) step of this will NOT work for packages with compiled code in it.

If you do have compiled code files, then you can copy the unbuilt folder roots to somewhere in Windows, and then build it from there using the command prompt (see no. 5 in instructions for Windows below). For this you will need to download and install the tools (cygwin), Perl and mingwin, so this is in fact virtually identical to following the Windows instructions (you will need to do all except no. 3).

If you can't get these tools, or can't get them to work (more likely) then there are some instructions on cross-compiling R packages for Windows in Linux. We have so far failed to get this working (maybe due to the system we are using), but hope to sometime in the future. Sorry if this is no use to you.


Windows-Windows   [top]


N.B. This advice works for our Windows 2000 PCs. If anybody has followed the more recent "Writing R packages" and had success and would like to contribute to this page, please email me. See the troubleshooting for solutions to some problems which you may encounter on different Windows versions.

You may have problems with this...

1. Download Perl, cygwin and mingwin from Brian Ripley's tools page. There are a lot of different versions of mingwin etc, so if you don't want to muck about figuring out which to use, here are the versions of these tools which we have used (which work)

[Perl]     [cygwin (=tools)]     [mingwin]     [hhc.exe]



You should unzip the tools into C:\cygwin, and the compressed mingwin into C:\mingwin. Perl should be put in C:\Perl. The hcc.exe file is to create the .chm help files for your package. This file should go in C:\cygwin. You may also want to download the latest version of html help workshop, which you can also find here. (I recommend it, just to ensure that you have all the relevant files - basically you need hha.dll somewhere on your computer).

2. Put the programs in your path. In Windows, go to (Start->Settings->)Control Panel->System->Advanced. Click on the Environment Variables button, which should be in the middle. In the lower list of variables, there should be one called Path. Press edit (on the lower set of buttons) and add the locations of the three new programs. There is a bit of confusion as to the whether the order in which they come matters, but we suggest

C:\Perl\bin\;C:\cygwin;[other stuff - DO NOT REMOVE];C:\mingwin\bin

Important: The Path should not have any spaces in between entries (after semi-colons).

Note: Perl has a setup program, so will probably add itself to the Path automatically, so check what it's done before you add Perl to the Path.

3. Create the package directories somewhere as in the Linux instructions 2-5 (the file permissions will be automatic).

Tip: You can create a package skeleton in R, by sourcing your functions/code into the workspace and then using the command package.skeleton(name="roots",list=ls()). Then edit the DESCRIPTION file and .Rd files appropriately.

4. Open a command prompt (Start->Programs->Accessories->Command Prompt). Change directory to your version of R: (normally eg cd \Program Files\R\rw1090\bin.

The R directory should include the Source Package Installation Files, by which I mean the bin directory should have the files build, check and Rcmd. If not, then reinstall R with the source installation files box checked.

5. Now build the package: Rcmd build --force --binary packagelocation eg. Rcmd build --force --binary C:\temp\roots. Note that this is slightly different to the Linux command R CMD. I recommend having your package in a directory path without spaces (i.e. preferably not in a subdirectory of C:\ Program Files, since it tends to create problems (especially with checking) if you can't describe the path implicitly through parent directories eg ..\ ..\ package). It is often useful just to put the package directory in the bin directory to avoid writing the location altogether. Then the command would be Rcmd build package. This should go through some crap and then create a .zip file of the package.

Tip: It is worth issuing the command Rcmd check package before building it, especially if your package is large or contains code from various sources, so that any problems in code, examples, help files etc can be located prior to distributing the package. I think this also is responsible for building/updating the html versions of the help files.

6. Install the package in R in the usual way: Packages -> Install package(s) from local .zip files, then library(roots). Note that the .zip file will be contained in the R bin location C:\Program Files\R\rw1090\bin.


Windows-Linux   [top]


1. Follow the instructions 1-4 above.

2. Build the package into a tar file: From the R bin directory, type Rcmd build packagelocation, eg. Rcmd build C:\temp\roots, or Rcmd build roots if you have put the package directory in the R bin directory.

3. In your Linux account, perform instruction 1 from the Linux section of this page. Copy the newly created .tar.gz file from Windows (C:\Program Files\R\rw1090\bin) to the \myrpackages directory in your Linux filespace.

4. Install the package: Follow instruction 7 in the Linux instructions.


MacOS   [top]


I do not have any experience with Macs at all, and so have not used R on a Mac. However, I am reliably informed that there is a guide out there for building R packages for Mac users:

Creating R packages on a Mac


Windows build output   [top]

I thought that it would be helpful if I gave what my computer says when doing an Rcmd check, Rcmd build or Rcmd build --force --binary. This output will probably change slightly, depending on which version of R you use.

C:\removethis\R-2.2.1\bin>Rcmd check C:/removethis/rw1090/roots

* checking for working latex ... OK
* using log directory 'C:/removethis/R-2.2.1/bin/roots.Rcheck'
* using R version 2.2.1, 2005-12-20
* checking for file 'roots/DESCRIPTION' ... OK
* this is package 'roots' version '0.1-3'
* checking if this is a source package ... OK

installing R.css in C:/removethis/R-2.2.1/bin/roots.Rcheck


---------- Making package roots ------------
adding build stamp to DESCRIPTION
making DLL ...
making fifrt.d from fifrt.c
gcc -Ic:/removethis/R-2.2.1/include -Wall -O2 -c fifrt.c -o fifrt.o
g77 -O2 -Wall -c fthrt.f -o fthrt.o
ar cr roots.a fifrt.o fthrt.o
ranlib roots.a
windres --include-dir c:/removethis/R-2.2.1/include -i roots_res.rc -o roots_re
s.o
gcc --shared -s -o roots.dll roots.def roots.a roots_res.o -Lc:/removethis/R-
2.2.1/src/gnuwin32 -lg2c -lR
... DLL made
installing DLL
installing R files
installing data files
installing man source files
installing indices
not zipping data
installing help
>>> Building/Updating help pages for package 'roots'
Formats: text html latex example chm
cuberoot text html latex example
fifthroot text html latex example
fourthroot text html latex example
table.of.roots text html latex
Microsoft HTML Help Compiler 4.74.8702

Compiling c:\removethis\rw1090\roots\chm\roots.chm


Compile time: 0 minutes, 0 seconds
5 Topics
16 Local links
0 Internet links
1 Graphic


Created c:\removethis\rw1090\roots\chm\roots.chm, 16,409 bytes
Compression increased file by 4,371 bytes.
adding MD5 sums

* DONE (roots)

* checking package directory ... OK
* checking for portable file names ... OK
* checking DESCRIPTION meta-information ... OK
* checking package dependencies ... OK
* checking index information ... OK
* checking package subdirectories ... OK
* checking R files for syntax errors ... OK
* checking R files for library.dynam ... OK
* checking S3 generic/method consistency ... OK
* checking replacement functions ... OK
* checking foreign function calls ... OK
* checking Rd files ... OK
* checking for missing documentation entries ... OK
* checking for code/documentation mismatches ... OK
* checking Rd \usage sections ... OK
* checking for CRLF line endings in C/C++/Fortran sources/headers ... OK
* creating roots-Ex.R ... OK
* checking examples ... OK
* creating roots-manual.tex ... OK
* checking roots-manual.tex ... OK


 ===============================

C:\removethis\R-2.2.1\bin>Rcmd build C:/removethis/rw1090/roots

* checking for file 'C:/removethis/rw1090/roots/DESCRIPTION' ... OK
* preparing 'C:/removethis/rw1090/roots':
* checking DESCRIPTION meta-information ... OK
* cleaning src
* removing junk files
* checking for LF line-endings in source files
* checking for empty directories
* building 'roots_0.1-3.tar.gz'


 ===============================

C:\removethis\R-2.2.1\bin>Rcmd build --force --binary C:/removethis/rw1090/roots

* checking for file 'C:/removethis/rw1090/roots/DESCRIPTION' ... OK
* preparing 'C:/removethis/rw1090/roots':
* checking DESCRIPTION meta-information ... OK
* cleaning src
* removing junk files
* checking for LF line-endings in source files
* checking for empty directories
* building binary distribution
WARNING
* some HTML links may not be found

Using auto-selected zip options ''

---------- Making package roots ------------
adding build stamp to DESCRIPTION
making DLL ...
making fifrt.d from fifrt.c
gcc -Ic:/removethis/R-2.2.1/include -Wall -O2 -c fifrt.c -o fifrt.o
g77 -O2 -Wall -c fthrt.f -o fthrt.o
ar cr roots.a fifrt.o fthrt.o
ranlib roots.a
windres --include-dir c:/removethis/R-2.2.1/include -i roots_res.rc -o roots_re
s.o
gcc --shared -s -o roots.dll roots.def roots.a roots_res.o -Lc:/removethis/R-
2.2.1/src/gnuwin32 -lg2c -lR
... DLL made
installing DLL
installing R files
installing data files
installing man source files
installing indices
not zipping data
installing help
>>> Building/Updating help pages for package 'roots'
Formats: text html latex example chm
cuberoot text html latex example chm
fifthroot text html latex example chm
fourthroot text html latex example chm
table.of.roots text html latex chm
Microsoft HTML Help Compiler 4.74.8702

Compiling c:\TEMP\Rbuild.1320\roots\chm\roots.chm


Compile time: 0 minutes, 0 seconds
5 Topics
16 Local links
0 Internet links
1 Graphic


Created c:\TEMP\Rbuild.1320\roots\chm\roots.chm, 16,405 bytes
Compression increased file by 4,367 bytes.
adding MD5 sums

packaged installation of package 'roots' as roots_0.1-3.zip
* DONE (roots)


Windows building troubleshooting   [top]

(A few problems you may experience and possible solutions)


--1--
Problem: Error: [something eg sh] is not an internal or external command

Cause: cygwin is not installed properly/Windows does not know where it is.


Solution:

a) Check your Path (see no. 2 above). Make sure there are no spaces in the Path sequence. You could also try the alternative ordering

C:\Perl\bin\;[other stuff - DO NOT REMOVE];C:\mingwin\bin;C:\cygwin;

Exit from the Command Prompt and open it again to get the Path to take effect. Try building again.

or
b) Try taking an axe to your computer : this stuff is tempramental.


--2--
Problem: Can't build chm files.

Cause: does not know where hhc.exe is.


Solution:

a)Put hhc.exe in the cygwin directory.

or
b) Install the whole hhw program [hhw]. Try adding hhw to your Path as well (??) (see no. 2 above).

or
c) Go into R\src\gnuwin32\ and check that the path for hhw is correct in the configuration macros section of Mkrules. Alternatively, ask for the help files not to be built. You are supposed to be able to turn off the html help option, by editing the help section at the start of MkRules. WARNING: any editing I do in this file is simply ignored, so this is unlikely to work and is really clutching at straws.


--3--
Problem:
preparing package roots for lazy loading
Error in tools:::.read_description(file) :
file '/DESCRIPTION' does not exist
Execution halted
make: *** [lazyload] Error 1
*** Installation of roots failed ***
Cause: Lazy loading is not working properly (though i am not really sure what that is).


Solution:

a) This happens with windows to windows (binary) builds, but is not likely to happen with something as simple as roots. However, in the Command prompt, try doing your build command with forward slashes and not backslashes, i.e.

C:\rw2000\bin>Rcmd build --force --binary C:/packages/roots

 instead of

C:\rw2000\bin>Rcmd build --force --binary C:\packages\roots

 By the way, i don't think normal tar (non-binary) builds will work with forward slashes.

or
b) go into the bin directory of the version of R which you use to build packages. Then open the build file with a text editor. At about line 65 of the file, where it says
if($WINDOWS) {
die "Please set TMPDIR to a valid temporary directory\n"
unless (-e ${R::Vars::TMPDIR});
@known_options = ("help|h", ...
add "no-lazy" to the list of known_options (within the parentheses). Then under my $INSTALL_opts (at about line 90), where it says if($WINDOWS) {, add the line

$INSTALL_opts .= " --no-lazy" if $opt_no_lazy;

to the others, docs and auto-zip. Save the file. Basically, this will add an option to the Rcmd build, taken from the options of Rcmd INSTALL to remove the lazy building in the build procedure. So in other words, when binary building you can now write

C:\rw2000\bin>Rcmd build --force --binary --no-lazy C:\packages\roots.


--4--
Problem:
* checking for working latex ... Error: environment variable TMPDIR not set (or set to unusable value) and no default available
Cause: Well, it tells you: it wants the location of the windows temporary directory, though this should be set up already. (We have encountered this on Windows XP).


Solution

In dos, use:

set TMPDIR=c:\Windows\temp

where temp is your Windows temporary directory, or make up a location.


--5--
Problem:
Found the following C sources/headers with CRLF line endings: src/fifrt.c ISO C requires LF line endings.
Cause: This is a difference between line endings in text files on different OS systems, and this problem occurs when sharing text files across multiple OS. (We encountered this problem when using Windows XP).


Solution:

You need to convert the relevant C files. For converting them in Windows, software can be found at: http://www.bastet.com/.

Download UDDU and follow the instructions. Regardless of the OS, you need to use the DOS2UNIX command. This seems to do the trick. By the sounds of it the DOS2UNIX command comes with Unix as standard.


[top]


Thanks...

Many thanks to the following people (most of whom have suffered for this cause) for their useful help, comments, and questions about this page:

Dan Bailey [bristol.ac.uk] , Patrick Brandt [unt.edu] , Nick Drew , Derek Ogle [northland.edu] , John Kuhling , Marina Knight [bristol.ac.uk] , Bernard Silverman [ox.ac.uk] , Joe Zhang [umanitoba.ca]