Building, Testing, and Distributing Packages

Avatar
Posit Support
Follow

Building, Testing, and Distributing Packages

Build and Reload

R packages contain a variety of resources including R code, native (C/C++/Fortran) code, datasets, documentation, as well as other supporting files. The usual workflow for package development is to make some changes, build and install the package, unload and reload the package (often in a new R session), then test as necessary.

All of these steps required to fully rebuild a package are performed in sequence when you use the Build and Reload command:

For most packages this occurs in only a couple of seconds and preserves all of your R session and RStudio IDE state. You can also execute Build and Reload using a keyboard shortcut (Ctrl+Shift+B) as well as configure RStudio to automatically save open source files prior to rebuiling.

Checking Packages

R includes a facility for checking the quality of packages (R CMD check) which you can invoke directly using the Check command:

There are wide variety of options to R CMD check that enable you to customize how the check is performed. For example:

  • --as-cran — Select customizations similar to those used for CRAN incoming checking
  • --no-manual — Do not produce the PDF manual
  • --no-vignettes — Do not check Sweave vignetttes

You can customize these options using Project Options : Build Tools. For more documentation on availble options see the article on Customizing Package Build Options.

Source and Binary Packages

You can build source and binary packages with RStudio using the Build Source Package and Build Binary Package commands:

You can customize these options for building source and binary packages using Project Options : Build Tools. For more documentation on availble options see the article on Customizing Package Build Options.

Using devtools

The devtools package includes a variety of tools aimed at making package development more productive. RStudio's package development tools integrate seamlessly with the devtools load_all and dev_mode facilities.

Load All

The dev_tools::load_all function simulates installing and reloading your package, by loading R code in R/, compiled shared objects in src/ and data files in data/. During development you usually want to access all functions so load_all ignores the package NAMESPACE. It works efficiently by only reloading files that have changed. It's not 100% correct, but it's very fast.

The RStudio Load All command (keyboard shortcut: Ctrl+Shift+L) calls the devtools load_all function for the current package.

Dev Mode

The devtools::dev_mode function switches your version of R into "development mode". In this mode, R will install packages to ~/R-dev. This is useful to avoid clobbering the existing versions of CRAN packages that you need for other tasks. Calling dev_mode() again will turn development mode off, and return you to your default library setup.

All of the RStudio package build tools are dev_mode aware, and dev_mode state is automatically preserved across restarts of R within RStudio.

Distributing Packages Publicly

R packages can be distributed in a variety of ways:

Contributing to CRAN

The "Comprehensive R Archive Network: (CRAN) is a collection of sites which carry identical material, consisting of the R distribution(s), the contributed extensions, documentation for R, and binaries. Contributing a package to CRAN allows you to easily share your work with the entire R community.

Additional information on submitting packages to CRAN can be found in the CRAN Repository Policy document.

Publishing on R-Forge or Github

R-Forge offers a central platform for the development of R packages, R-related software and further projects. If you use R-Forge to host your package source code then users can install your package directly from R-Forge using a command like this:

install.packages("MyPackage", repos="http://R-Forge.R-project.org")

GitHub is a web-based hosting service for software development projects that use the Git revision control system. If you use GitHub to host your package source code then users can install your package directly from GitHub using the install_github function in the devtools package:

library(devtools)
install_github("MyUsername", "MyPackage")

The devtools package also includes the install_gitorious, install_bitbucket, and install_url functions for installing packages from other locations.

Distributing Packages Privately

If you work in an organization that builds R packages with intellectual property, you may not want to share your packages on CRAN, R-Forge, or on a public Github repos. Instead, you may want to control who has access to your in-house R packages. There are many ways to share packages internally. Consider some of these options.

  • File shares. Save the R package source code or binaries in a common directory. Users can install these packages with Tools > Install Packages... in the IDE or with install.packages from the command line.
  • System Library. If using RStudio Workbench (previously RStudio Server Pro) or RStudio Server Open Source, give the source code or binaries for your R package to your system administrator. The Sys admin can install those packages into the system library so that everyone has access.
  • Local Repository. Create a local repository that contains your in-house packages. Use install.packages to pull your package from this local repos.

Related Topics

Comments