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

[useR2019 poster __R package development using GitLab CI/CD pipeline__ , JF Rey, L Houde, 2019](inst/userR2019-poster_JF_REY.pdf)

** Table of Contents** 

- [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

* Have to know:
  * GitLab project management
  * R Packages

* Should to know:
  * 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... :

* simple R package : [master](tree/master)
* R package and c++ code source : [Rcpp](tree/rcpp)

## 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 :  
* 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.  

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.

Each jobs produces artifacts mainly in _build_ stage it produces R packages delivery for Linux, Windows and Mac OS.  

## Author

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

## License

See [LICENSE](LICENSE)