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

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
73
74
75
76
77
78

### 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
79
80
81
82
83
84
85
86
87
* __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.
88

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


## 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)
99
* build : Build the package source tar.gz and binary version for MacOS (.tgz) and Windows (.zip) only with commit is tagger.  
100
101
102

You need to set up this file for your project.

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

## Author

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

## License

See [LICENSE](LICENSE)