README.md
1Run R CMD check from R and Capture Results
2================
3
4<!-- README.md is generated from README.Rmd. Please edit that file -->
5
6# rcmdcheck
7
8> Run R CMD check from R and Capture
9Results
10
11<!-- badges: start -->
12
13[![lifecycle](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://tidyverse.org/lifecycle/#maturing)
14[![Linux Build
15Status](https://travis-ci.org/r-lib/rcmdcheck.svg?branch=master)](https://travis-ci.org/r-lib/rcmdcheck)
16[![Windows Build
17status](https://ci.appveyor.com/api/projects/status/github/r-lib/rcmdcheck?svg=true)](https://ci.appveyor.com/project/gaborcsardi/rcmdcheck)
18[![](http://www.r-pkg.org/badges/version/rcmdcheck)](http://www.r-pkg.org/pkg/rcmdcheck)
19[![CRAN RStudio mirror
20downloads](http://cranlogs.r-pkg.org/badges/rcmdcheck)](http://www.r-pkg.org/pkg/rcmdcheck)
21[![Coverage
22Status](https://img.shields.io/codecov/c/github/r-lib/rcmdcheck/master.svg)](https://codecov.io/github/r-lib/rcmdcheck?branch=master)
23<!-- badges: end -->
24
25Run R CMD check form R programatically, and capture the results of the
26individual checks.
27
28## Installation
29
30``` r
31source("https://install-github.me/r-lib/rcmdcheck")
32```
33
34## Usage
35
36``` r
37library(rcmdcheck)
38rcmdcheck("path/to/R/package")
39```
40
41Call `rcmdcheck()` on a source R package `.tar.gz` file, or on a folder
42containing your R package. Supply `quiet = FALSE` if you want to omit
43the output. The result of the check is returned, in a list with elements
44`errors`, `warnings`, and `notes`. Each element is a character vector,
45and one element of the character vectors is a single
46failure.
47
48<img width="1000" src="https://cdn.jsdelivr.net/gh/r-lib/rcmdcheck@master/tools/rcmdcheck.svg">
49
50### Programmatic usage
51
52`rcmdcheck()` returns an `rcmdcheck` object, which you can query and
53manipulate.
54
55``` r
56library(rcmdcheck)
57chk <- rcmdcheck("tests/testthat/bad1", quiet = TRUE)
58chk
59#> ── R CMD check results ────────────────────────────── badpackage 1.0.0 ────
60#> Duration: 11.6s
61#>
62#> ❯ checking DESCRIPTION meta-information ... WARNING
63#> Non-standard license specification:
64#> Public domain
65#> Standardizable: FALSE
66#>
67#> 0 errors ✔ | 1 warning ✖ | 0 notes ✔
68```
69
70`check_details()` turns the check results into a simple lists with the
71following information currently:
72
73``` r
74names(check_details(chk))
75#> [1] "package" "version" "notes" "warnings"
76#> [5] "errors" "platform" "checkdir" "install_out"
77#> [9] "description" "session_info" "cran" "bioc"
78```
79
80 - `package`: Package name.
81 - `version`: Package version number.
82 - `notes`: Character vector of check `NOTE`s.
83 - `warnings`: Character vector of check `WARNING`s.
84 - `errors`: Character vector of check `ERROR`s.
85 - `platform`: Platform, e.g. `x86_64-apple-darwin15.6.0`.
86 - `checkdir`: Check directory.
87 - `install_out`: Output of the package installation.
88 - `description`: The text of the `DESCRIPTION` file.
89 - `session_info`: A `sessioninfo::session_info` object, session
90 information from within the check process.
91 - `cran`: Flag, whether this is a CRAN package. (Based on the
92 `Repository` field in `DESCRIPTION`, which is typically only set for
93 published CRAN packages.)
94 - `bioc`: Flag, whether this is a Bioconductor package, based on the
95 presence of the `biocViews` field in `DESCRIPTION`.
96
97Note that if the check results were parsed from a file, some of these
98fields might be missing (`NULL`), as we don’t have access to the
99original `DESCRIPTION`, the installation output, etc.
100
101### Parsing check output
102
103`parse_check()` parses check output from a file, `parse_check_url()`
104parses check output from a URL.
105
106### CRAN checks
107
108rcmdcheck has a functions to access CRAN’s package check results.
109
110`cran_check_flavours()` downloads the names of the CRAN platforms:
111
112``` r
113cran_check_flavours()
114#> [1] "r-devel-linux-x86_64-debian-clang"
115#> [2] "r-devel-linux-x86_64-debian-gcc"
116#> [3] "r-devel-linux-x86_64-fedora-clang"
117#> [4] "r-devel-linux-x86_64-fedora-gcc"
118#> [5] "r-patched-linux-x86_64"
119#> [6] "r-patched-solaris-x86"
120#> [7] "r-release-linux-x86_64"
121#> [8] "r-release-windows-ix86+x86_64"
122#> [9] "r-release-osx-x86_64"
123#> [10] "r-oldrel-windows-ix86+x86_64"
124#> [11] "r-oldrel-osx-x86_64"
125```
126
127`cran_check_results()` loads and parses all check results for a package.
128
129``` r
130cran_check_results("igraph")
131#> $`r-devel-linux-x86_64-debian-clang`
132#> ── R CMD check results ──────────────────────────────── igraph 1.2.4.1 ────
133#> Duration: 0ms
134#>
135#> 0 errors ✔ | 0 warnings ✔ | 0 notes ✔
136#>
137#> $`r-devel-linux-x86_64-debian-gcc`
138#> ── R CMD check results ──────────────────────────────── igraph 1.2.4.1 ────
139#> Duration: 0ms
140#>
141#> 0 errors ✔ | 0 warnings ✔ | 0 notes ✔
142#>
143#> $`r-devel-linux-x86_64-fedora-clang`
144#> ── R CMD check results ──────────────────────────────── igraph 1.2.4.1 ────
145#> Duration: 0ms
146#>
147#> ❯ checking installed package size ... NOTE
148#> installed size is 16.1Mb
149#> sub-directories of 1Mb or more:
150#> R 1.4Mb
151#> help 1.1Mb
152#> libs 13.1Mb
153#>
154#> 0 errors ✔ | 0 warnings ✔ | 1 note ✖
155#>
156#> $`r-devel-linux-x86_64-fedora-gcc`
157#> ── R CMD check results ──────────────────────────────── igraph 1.2.4.1 ────
158#> Duration: 0ms
159#>
160#> 0 errors ✔ | 0 warnings ✔ | 0 notes ✔
161#>
162#> $`r-patched-linux-x86_64`
163#> ── R CMD check results ──────────────────────────────── igraph 1.2.4.1 ────
164#> Duration: 0ms
165#>
166#> 0 errors ✔ | 0 warnings ✔ | 0 notes ✔
167#>
168#> $`r-patched-solaris-x86`
169#> ── R CMD check results ──────────────────────────────── igraph 1.2.4.1 ────
170#> Duration: 0ms
171#>
172#> ❯ checking installed package size ... NOTE
173#> installed size is 9.6Mb
174#> sub-directories of 1Mb or more:
175#> R 1.5Mb
176#> help 1.2Mb
177#> libs 6.5Mb
178#>
179#> 0 errors ✔ | 0 warnings ✔ | 1 note ✖
180#>
181#> $`r-release-linux-x86_64`
182#> ── R CMD check results ──────────────────────────────── igraph 1.2.4.1 ────
183#> Duration: 0ms
184#>
185#> 0 errors ✔ | 0 warnings ✔ | 0 notes ✔
186#>
187#> $`r-release-windows-ix86+x86_64`
188#> ── R CMD check results ──────────────────────────────── igraph 1.2.4.1 ────
189#> Duration: 0ms
190#>
191#> ❯ checking whether package 'igraph' can be installed ... NOTE
192#> See below...
193#>
194#> ❯ checking installed package size ... NOTE
195#> installed size is 16.7Mb
196#> sub-directories of 1Mb or more:
197#> R 1.4Mb
198#> help 1.1Mb
199#> libs 13.8Mb
200#>
201#> 0 errors ✔ | 0 warnings ✔ | 2 notes ✖
202#>
203#> $`r-release-osx-x86_64`
204#> ── R CMD check results ──────────────────────────────── igraph 1.2.4.1 ────
205#> Duration: 0ms
206#>
207#> ❯ checking package dependencies ... NOTE
208#> Package suggested but not available for checking: ‘graph’
209#>
210#> ❯ checking installed package size ... NOTE
211#> installed size is 17.9Mb
212#> sub-directories of 1Mb or more:
213#> R 1.4Mb
214#> help 1.2Mb
215#> libs 14.9Mb
216#>
217#> 0 errors ✔ | 0 warnings ✔ | 2 notes ✖
218#>
219#> $`r-oldrel-windows-ix86+x86_64`
220#> ── R CMD check results ──────────────────────────────── igraph 1.2.4.1 ────
221#> Duration: 0ms
222#>
223#> ❯ checking installed package size ... NOTE
224#> installed size is 16.7Mb
225#> sub-directories of 1Mb or more:
226#> R 1.4Mb
227#> help 1.1Mb
228#> libs 13.8Mb
229#>
230#> 0 errors ✔ | 0 warnings ✔ | 1 note ✖
231#>
232#> $`r-oldrel-osx-x86_64`
233#> ── R CMD check results ──────────────────────────────── igraph 1.2.4.1 ────
234#> Duration: 0ms
235#>
236#> ❯ checking installed package size ... NOTE
237#> installed size is 17.2Mb
238#> sub-directories of 1Mb or more:
239#> R 1.4Mb
240#> help 1.1Mb
241#> libs 14.2Mb
242#>
243#> 0 errors ✔ | 0 warnings ✔ | 1 note ✖
244#>
245#> attr(,"package")
246#> [1] "igraph"
247#> attr(,"class")
248#> [1] "rmcdcheck_cran_results"
249```
250
251### Comparing checks
252
253`compare_checks()` can compare two or more `rcmdcheck` objects.
254`compare_to_cran()` compares an `rcmdcheck` object to the CRAN checks of
255the same package:
256
257``` r
258chk <- rcmdcheck(quiet = TRUE)
259compare_to_cran(chk)
260#> ─ R CMD check comparison rcmdcheck 1.3.3 / 1.3.2 / 1.3.2 / 1.3.2 / 1.
261#> Status: OK
262#>
263#> ── Fixed
264#>
265#> ✔ checking tests ... [41s] ERROR
266#> ✔ checking tests ... [38s] ERROR
267```
268
269### Background processes
270
271`rcmdcheck_process` is a `processx::process` class, that can run `R CMD
272check` in the background. You can also use this to run multiple checks
273concurrently. `processx::process` methods can be used to poll or
274manipulate the check processes.
275
276``` r
277chkpx <- rcmdcheck_process$new()
278chkpx
279#> PROCESS 'R', running, pid 90876.
280```
281
282``` r
283chkpx$wait()
284chkpx$parse_results()
285#> ── R CMD check results ─────────────────────────────── rcmdcheck 1.3.3 ────
286#> Duration: 14.8s
287#>
288#> 0 errors ✔ | 0 warnings ✔ | 0 notes ✔
289```
290
291## License
292
293MIT © Mango Solutions, Gábor Csárdi, RStudio
294