forked from hadley/r-pkgs
-
Notifications
You must be signed in to change notification settings - Fork 0
/
check.Rmd
106 lines (68 loc) · 5.26 KB
/
check.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
---
title: Checking a package
layout: default
output: bookdown::html_chapter
---
## Checking
If you want to submit your package to CRAN, it must pass `R CMD check` without any warnings or errors, and preferrably as few notes as possible. Even if you're not planning on submitting to CRAN, running a check is still a good idea because it can detect common problems. Typically errors are severe and should be fixed, warnings are extremely important to consider, and notes are good to look into, but only need to be fixed if you're submitting to CRAN.
Passing `R CMD check` is the most frustrating part of package development, and it usually takes some time the first time. Hopefully by following the tips elsewhere in this document you'll be in a good place to start – in particular, using roxygen and only exporting the minimal number of functions is likely to save a lot of work. If you're having a lot of problems with R CMD check, somewhat counterintuitively you should try running it more often. The sooner you find out about a problem after making it, the easier it is to fix.
To check your package, run `devtools::check()`, or in RStudio, press Cmd + Shift + E.
## Check components
As well as checking the whole package, devtools provides a couple of functions for just running specific parts:
* `devtools::run_examples()`: It also has an optional parameter which tells
it which function to start at - that way once you've discovered an error,
you can rerun from just that file, not all the files that lead up to.
* `devtools::check_doc()`: documentation problems are one of the most common
causes of check failures. This function allows you to skip everything else
and focus just on documentation.
The checking functions work with `.Rd` files not roxygen comments, so all checking functions call `document()` first to ensure that your `.Rd` files are up-to-date.
## Common problems
* Sometimes `check()`ing will fail because package installation fails. You
can get the error messages most easily by trying to build the package
yourself.
* All exported objects must be documented. All paramters of functions must
be documented.
* S3 methods must have compatible method signatures to their generic. An
S3 method must have all the same arguments as its generic. If the generic
includes `...` you can have additional arguments. A common cause of this
error is defining print methods, because the `print()` generic contains
`...`.
```{r}
print
# BAD
print.my_class <- function(x) cat("Hi")
# GOOD
print.my_class <- function(x, ...) cat("Hi")
```
* You must use `TRUE` and `FALSE` in your code and examples, not `T` and `F`
* Data is not adequately compressed. See [data](#data-cran) for more details.
* Bugs in the examples or vignettes. A common cause of problems is relying on
internal functions - examples and vignettes can only use exported functions.
Also make sure that you've included all the needed package dependencies in
the description.
* Occassionally you'll get an error when building the PDF manual. This is
usually because the pdf is built by latex and you've forgotten to escape
something. Debugging this is painful - your best bet is to look up the
latex logs and combined tex file and work back from their to `.Rd` files
and back to a roxygen comment. You may need to enlist the help of a local
latex expert.
## Checking on Windows
You can check packages on Windows using `build_win()`. This builds your package and submits it to the CRAN win-builder. 30-60 minutes after submission, you'll recieve and email which will point you to the check results.
This checks both 32-bit and 64-bit builds. So if you're using C code, you'll need to make sure it works for both.
By default `build_win()` checks with both the release and development version of R. You can override this with the version parameter.
## Checking dependencies
## Continuous integration with Travis
If you use github, I recommend exploring the very useful [Travis CI](https://travis-ci.org/). Travis is a continuous integration service - that means it will run code of your choosing every time you push a commit to github.
1. Sign in to https://travis-ci.org/
1. Navigate to your [account](https://travis-ci.org/profile) and enable
travis for the repo you want to test on.
1. Run `use_travis()` to set up a basic `.travis.yml` config file. The
defaults are usually adequate for simple packages.
1. Commit and push to github.
1. Wait a few minutes to see the results in your email.
Now you're set up so that `R CMD check` will be run every time you push a commit to github, and every time some one does a pull request. Any time a failure occurs you'll find out about it right away. I find this really useful - it also encourages me to run `R CMD check` more frequently locally, because I know if it fails I'll find out about a few minutes later, often once I've moved on to a new challenge.
Common configuration:
* Fail not only on errors, but also on warnings
* Install binary packages
* Install github packages
Since you can use Travis to run arbitrary code you can use it to implement arbitrary push-to-deploy strategies. For example, it's relatively easy to deploy code to S3 - this makes it easy (for example) to update a documentation website.