README.md

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

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

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

## 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 directory, 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.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.  
* __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.inrae.fr/r-ecosystem/r-docker-images/blob/master/r-base-biosp/Dockerfile) for more informations.

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.  
More informations about .gitlab-ci.yml file configuration is available [here](https://gitlab.paca.inrae.fr/help/ci/yaml/README.md)  
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) only with commit is tagger.  

You need to set up this file for your project.

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

## Author

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

## License

See [LICENSE](LICENSE)