Using {circle} with {tic}

Enabling the repository on Circle CI

The first step is to enable/register your repository on Circle CI. Todo this,enable_repo() can be called. Assuming you alreadyhave an account on Circle CI (authenticating with GitHub isrecommended), this “follows” your repository on Circle CI so that buildscan be triggered by pushes to the repository.

Creating the Circle CI YAML configuration file

Next, a YAML file (.circleci/config.yml) needs to becreated which lists the tasks which should be executed on Circle CIafter a commit to the repository.

This is where theropensci/tic package comesinto play which provides YAML templates for Circle CI. There are twoways to get the template via {tic}:

• by going through the chattytic::use_tic() wizard whichasks some questions related to configuration and then writes/initiatesmultiple CI providers (based on the choices made). This is a good choiceif you want to understand in greater detail what {tic} is doing.
• by callingtic::use_circle_yml() which (by default)writes a Circle CI configuration file that checks the R package via{rcmdcheck} and deploys a {pkgdown} site to thegh-pagesbranch of the repository.

In addition some files will be added to.Rbuildignoreand.gitignore. Also the CI-agnostictic.Rfile will be created which lists the steps/macros that will be executedin a domain-specific language syntax. Please have a look atthe introductionvignette of the tic package to understand the role oftic.R in more detail.

Enabling deployment from builds

To be able to push to the GitHub repository some setup work isrequired. Deployment is often done by creating a SSH key pair of whichone part is stored on Circle CI and the other one on GitHub. To preventhaving to add the SSH key parts to Circle CI and GitHub manually,use_circle_deploy() can be called to do all of thisprogrammatically. Seethesection on “Deployment” in the “Getting Started” vignette for moredetails on this process.

Understanding the YAML file

The config file of this repo at.circleci/config.ymlhas also been set up with {tic}.

Let’s walk through it step by step to understand what ishappening:

jobs:r-release:    # r-release-envenvironment:docker:-image: rocker/versesteps:- checkout

In this part we specify to use therocker/verse dockerimage as the base for the job. The first step is “checkout” which meansthe repository is cloned.

      # create a unique env var for the cache. Unfortunately normal env vars      # are not picked up by the cache, therefore this workaround is needed.      # See https://discuss.circleci.com/t/cannot-use-circle-yml-environment-variables-in-cache-keys/10994/7-run: echo "$(date '+%d-%m')-r-release" > /tmp/_tmp_file-restore_cache:key: R-package-library-{{ checksum "/tmp/_tmp_file" }}

Next, an action related to caching R packages is initiated. Thissaves some time in the future because once all R packages which thepackage needs have been installed once for a given day, they will bere-used in future builds of the day without having to be installedagain.

      # install deps and check pkg ----------------------------------------------run:name:"[r-release] Install dependencies"          command:|            sudo apt update && sudo apt install -y ccache libgit2-dev libharfbuzz-dev libfribidi-dev            echo -e 'options(Ncpus = 4, repos = structure(c(CRAN = "https://cloud.r-project.org/")))' > $HOME/.Rprofile            R -q -e 'install.packages("remotes")'            R -q -e 'if (getRversion() < "3.2" && !requireNamespace("curl")) install.packages("curl")'            R -q -e 'remotes::install_github("ropensci/tic", upgrade = "always"); print(tic::dsl_load()); tic::prepare_all_stages()'            R -q -e 'tic::before_install()'            R -q -e 'tic::install()'

Next, the {tic} package is installed and certainticsteps are run. These take care of installing the dependencies of theR package to be checked and prepare the environment of other subsequentsteps.

-run:name:"[r-release] R CMD Check"no_output_timeout: 60m          command:|            R -q -e 'tic::before_script()'            R -q -e 'tic::script()'

This step checks the package for CRAN eligibility by making use ofrcmdcheck::rcmdcheck() inside thetic::script() call.

      # save R pkg cache --------------------------------------------------------save_cache:key: R-package-library-{{ checksum "/tmp/_tmp_file" }}paths:- /usr/local/lib/R/site-library

Finally, the R package which was initiated earlier is saved.

Thedeploy: step following next is in most partsexecuting the same steps as just shown. In the end however,tic::deploy() is called which internally will build a{pkgdown} site of the package and then deploy this site to thegh-pages branch of the repository.

The first build

After.circleci/config.yml andtic.R havebeen commited and pushed, the first build will start on Circle CI.

Calling one ofget_pipelines(),get_workflows() orget_jobs() should nowreturn some content.

In addition, you can directly browse the builds in the Circle CI webinterface by callingusethis::browse_circleci().