r-ci (original) (raw)
Easy and portable CI for R packages
This repository provides a script run.sh
for portable, flexible and lightweight Continuous Integration (CI) use at GitHub Actions, Travis, Azure Pipelines and Docker for local testing and use -- all shown below via real examples -- and likely others such as GitLab.
This script contains the following key functions which are typically all a user needs to call:
./run.sh bootstrap
Sets up the R environment, installs auxiliary packages such as testthat
or tinytest
.
./run.sh install_deps
Parses DESCRIPTION
and installs the required packages. install_all
is a (slightly heavier) alternative pulling not only dependencies but also suggested packages.
./run.sh run_tests
Builds the package tarball, and runs tests on it resulting in the overall CI test pass or fail.
Use with GitHub Actions
GitHub Actions is currently en vogue and popular due to fairly unlimited build resources, along with the stunning own-goal scored by the previous incumbent. Usage with run.sh
is easy. Just commit any file ending in .yml
or .yaml
in a directory .github/workflows
within your GitHub repo---and you are all set. No additional registration is needed.
Below is an example .github/workflows/ci.yaml
from thedang repository running a simple matrix build over Linux and macOS. Note that the matrix build for either can be turned off by placing a simple comment #
character in front as can be seen in many example YAML files. Also note that this version now uses a small GitHub Action for r-ci-setup instead of the standard curl
use shown in the other examples.
# Run CI for R using https://eddelbuettel.github.io/r-ci/
name: ci
on:
push:
pull_request:
env:
_R_CHECK_FORCE_SUGGESTS_: "false"
jobs:
ci:
strategy:
matrix:
include:
- {os: macOS-latest}
- {os: ubuntu-latest}
runs-on: ${{ matrix.os }}
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup
uses: eddelbuettel/github-actions/r-ci-setup@master
- name: Bootstrap
run: ./run.sh bootstrap
- name: Dependencies
run: ./run.sh install_all
- name: Test
run: ./run.sh run_tests
Use with Travis CI
Travis CI continues to be useful for those with remaining free credits, or a paid plan, so very basic use by Open Source project on Linux should be unaffected.
The following code examples is an actual .travis.yml
file, also from the dang repository used above. It runs a simple matrix build over macOS and Linux.
# Run CI for R using https://eddelbuettel.github.io/r-ci/
language: c
sudo: required
dist: focal
jobs:
include:
- name: linux
os: linux
- name: macOS
os: osx
## Two core settings: BSPM for binary installation where possible, and no
## installation of 'Suggests:' to keep things lighter
env:
global:
- _R_CHECK_FORCE_SUGGESTS_="false"
USE_BSPM="true"
before_install:
- curl -OLs https://eddelbuettel.github.io/r-ci/run.sh
- chmod 0755 run.sh
- ./run.sh bootstrap
install:
- ./run.sh install_all
script:
- ./run.sh run_tests
after_failure:
- ./run.sh dump_logs
#after_success:
# - ./run.sh coverage
notifications:
email:
on_success: change
on_failure: change
Use with Azure Pipelines
Azure Pipelines are an alternative worth considering as they also offer fairly generous usage credits. The example below is once again from the dang repository and is provided in its file .ci/ci.yaml
(but in its git repo on Azure; these pipelines can also access other repos for example at GitHub). As in the other examples, a matrix over Linux and macOS is setup
# Evolved from starter pipeline via r-azure-pipelines repo
trigger:
- master
variables:
- name: R_LIBS_USER
value: '$(Agent.BuildDirectory)/R/library'
- name: CRAN
value: 'https://cloud.r-project.org'
- name: _R_CHECK_FORCE_SUGGESTS_
value: false
- name: USE_BSPM
value: true
strategy:
matrix:
linux:
imageName: "ubuntu-latest"
macos:
imageName: "macos-latest"
maxParallel: 2
steps:
- bash: curl -OLs https://eddelbuettel.github.io/r-ci/run.sh
displayName: download
- bash: chmod 0755 run.sh
displayName: mode
- bash: ./run.sh bootstrap
displayName: bootstrap
- bash: ./run.sh install_deps
displayName: deps
- bash: ./run.sh run_tests
displayName: tests
Use with Docker
A key advantage of the simple run.sh
script is its versatility: just drop it into a Docker session to test a local repo!
The following short video, part of post #32: Portable Continuous Integration using r-ci in the r^4 series of r^4 posts, demonstrates Docker use for CI with the dang repository used above.
The commands used in the video are, essentially, just these:
# launch docker using 'r-bspm:20.04' from rocker
docker run --rm -ti -v ${PWD}:/work -w /work rocker/r-bspm:20.04
# fetch the script
wget https://eddelbuettel.github.io/r-ci/run.sh && chmod 0755 run.sh
# bootstrap
./run.sh bootstrap
# install just depends
./run.sh install_deps
# test (with just depends)
export _R_CHECK_FORCE_SUGGESTS_="false"; ./run.sh run_tests
# alternate: install all
./run.sh install_all
# test (with all)
export _R_CHECK_FORCE_SUGGESTS_="true"; ./run.sh run_tests