Today I tried to build my own R packages to submit on CRAN. I would like to document the process and some errors I encountered for future reference:
First, about programming and file preparation:
1-1. It is preferred to use object-oriented programming (oop) to enhance readability and to control errors. Commonly adapted OOP methods are S3 and S4 methods. S3 is more flexible but does not filtered errors as good as S4. S4 method is more organized.
1-2. For example data files, save the file object in list or data.frame for easy calling. For example: if the data contains objects x and y, I save them as
> mydata = list(x=x,y=y)
> save(mydata,file='mydata.rda')
Then calling the data in examples using:
> data(mydata)
> attach(mydata)
Note: attach only works for classes 'list' and 'data.frame'.
1-3. In R, use the following code to generate skeletons of R package:
package.skeleton(name_of_package,code_files='name_of_code_files',environment=.GlobalEnv,path='folders_to_put_the_R_package_skeleton',force=TRUE).
Note: I like to put all functions in one file: 'name_of_code_files.R', so that I just need to send the name of the function to R file. Otherwise we need to create a vector of function names :
package.skeleton(name_of_package,list=c(fn_1,fn_2,...),environment=.GlobalEnv,path='folders_to_put_the_R_package_skeleton',force=TRUE).
After get the skeleton, we need to edit the package files.
2-1. Description:
- fill in the information and choose license as 'GPL-3' or 'GPL(>=2)'.
- in 'Depends', put in the dependence packages and R version, e.g. R (>=1.10.2)
2-2. Namespace:
- export(fn_1,fn_2,...)
# list those functions visible to the users and all the functions needs to be documented.
- S3method(method, class)
#list S3 method. If we have a function print.goat that uses S3 method of 'print' on an
#object of class goat, then we need to write S3method(print,goat)
2-3. .Rd file (manual file): edit manual file based on the template
Finally, build, check and install the files in terminal:
3-1. To build a '.tar.gz' file, type
R CMD build package_name
To install a package, type
R CMD install package_name
To check the package, type
R CMD check package_name
3-2. Make sure to check the file before submitting to CRAN. CRAN only accepts packages without check warnings or errors. Here are some steps that are likely to have errors:
- checking S3 generic/method consistency ...
Make sure the S3 method has the same argument name in the manual file as the original
function. For example: print.goat (x,...) (has to be x instead of y)
- * checking PDF version of manual ... WARNING
> LaTeX errors when creating PDF version.
> This typically indicates Rd problems.
> * checking PDF version of manual without index ... ERROR
Check if pdflatex is in the current path. In terminal, type
pdflatex --version
If an error occurs, pdflatex is not under the current path. We need to add it to the path by
export PATH=/usr/texbin:$PATH
- if the log file says
! LaTeX Error: File `Rd.sty' not found.
Rd.sty is a style file provided by R to handle some of the macros used in help pages. You can have R tell pdflatex where to find it by using
R CMD texify --pdf package.tex
Alternatively, if your package is in directory "package", you can do
R CMD Rd2pdf package
and it will produce the .tex and texify it all in one step. I believe both will leave the log file for you to examine if there's an error, but you can force that using the "--no-clean" command line option.
Here is a good tutorial for building R packages: https://groups.google.com/forum/#!topic/mystat100/JxGR0YcYnZw
