2 System Setup

2.1 Software Tools

Development of Workbench components requires the same toolchain for working on lessons:

R
pandoc
Git

It is recommended to have the latest versions of R and pandoc available. You need at least git 2.28 for security purposes.

R version
---

R version 4.4.2 (2024-10-31) -- "Pile of Leaves"
Copyright (C) 2024 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under the terms of the
GNU General Public License versions 2 or 3.
For more information about these matters see
https://www.gnu.org/licenses/.


pandoc version
---

pandoc 3.1.11
Features: +server +lua
Scripting engine: Lua 5.4
User data directory: /home/runner/.local/share/pandoc
Copyright (C) 2006-2023 John MacFarlane. Web: https://pandoc.org
This is free software; see the source for copying conditions. There is no
warranty, not even for merchantability or fitness for a particular purpose.


git version
---

git version 2.47.1

2.2 R Packages

Once you have these installed, make sure to install ALL of the dependencies for the workbench:

install.packages(c("sandpaper", "pegboard", "varnish", "tinkr"),
  dependencies = TRUE,
  repos = c(getOption("repos"), "https://carpentries.r-universe.dev"))

Working on Linux?

If you are on Linux, you will run into a couple of fun aspects that you may already be familiar with, especially if you have ever tried to install bioinformatic software:

having to also install some extra C libraries (which are akin to R packages, but for C), such as the xslt library.
having to build all packages from source

You can find detailed instructions in The Sandpaper Setup Guide, but the relevant commands are below.

System Dependencies

Here is the gist for Ubuntu Users to get system dependencies set up. Use The Carpentries R-Universe API to get all of the system dependencies. Here’s how to do that via CURL:

curl https://carpentries.r-universe.dev/stats/sysdeps 2> /dev/null | jq -r '.headers[0] | select(. != null)'

This list can be sent to apt-get install to install everything:

sudo apt-get install -y \
  $(curl https://carpentries.r-universe.dev/stats/sysdeps 2> /dev/null | jq -r '.headers[0] | select(. != null)') 2> /dev/null \
  || echo "Not on Ubuntu"

Binary Packages

To get binary packages for your system, I will admit that it’s slightly confusing because they bury the instructions for registering your system to use binaries in the admin pages and even then, it’s kinda long. The gist is that you need to do two things:

set your HTTPUserAgent header to state your R version and platform
add the packagemanager CRAN-like repository to R’s options:

Here’s a script that you can copy and paste into ~/.Rprofile which will be run every time you start R

local({
  # Set the default HTTP user agent to get pre-built binary packages
  RV <- getRversion()
  OS <- paste(RV, R.version["platform"], R.version["arch"], R.version["os"])
  codename <- sub("Codename.\t", "", system2("lsb_release", "-c", stdout = TRUE))
  options(HTTPUserAgent = sprintf("R/%s R (%s)", RV, OS))

  # register the repositories for The Carpentries and CRAN
  options(repos = c(
    carpentries = "https://carpentries.r-universe.dev/",
    CRAN = paste0("https://packagemanager.posit.co/all/__linux__/", codename, "/latest")
  ))
})

When you have this set up, you can then install the workbench packages:

# Install The Workbench and dependencies
install.packages(c("sandpaper", "varnish", "pegboard", "tinkr"), dep = TRUE)

The {sandpaper} package comes with the {usethis} package embedded (though this may change in the future). In addition, you will need the {devtools} for development.

I would also highly recommend the {pandoc} package for managing pandoc versions (NOTE: this requires you to have a personal access token set up).

install.packages("devtools")
install.packages("pandoc")

Once you have devtools, be sure to run devtools::dev_sitrep() and usethis::git_sitrep() to make sure you have the tools to build The Workbench:

devtools::dev_sitrep()
#> ── R ───────────────────────────────────────────────────────────────────────────
#> • version: 4.3.0
#> • path: '/usr/lib/R/'
#> ── devtools ────────────────────────────────────────────────────────────────────
#> • version: 2.4.5
#> ── dev package ─────────────────────────────────────────────────────────────────
#> • package: <unset>
#> • path: <unset>
#> ✔ All checks passed

usethis::git_sitrep()
#> Git config (global)
#> • Name: 'Zhian N. Kamvar'
#> • Email: 'zkamvar@gmail.com'
#> • Global (user-level) gitignore file: <unset>
#> • Vaccinated: FALSE
#> ℹ See `?git_vaccinate` to learn more
#> ℹ Defaulting to 'https' Git protocol
#> • Default Git protocol: 'https'
#> • Default initial branch name: 'main'
#> GitHub
#> • Default GitHub host: 'https://github.com'
#> • Personal access token for 'https://github.com': '<discovered>'
#> • GitHub user: 'zkamvar'
#> • Token scopes: 'gist, repo, user, workflow'
#> • Email(s): 'zkamvar@gmail.com (primary)', ...
#> Git repo for current project
#> ℹ No active usethis project

^{Created on 2023-05-30 with reprex v2.0.2}

2.3 Development Workflow

This development workflow is known as Test Driven Development in which a test is written before things work. This way, we can confirm that a bug is fixed once it passes the tests and we have confidence that it will not fail again.

open RStudio and switch to the project for the package you are working on
checkout a new branch for your feature/bug
load package via devtools::load_all() or ctrl+shift+L ( use cmd on macOS) to load the package NAMESPACE
(if needed) document (either via devtools::document() or ctrl+shift+D)
run tests (either via devtools::test() or ctrl+shift+T to run the entire test suite OR to test a single file, use the “run tests” button in a test file or run testthat::test_local(filter = '[FILE SLUG]')
modify tests for new functionality/bug fix
add functionality/bug fix and move to 3 unless you are ready to push
run check with devtools::check() or ctrl+shift+E