presentations/cran/cran.md

In leerichardson/leeR: R-Package Development Examples

CRAN and R-Packages

author: Lee F Richardson date: Jan 30, 2018

1. What is CRAN? Why use it?
2. R CMD check
3. Travis, Win-builder, and Submitting

All code online at: https://github.com/leerichardson/leeR

What is 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." - CRAN servers all over the world, called mirrors - CRAN mirrors have contributed extensions (R-packages)

Why put your package on CRAN?

- Authenticity

• Quality Control (external standards/checks)

• More likely to be used (install.packages)

CRAN vs. Github

  - CRAN and Github: Platforms for sharing R packages

• CRAN more reliable, takes more effort

• Github easy, no external checks

• Choice depends on project

It all comes down to R CMD check

  R CMD check: Terminal command, checks package  

• Runs a series of checks on package

• Run in console with the devtools package:  

  devtools::check()

 

devtools::check() also: - Runs documentation, builds package (R CMD build)

Three Types: Notes, Warnings, and Errors

R CMD check gives three types of feedback: - Errors: Most Severe - Warnings: Medium Severe - Notes: Least Severe

Details on each check: 1.3.1 Writing R Extensions

Example 1: Checking the Tests

Say we add a new test to our package:

test_that("our function works", {
  expect_equal(2, 2)
  expect_equal(1, 2)
})

What will devtools::check() do?

Error: Tests don't run!

Example 2: Checking documentation

#' Print a string!
#'
#' @param string to print
#' @param fake parameter
#'
#' @return A printed string
#' @examples
#' to_print <- "Hello, world!
#' leeR_demo(to_print)
#'
leeR_demo <- function(string) {
  print(string)
}

devtools::check()?

Warning: Function/Docs don't match

Example 3: Anything wrong here?

#' Multivariate normal random numbers
#'
#' @param n number of observations
#' @param mean_vec vector of means
#'
#' @return n x length(mean_vec) of
#' observations from a multivariate normal
generate_mvnorm <- function(n, mean_vec) {
  rmvnorm(n = n, x = mean_vec)
}

devtools::check()...

Note: Using an external package

  devtools::use_package("mvtnorm")
  mvtnorm::rmvnorm

After R CMD check passes, we need to...

  - Remember to keep running R CMD check

• Make sure R CMD check passes on multiple operating systems

Solve with Continuous Integration and Win-builder!

Continuous Integration automates checks

What is Continuous Integration (CI)?

"Continuous Integration is the practice of merging in small code changes frequently - rather than merging in a large change at the end of a development cycle. The goal is to build healthier software by developing and testing in smaller increments. This is where Travis CI comes in." - https://docs.travis-ci.com/user/for-beginners - Travis is a "Continuous Integration" (CI) service

• Use Travis R CMD check on every Github push

How to integrate Travis with R-package

  - Add to package with:

  devtools::use_travis("/home/lee/Dropbox/leeR")

• Creates .travis.yml in source directory

• Get Travis account, link Github account

• Push to Github

• E-mail will tell you if it passed

Travis builds and checks on Ubuntu

Win-builder builds and checks on Windows

  - Travis checks package on Ubuntu

• Win-builder checks package on Windows

  devtools::build_win()

• Build, submits to https://win-builder.r-project.org/

• E-mail in 30-60 minutes with results  

Win-builder builds and checks on Windows

Submitting the finished package

1. R CMD check passes
2. Travis CI passes
3. Win-builder passes

Once these steps are complete: - Follow http://r-pkgs.had.co.nz/release.html#release-check - Aim, aim, Let it fly!

  devtools::release()

Submits this form https://cran.r-project.org/submit.html

Conclusions

 

• It all comes down to R CMD check

• Know goals, prepare early for CRAN

• Travis, winbuilder are useful external tools

• Big victory for the devtools/R-packages book

Resources

• http://r-pkgs.had.co.nz/check.html
• https://cran.r-project.org/doc/manuals/r-release/R-exts.html#useDynLib
• http://www.hep.by/gnu/r-patched/r-faq/R-FAQ_20.html
• https://cran.r-project.org/web/packages/policies.html

Two good lists of all the checks are - http://r-pkgs.had.co.nz/check.html - Section 1.3.1 of Writing R Extensions

leerichardson/leeR documentation built on May 21, 2019, 1:39 a.m.