R Language Creating packages with devtools Creating and distributing packages
Example
This is a compact guide about how to quickly create an R package from your code. Exhaustive documentations will be linked when available and should be read if you want a deeper knowledge of the situation. See Remarks for more resources.
The directory where your code stands will be refered as ./, and all the commands are meant to be executed from a R prompt in this folder.
Creation of the documentation
The documentation for your code has to be in a format which is very similar to LaTeX.
However, we will use a tool named roxygen in order to simplify the process:
install.packages("devtools")
library("devtools")
install.packages("roxygen2")
library("roxygen2")
The full man page for roxygen is available here. It is very similar to doxygen.
Here is a practical sample about how to document a function with roxygen:
#' Increment a variable.
#'
#' Note that the behavior of this function
#' is undefined if `x` is not of class `numeric`.
#'
#' @export
#' @author another guy
#' @name Increment Function
#' @title increment
#'
#' @param x Variable to increment
#' @return `x` incremented of 1
#'
#' @seealso `other_function`
#'
#' @examples
#' increment(3)
#' > 4
increment <- function(x) {
return (x+1)
}
It is also recommanded to create a vignette (see the topic Creating vignettes), which is a full guide about your package.
Construction of the package skeleton
Assuming that your code is written for instance in files ./script1.R and ./script2.R, launch the following command in order to create the file tree of your package:
package.skeleton(name="MyPackage", code_files=c("script1.R","script2.R"))
Then delete all the files in ./MyPackage/man/.
You have now to compile the documentation:
roxygenize("MyPackage")
You should also generate a reference manual from your documentation using R CMD Rd2pdf MyPackage from a command prompt started in ./.
Edition of the package properties
1. Package description
Modify ./MyPackage/DESCRIPTION according to your needs. The fields Package, Version, License, Description, Title, Author and Maintainer are mandatory, the other are optional.
If your package depends on others packages, specify them in a field named Depends (R version < 3.2.0) or Imports (R version > 3.2.0).
2. Optional folders
Once you launched the skeleton build, ./MyPackage/ only had R/ and man/ subfolders. However, it can have some others:
data/: here you can place the data that your library needs and that isn't code. It must be saved as dataset with the.RDataextension, and you can load it at runtime withdata()andload()tests/: all the code files in this folder will be ran at install time. If there is any error, the installation will fail.src/: for C/C++/Fortran source files you need (usingRcpp...).exec/: for other executables.misc/: for barely everything else.
Finalization and build
You can delete ./MyPackage/Read-and-delete-me.
As it is now, your package is ready to be installed.
You can install it with devtools::install("MyPackage").
To build your package as a source tarball, you need to execute the following command, from a command prompt in ./ : R CMD build MyPackage
Distribution of your package
Through Github
Simply create a new repository called MyPackage and upload everything in MyPackage/ to the master branch. Here is an example.
Then anyone can install your package from github with devtools:
install_package("MyPackage", "your_github_usename")
Through CRAN
Your package needs to comply to the CRAN Repository Policy. Including but not limited to: your package must be cross-platforms (except some very special cases), it should pass the R CMD check test.
Here is the submission form. You must upload the source tarball.
