README.md 7.23 KB
Newer Older
Julien Veyssier's avatar
Julien Veyssier committed
1
2
3
4
5
6
R package checker
=================

# Introduction
---

Julien V's avatar
Julien V committed
7
R package checker is a tool to check if a new version of an R package (you might be developing) breaks any package which depends on it.
Julien Veyssier's avatar
Julien Veyssier committed
8
9
10
11
12
13
14

It works with a Bash script and an optional simple web interface. It runs R CMD CHECK on every package that depends on the package to test.

The execution of the R CMD CHECK can be parallelized by giving the corresponding option to the Bash script.

XVFB is used to perform graphical actions even without being under a running X server. JQuery is used to present check results.

Julien Veyssier's avatar
Julien Veyssier committed
15
There are basically two ways to use R package checker :
Julien Veyssier's avatar
Julien Veyssier committed
16

Julien Veyssier's avatar
Julien Veyssier committed
17
18
* Call the Bash script directly, watch the output and read .Rout files **OR** watch the real-time html output including all .Rout outputs
* Deploy the Php files and adapt values in config.php to manage test launch and results viewing in the basic web interface
Julien Veyssier's avatar
Julien Veyssier committed
19

Julien V's avatar
Julien V committed
20
21
**This project is developped within the context of [MBB platform](http://mbb.univ-montp2.fr) services.**

Julien Veyssier's avatar
Julien Veyssier committed
22
23
24
25
## Table of content
---
1. [Screenshots](#screenshots)
2. [Requirements](#requirements)
26
3. [Usage](#usage)
Julien Veyssier's avatar
Julien Veyssier committed
27
    1. [Direct Bash call](#direct-bash-call)
Julien Veyssier's avatar
Julien Veyssier committed
28
29
        * without --html
        * with --html
Julien Veyssier's avatar
Julien Veyssier committed
30
    2. [With the basic web interface](#with-the-basic-web-interface)
Julien Veyssier's avatar
Julien Veyssier committed
31
32
33

# Screenshots
---
Julien Veyssier's avatar
Julien Veyssier committed
34
**Bash script output :**
Julien Veyssier's avatar
Julien Veyssier committed
35

36
![screenshot bash](http://gitlab.mbb.univ-montp2.fr/julien/r-package-checker/raw/master/screenshots/rcheck_bash.png)
Julien Veyssier's avatar
Julien Veyssier committed
37

38
39
---

Julien Veyssier's avatar
Julien Veyssier committed
40
**Simple web interface example with 3 parallel processes :**
Julien Veyssier's avatar
Julien Veyssier committed
41

42
![screenshot web](http://gitlab.mbb.univ-montp2.fr/julien/r-package-checker/raw/master/screenshots/rcheck_web.png)
Julien Veyssier's avatar
Julien Veyssier committed
43

44
45
---

Julien Veyssier's avatar
Julien Veyssier committed
46
47
**Something went wrong in plotKML check procedure :**

48
![screenshot web problem](http://gitlab.mbb.univ-montp2.fr/julien/r-package-checker/raw/master/screenshots/rcheck_web_problem.png)
Julien Veyssier's avatar
Julien Veyssier committed
49
50
51

# Requirements
---
Julien Veyssier's avatar
Julien Veyssier committed
52
* MANDATORY any version of R (results will be different from one version to another as R CMD CHECK results differ depending on R version...)
Julien Veyssier's avatar
Julien Veyssier committed
53
54
* MANDATORY Xvfb
* OPTIONAL Php enabled web server
55
56
57
* OPTIONAL Java is probably needed by one of the packages depending on the package to check
* OPTIONAL Many libraries are probably needed to install dependencies of package to test. If an INSTALL or a CHECK fails, it is quite easy to determine if it is due to a missing lib and which lib it is.
* OPTIONAL configured mail server to be able to send mails (mail command is used by the bash script)
Julien Veyssier's avatar
Julien Veyssier committed
58
59
60
61

# Usage
---

62
63
64
65
Basically you can either check a specific package OR just give a list of packages to run R CMD CHECK on them.

The "-c" Bash script option allows you to directly give a list of packages to check. This option is not compatible with giving a package to test ("-p" option).

66
67
68
69
## Direct Bash call

This is the simple way to use the R package checker. The script prints current steps in stdout and all R output files in the output directory (-d|--dest DESTINATION_DIRECTORY). 

julien veyssier's avatar
julien veyssier committed
70
71
72
73
74
75
This tool was initially designed to take a package name as the main parameter and check everything that depends on it. This can be done with the -p parameter.

You can also give a list of packages to test (--checklist to give a list with versions and --checklistraw to give a simple list, last versions available are processed).

Another way to use R-package-checker is to pass a folder which contains packages tarballs with -t option. These packages are installed and checked.

76
77
78
Here are the script options :

```
julien veyssier's avatar
julien veyssier committed
79
rtest.sh [-p|--package NAME_OF_PACKAGE_TO_TEST || -c|--checklist CHECKLIST_FILE || --checklistraw -t|--tarfolder TAR_FOLDER_PATH] [-l|--libuser R_USER_LIB_VALUE] [-d|--dest DESTINATION_DIRECTORY] [-m|--mail MAIL_TO] [-u|--urlresult URL] [-r|--repo PACKAGE_TO_TEST_REPO] [-x|--xvfb XVFB-RUN PATH] [-n|--nbcores NBCORES] [-s|--skipinstall] [-h|--html] [--rpath PATH_TO_R_BINARY]
80

81
82
-p | --package NAME_OF_PACKAGE_TO_TEST : name of package to test (case sensible), all packages depending on this package are going to be checked by their R CMD CHECK
-c | --checklist CHECKLIST_FILE : file listing packages you want to check (each line should look like : PKG_NAME,PKG_VERSION,anything)
julien veyssier's avatar
julien veyssier committed
83
84
--checklistraw RAW_CHECKLIST_FILE : file listing packages you want to check (simply one package name per line)
-t | --tarfolder TAR_FOLDER_PATH : path to folder where tarballs of packages can be found. All of these packages are going to be \"R CMD CHECKED\"
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
-r | --repo PACKAGE_TO_TEST_REPO : repository of package you want to test (DEFAULT : R-CRAN)
-l | --libuser R_LIBS_USER : directory where packages depending on PACKAGE_TO_TEST are going to be installed (DEFAULT : R will choose it)
                             This directory can be used several times for several tests. Using same directory several times will save time.
                             This directory can exist or not. If not, it will be created
-d | --dest DESTINATION_DIRECTORY : result directory where HTML result and test files are produced (DEFAULT : ./check_PKGNAME_DATE)
-m | --mail MAIL_TO : email address for real time user information (DEFAULT : NO MAIL WILL BE SENT)
-u | --urlresult URL : if -m option was set, this http link to test results will be sent instead of a file path (DEFAULT : destination directory absolute path)
-x | --xvfb PATH : Specific path to xvfb-run script (DEFAULT : 'xvfb-run')
-n | --nbcores NBCORES : Number of cores for parallel executions of installations (Ncpu parameter) and number of simultaneous checks (DEFAULT : 1)
-s | --skipinstall : flag to skip the packages update/installation
-h | --html : generate html report in DESTINATION_DIRECTORY/index.html . Will download jquery in destination directory
```

### without --html

The script will not produce any fancy output. You'll have to find and read files to see the results of a check.

If there is a failure, check in the output/destination directory to find the corresponding .Rout file.

### with --html

Using the --html option, each step triggers the update of an html page located in the destination/output directory. This page contains the same information than the simple web interface but is static html which does not need Php and a webserver.

## With the basic web interface

julien veyssier's avatar
julien veyssier committed
110
111
The basic web interface launches rtest.sh with -p option to test all packages depending on a specific one.

112
113
114
115
To setup and use the web interface you need to :

* Copy view.php, start.php, config.php in a directory inside your web root
* Adjust variables in config.php :
Julien Veyssier's avatar
Julien Veyssier committed
116

Julien Veyssier's avatar
Julien Veyssier committed
117
```php
Julien Veyssier's avatar
Julien Veyssier committed
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
// name of the package to test
$package_to_test = "mypkg";

// path to rtest bash script
$rtest_location = "/home/user/rcheck/rtest.sh";

// where you want to install packages
$rlib_location = "/home/user/Rlib_test";

//$email_addr = "Emmanuel.Paradis@univ-montp2.fr";
$email_addr = "your@email.address";

// path to xvfb-run
$xvfbrun_location = "/home/user/xvfb-run";

// directory for all results directories
// (where to put check results)
$all_results_dir = "/home/user/rcheck_results/";

// repository to use to get last version of the package to test
$package_to_test_repo = "http://my.pkg.repo.org/";

// number of threads used for parallel checking
$nb_threads = 4;

// base URL where you host the web interface
// (will prefix start.php and view.php in links)
$base_url = "http://my.server.org/r-package-checker/";
Julien Veyssier's avatar
Julien Veyssier committed
146
```
Julien Veyssier's avatar
Julien Veyssier committed
147

148
* Visit http://your.server.org/rcheck/start.php to launch a check.
149
* Follow the link given by start.php to view.php to see the real time check progress.