by Matt Wand and David Nott

This page describes, via an example, how to make your own package of functions and data sets in the R environment.

It is geared towards running on the Linux system in the School of Mathematics at UNSW in late 2003. Modifications may be required for other platforms and later time periods.

If you successfully complete each of the instructions on this page then you should have a good idea of what is involved to organise your own R package.

This page is a concrete outcome of the Computer Package Discussion Group.

Consider a package of R functions which we will call roots that contains 3 functions: cuberoot(), fourthroot() and fifthroot(). As the name suggests, cuberoot(x) returns the cuberoot of the real number x. The functions fourthroot() and fifthroot() are defined similarly. However, to illustrate the integration of Fortran and C into R packages we will have:

The steps required for construction and installation of roots are as follows:

1. In a LINUX window issue the command cd. Then issue the command pwd. This will give the full pathname of your top directory under LINUX. If your userid is fred then it should be /c/fred. From now on we will use fred as an example userid. You will need to replace fred by your actual userid in all following instructions.
2. In the directory /c/fred make two sub-directories named myrlibrary and myrpackages
3. While still in the directory /c/fred create a file named .Rprofile that contains the single line .libPaths("/c/fred/myrlibrary"). This tells the computer that you have designated the directory /c/fred/myrlibrary as the place to store your own personal R packages; once they have been converted to an R library.
4. Now go to the directory /c/fred/myrpackages. This is where the source files of packages that you maintain will be stored. Create a sub-directory called roots. This will be the home of the source files of the roots package.
5. Now go the to directory /c/fred/myrpackages/roots and create 4 sub-directories named R, src, data and man
6. Issue the command chmod 755 * to satisfy the directory permission requirement of R packages.
7. Go to the directory /c/fred/myrpackages/roots/R. This is where the R function source code is to be stored. Create files with the following names and content: cuberoot.r, fourthroot.r, fifthroot.r and firstlib.r. Then issue the command chmod 644 * to satisfy the file permission requirement of R packages. Note that the file firstlib.r contains the source code of an R function named .First.lib() which is called whenever the package is loaded. This function is important because it ensures that the Fortran and C components of the package are loaded in.
8. Go to the directory /c/fred/myrpackages/roots/src. This is where the Fortran and C source code is to be stored. Create files with the following names and content: fthrt.f and fifrt.c. Then issue the command chmod 644 *.
9. Go to the directory /c/fred/myrpackages/roots/data. This is where datasets can be stored. Create a file with the following name and content: table.of.roots.txt Then issue the command chmod 644 *.
10. Go to the directory /c/fred/myrpackages/roots/man. This is where the manual files are to be stored. Create files with the following names and content: cuberoot.rd, fourthroot.rd, fifthroot.rd and table.of.roots.rd. Then issue the command chmod 644 *.
11. Go to the directory /c/fred/myrpackages/roots and create a file with the following name and content: DESCRIPTION
12. Open the file DESCRIPTION with an editor and change the Author and Maintainer name and e-mail address to your name and e-mail address.
13. While still in the directory /c/fred/myrpackages/roots issue the command chmod 644 DESCRIPTION.
14. The files that make up the roots package should now each be in place. Now build the package by going to the directory /c/fred/myrpackages and issuing the command R CMD build roots.
15. There should now be a file in /c/fred/myrpackages named roots_0.1-1.tar.gz. This is a portable file that contains Version 0.1-1 of the roots package. Install the package in your own R library by issuing the command R CMD INSTALL -l /c/fred/myrlibrary roots_0.1-1.tar.gz
16. To test that the package is correctly installed go to any directory in your LINUX account and activate R by typing R. Inside the R session issue the command library(roots). Type cuberoot(27). If you get back 3 then you have at least verified that this function is correctly loaded.
17. For more thorough checking type data(table.of.roots) and then type table.of.roots You can use this table to check each function with various arguments. For example, fourthroot(6) should give 1.565085.
18. Add optional extra would be to now update the package with the addition of a new function (e.g. sixthroot()), along with documentation, and create Version 0.1-2 of roots.

If you got through to the end of the above steps successfully then you should now have a good idea of what is involved to put together your own R package. Of course, you don't need to use the same names and locations for myrlibrary and myrpackages. However, note that as of September 2003 having these directories in george causes permission problems.

Finally, most of what is on this page was figured out from the 78-page document Writing R Extensions by the R Development Core Team and is available from here.