README.md 4.71 KB
Newer Older
Jean-Francois Rey's avatar
Jean-Francois Rey committed
1
[![pipeline status](https://gitlab.paca.inrae.fr/r-ecosystem/cookbooks/r-packages-ci-cd/badges/master/pipeline.svg)](https://gitlab.paca.inrae.fr/r-ecosystem/cookbooks/r-packages-ci-cd/commits/master)
Jean-Francois Rey's avatar
Jean-Francois Rey committed
2

3
4
5
6
7
8
# 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
9
## 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)
10

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

- [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
25
* Have to know: 
26
  * GitLab project management
Jean-Francois Rey's avatar
Jean-Francois Rey committed
27
  * R Packages  
28

Jean-Francois Rey's avatar
Jean-Francois Rey committed
29
30

* Should to know: 
31
32
33
34
35
36
37
38
  * 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
39
40
* simple R package : [master](../tree/master)
* R package and c++ code source : [Rcpp](../tree/rcpp)
41
42
43
44
45
46
47
48
49
50

## 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
51
  * __[test/](tests)__ : testthat directory, instruction for tests
52
53
54
55
56
57
58
59
60
61
62
63
64
  * __[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

65
## Set up GitLab
66
67
68
69
70
71
72

### The project repository

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

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

Jean-Francois Rey's avatar
Jean-Francois Rey committed
73
You need to enable __Pipelines__ in the project setting (_Setting -> General -> Visibility_)  
74
75
76
77
78
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
79
80
* __r-base-biosp__ : it's the current version of R for Linux OS (nightly build as docker image). [See here](https://gitlab.paca.inrae.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.inrae.fr/r-ecosystem/r-docker-images) for more information.  
Jean-Francois Rey's avatar
Jean-Francois Rey committed
81
82
83
* __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.  

84
85
86
Check _tags_ in [.gilab-ci.yml](.gitlab-ci.yml) file to enable the runner needed. 
_R_ tags is for R version 3.6.2 and _R4_ tags is for R verison >= 4.0.0 .  
> With R version 4.0.0 the Windows toolschain have change and it's no more needed to download binaries of dependendcies as systems libraries.  
Jean-Francois Rey's avatar
Jean-Francois Rey committed
87
88

This runners come with pre-installer R packages, R tools and system-libraries (bin and dev).  
Jean-Francois Rey's avatar
Jean-Francois Rey committed
89
See [here](https://gitlab.paca.inrae.fr/r-ecosystem/r-docker-images/blob/master/r-base-biosp/Dockerfile) for more informations.
90

91
If you need, you can add your own runner or ask GitLab administrator to set up a new one.  
92
93
94
95
96


## The .gitlab-ci.yml file

__[.gitlab-ci.yml](.gitlab-ci.yml)__ is the configuration file for the CI/CD pipeline.  
Jean-Francois Rey's avatar
Jean-Francois Rey committed
97
More informations about .gitlab-ci.yml file configuration is available [here](https://gitlab.paca.inrae.fr/help/ci/yaml/README.md)  
98
99
100
101
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)
102
* build : Build the package source tar.gz and binary version for MacOS (.tgz) and Windows (.zip) only with commit is tagger.  
103
104
105

You need to set up this file for your project.

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

## Author

Jean-Francois Rey's avatar
Jean-Francois Rey committed
110
[Jean-François Rey](https://jeff.biosp.org) \<jean-francois.rey at inrae dot fr\>
111
112
113
114

## License

See [LICENSE](LICENSE)