README.md 5.33 KB
Newer Older
Julien Veyssier's avatar
Julien Veyssier committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
R package checker
=================

# Introduction
---

R package checker is a tool to check if a new version of an R package (you might be developing) brakes any package which depends on it.

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.

There is basically three ways to use R package checker :

* Call the Bash script directly and watch the output
* Call the Bash script directly with the --html option to produce a real-time html output
* Setup the Php files and adapt values in config.php to manage test launch and results viewing.

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

# Screenshots
---
Bash script output :
Julien Veyssier's avatar
Julien Veyssier committed
34
35
36
37
38
39
40
41

![screenshot bash](https://gitlab.com/eneiluj/r-package-checker/raw/master/screenshots/rcheck_bash.png)

Simple web interface examples :

![screenshot web](https://gitlab.com/eneiluj/r-package-checker/raw/master/screenshots/rcheck_web.png)

![screenshot web problem](https://gitlab.com/eneiluj/r-package-checker/raw/master/screenshots/rcheck_web_problem.png)
Julien Veyssier's avatar
Julien Veyssier committed
42
43
44
45
46
47
48

# Requirements
---
* MANDATORY any version of R (results will be different from one version to another)
* MANDATORY Xvfb
* OPTIONAL Php enabled web server
* Java is probably needed by one of the packages depending on the package to check
49
* 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.
Julien Veyssier's avatar
Julien Veyssier committed
50
51
52
53

# Usage
---

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
## 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). 

Here are the script options :

```
rtest.sh PACKAGE_TO_TEST [-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]

PACKAGE_TO_TEST : package to test
-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

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
93
```php
Julien Veyssier's avatar
Julien Veyssier committed
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
// 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
122
```
123
124
* Visit http://your.server.org/rcheck/start.php to launch a check.
* Follow the link given by start.php to view.php to see the real time check progress.