README.md 4.12 KB
Newer Older
1
2
3
4
5
6
# R Packages Continuous Integration and Deployment (CI/CD) pipeline

This project hosts the repository of a Cookbook to manage a R package.

This template generate the documentation, build the package, run unit tests, check --as--cran, create package binaries for Windows and Mac OS...  

Jean-Francois Rey's avatar
Jean-Francois Rey committed
7
## A quick look at that : [useR2019 poster __R package development using GitLab CI/CD pipeline__ , JF Rey, L Houde, 2019](inst/userR2019-poster_JF_REY.pdf)
8

Jean-Francois Rey's avatar
Jean-Francois Rey committed
9
## Table of Contents 
10
11
12
13
14
15
16
17
18
19
20
21
22

- [Prerequisites](#prerequisites)
- [Files](#files)
- [Principle](#principle)
- [Set GitLab](#set-gitlab)
  - [The Project](#the-project-repository)
  - [The Runners](#the-runners)
- [The .gitlab-ci.yml file](#the-gitlab-ciyml-file)
- [Author](#author)
- [License](#license)

## Prerequisites

Jean-Francois Rey's avatar
Jean-Francois Rey committed
23
* Have to know: 
24
  * GitLab project management
Jean-Francois Rey's avatar
Jean-Francois Rey committed
25
  * R Packages  
26

Jean-Francois Rey's avatar
Jean-Francois Rey committed
27
28

* Should to know: 
29
30
31
32
33
34
35
36
  * GitLab Runners principle
  * GitLab CI/CD principle
  * R Package CRAN policy

## Branches

There are severals version of this project, depending if the package need compilations, vignettes... :

Jean-Francois Rey's avatar
Jean-Francois Rey committed
37
38
* simple R package : [master](/master)
* R package and c++ code source : [Rcpp](/rcpp)
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

## Files

* __[.gitlab-ci.yml](.gitlab-ci.yml)__ : file configuring the CI/CD pipeline
* R Package stuff : 
  * __[DESCRIPTION](DESCRIPTION)__ : the DESCRIPTION file update by roxygen2
  * __[NAMESPACE](NAMESPACE)__ : the NAMESPACE file generated by roxygen2
  * __[.Rbuildignore](.Rbuildignore)__ : regex for files to not include in package
  * __[R/](R)__ : R source code directory
  * __[man/](man)__ : documentation directory generated by roxygen2
  * __[test/](tests)__ : testthat direcotry, instruction for tests
  * __[inst/](inst)__ : directory of files to add in package at install
  * __[LICENSE](LICENSE)__ : the license file

## Principle

![GitLab CI/CD R Package pipeline](inst/GitLab_CI_CD_pipeline_RPackage.png)

* At push (and commit), in GitLab repository, the pipeline is trigger.
* GitLab use __[.gitlab-ci.yml](.gitlab-ci.yml)__ file to set the pipeline and run it on runners.
  * First it generates the package
  * Then it run tests
  * And finally build binaries packages

## set up GitLab

### The project repository

You can fork this project and use it as a template.

* Files in the project: [Files](#files)  

You need to enable __Pipelines__ in the project setting (_Setting -> General -> Visibility_)
and enable __Shared Runners__ (_Setting -> CI/CD -> Runners_).  

### The runners

Four Runners are availables for R Packaging in the shared runners :  
Jean-Francois Rey's avatar
Jean-Francois Rey committed
77
78
79
80
81
82
83
84
85
* __r-base-biosp__ : it's the current version of R for Linux OS (nightly build as docker image). [See here](https://gitlab.paca.inra.fr/r-ecosystem/r-docker-images) for more information.  
* __r-devel-biosp__ : it's the in development version of R (the next version) for Linux OS (nightly build as docker image). [See here](https://gitlab.paca.inra.fr/r-ecosystem/r-docker-images) for more information.  
* __R win10 binaries__ : a Windows 10 Virtual Machine with the current R and Rtools version.  
* __R Mac__ : a Mac OS High Sierra with the current R and Rtools version.  

Check _tags_ in [.gilab-ci.yml](.gitlab-ci.yml) file to enable the runner needed.  

This runners come with pre-installer R packages, R tools and system-libraries (bin and dev).  
See [here](https://gitlab.paca.inra.fr/r-ecosystem/r-docker-images/blob/master/r-base-biosp/Dockerfile) for more informations.
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

If you need you can add your own runner or ask GitLab administrator to set up a new one.  


## The .gitlab-ci.yml file

__[.gitlab-ci.yml](.gitlab-ci.yml)__ is the configuration file for the CI/CD pipeline.  
It set up three stages (create, tests and build) and severals jobs by stages.  

* create : update Description, NAMESPACE, and man (roxygen2). Create the package.  
* tests : Test the package (--as-cran)
* build : Build the package source tar.gz and binary version for MacOS (.tgz) and Windows (.zip)

You need to set up this file for your project.

Jean-Francois Rey's avatar
Jean-Francois Rey committed
101
Each jobs produce artifacts mainly in _build_ stage, they produce R packages delivery for Linux, Windows and Mac OS.  
102
103
104
105
106
107
108
109

## Author

[Jean-François Rey](https://jeff.biosp.org) \<jean-francois.rey at inra dot fr\>

## License

See [LICENSE](LICENSE)