setup.qmd

---
title: "System Setup"
---

## 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}
#| echo: false
#| message: true
cat("R version\n---\n")
writeLines(system2(c("R", "--version"), stdout = TRUE))
cat("\npandoc version\n---\n")
writeLines(system2(c("pandoc", "--version"), stdout = TRUE))
cat("\ngit version\n---\n")
writeLines(system2(c("git", "--version"), stdout = TRUE))
```


## R Packages

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

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

:::{.callout-tip}

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

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

You can find detailed instructions in [The Sandpaper Setup 
Guide](https://carpentries.github.io/sandpaper-docs/#infrastructure-r-packages-2), 
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](https://carpentries.r-universe.dev) API to get all
of the system dependencies. Here's how to do that via CURL:

```bash
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:

```bash
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](https://packagemanager.posit.co/__docs__/admin/serving-binaries/#binaries-r-configuration-linux)
and even then, it's kinda long. The gist is that you need to do two things:

1. set your HTTPUserAgent header to state your R version and platform
2. 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

```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:

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

:::


The {sandpaper} package comes with the [{usethis}](https://usethis.r-lib.org)
package embedded (though this may change in the future). In addition, you will
need the [{devtools}](https://devtools.r-lib.org) for development.

I would also _highly_ recommend the [{pandoc}](https://cderv.github.io/pandoc/)
package for managing pandoc versions (NOTE: this requires you to have a 
personal access token set up).

```{.r}
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:

``` r
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
```

<sup>Created on 2023-05-30 with [reprex v2.0.2](https://reprex.tidyverse.org)</sup>


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

1. open RStudio and switch to the project for the package you are working on
2. checkout a new branch for your feature/bug
3. **load package** via `devtools::load_all()` or <kbd>ctrl</kbd>+<kbd>shift</kbd>+<kbd>L</kbd> (
   use <kbd>cmd</kbd> on macOS) to load the package NAMESPACE
4. (if needed) **document** (either via `devtools::document()` or <kbd>ctrl</kbd>+<kbd>shift</kbd>+<kbd>D</kbd>)
5. **run tests** (either via `devtools::test()` or
   <kbd>ctrl</kbd>+<kbd>shift</kbd>+<kbd>T</kbd> 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]')`
6. **modify tests** for new functionality/bug fix
7. **add functionality/bug fix** and move to 3 unless you are ready to push
8. run check with `devtools::check()` or <kbd>ctrl</kbd>+<kbd>shift</kbd>+<kbd>E</kbd>