pre-reqs.qmd

---
title: "Prerequisites"
author: "Emma Rand and Ian Lyttle"
format: html
execute:
  echo: true
  eval: false
bibliography: materials/references.bib
---

You will need

-   [R and RStudio](#install-r-and-rstudio)
-   [R package development toolchain](#install-r-package-development-toolchain): Rtools(windows) or XCode (mac) or r-base-dev
-   To [install the **`devtools`** and **`btt22`** packages](#packages)
-   [Git]
-   [GitHub account]
-   [GitHub to be linked to RStudio](#check-link-between-rstudio-and-github)

## Install R and RStudio {#install-r-and-rstudio}

You will need:

-   R version >= 4.1
-   RStudio  >= 2022.02.1

### Installing R

Download the pre-compiled binary for your OS from <https://cloud.r-project.org/> and install.

#### For Windows

Click "Download R for Windows", then "base", then "Download R #.#.# for Windows". This will download an `.exe` file; once downloaded, open to start the installation. If you do not have administrator rights, the installer will default to install in your Documents folder - if you prefer, you can change the location to another folder that you have write access to.

#### For Mac

Click "Download R for (Mac) OS X", then "R-#.#.#.pkg" to download the installer. Run the installer to complete installation.

#### For Linux

Click "Download R for Linux". Instructions on installing are given for Debian, Redhat, Suse and Ubuntu distributions. Where there is a choice, install both `r-base` and `r-base-dev`.

### Installing R Studio

Downloads are available from <https://www.rstudio.com/products/rstudio/download/> (scroll to the end of the page to see the downloads). You want RStudio Desktop (Open Source License).

#### For Windows with no admin rights

Download the `.zip` source archive under "Zip/Tarballs". Extract the files to a folder where you have write access, e.g. `C:\Users\username\RStudio`. In this folder, open the `bin` directory and find the RStudio program: it is named `rstudio.exe`, but the file extension will typically be hidden, so look for `rstudio`. Right-click this executable to create a desktop shortcut. Double-click the executable or use the shortcut to open.

#### For all other operating systems

Download the relevant installer for your OS listed under "Installers for Supported Platforms". Run the installer to complete installation.

## Install R package development toolchain {#install-r-package-development-toolchain}

#### For Windows with no admin rights

Download the latest (recommended) Rtools installer, `Rtools.exe`, from <https://cran.r-project.org/bin/windows/Rtools/>. Run the installer keeping the default settings.

#### For Windows with admin rights

Download the latest (recommended) Rtools installer, `Rtools.exe`, from <https://cran.r-project.org/bin/windows/Rtools/>. Run the installer making the following selections: keep the default settings for the installation location and components to install; check the box to add rtools to the system PATH.

#### For Mac

Install XCode. Either:

1.  Download and install XCode from the Mac AppStore: <http://itunes.apple.com/us/app/xcode/id497799835?mt=12>
2.  Within XCode go to Preferences : Downloads and install the Command Line Tools

Or for a smaller download size:

1.  Register as an Apple Developer (free) here: <https://developer.apple.com/programs/register/>
2.  Download the Command Line Tools for XCode appropriate for the version of OS X you are running from here: <https://developer.apple.com/downloads/>

#### For Linux

If you installed `r-base-dev`, when installing R, you should have all you need to build packages from source. Otherwise return to the instructions for installing R for your distribution and follow the instructions there to install the additional tools.

## Install the **`devtools`** and **`btt22`** packages {#packages}

The aim of **`devtools`** [@devtools] is to make package development easier by providing R functions that simplify and expedite common tasks. The [R Packages](https://r-pkgs.org/) [@wickham2020a] book and the Building Tidy Tools workshop are based on a **`devtools`** workflow.

Install **`devtools`**:

```{r}
install.packages("devtools")
```

After installing the [R package development toolchain](#install-r-package-development-toolchain) and **`devtools`**, you can verify your system is set up by running:

```{r}
#| eval: true
devtools::has_devel()
```

The central project for the Building Tidy Tools 2022 workshop is you will build a package called **`ussie`**, and populate it with functions. The goal of **`btt22`** is to help you build the **`ussie`** package. Its two main purposes are:

-   installing **`btt22`** means you will have all the packages you need for the workshop and,
-   **`btt22`** has functions that allow you to template code for workshop exercises and to reset the state of **`ussie`** to a particular point in the workshop if things go wrong.

*We recommend you install **`btt22`** no sooner than a week before the workshop.*

Install **`btt22`** from GitHub:

```{r}
devtools::install_github("rstudio-conf-2022/btt22")
```

## Git

### Windows

Check if Git is installed by running `which git` in the **Terminal**

If `which git` didn't find Git installed:

-   Download and install from <https://git-scm.com/downloads>
-   Keep all the default settings
    -   If the installer hangs with the progress bar at 100%, close the installer with Task Manager (press Ctrl + Alt + Delete; select Task Manager; find Git for Windows installer and close).
-   Open RStudio. In the menus go to Tools \> Global Options \> Git/SVN.
-   Check RStudio has found git under "Git executable:"
    -   You may need to click Browse and find the git executable.

    -   It may be under C:\\Users\\username\\AppData\\Local\\Programs\\Git\\ - remember if file extensions are hidden it will show as git rather than git.exe. Restart RStudio before trying to use git.

### Mac

Check if Git is installed by running `which git` in the **Terminal**

If asked to install the Xcode command line tools, say yes!

If `which git` didn't find Git installed, and if you weren't prompted to install it, run the following in the **Terminal**: `xcode-select --install`

#### Other options for installing Git on a Mac

-   Recommended if you don't want to use the Terminal:
    -   Download and install from <https://git-scm.com/downloads>

    -   If you're developing version controlled packages, you should get to using the Terminal
-   Recommended if you do lots of scientific computing and using software that needs to be installed and updated regularly:
    -   You might first need to install Homebrew if this is your first time using it, see [brew.sh](https://brew.sh/) for instructions

    -   Use Homebrew: Run the following in the Terminal: `brew install git`

## GitHub account

Register a GitHub account at [github.com](https://github.com/).

-   Incorporate your actual name!
-   Reuse your username from other contexts.
-   Pick a username you will be comfortable revealing to your future boss.
-   Shorter is better than longer.
-   Be as unique as possible in as few characters as possible.
-   Make it timeless.
-   Avoid words laden with special meaning in programming.
-   Use all lower case letters.

Advice and more information from [Happy Git with R](https://happygitwithr.com/) [@bryan]

## Check link between RStudio and GitHub {#check-link-between-rstudio-and-github}

Configure your `user.name` and `user.email` for git in RStudio with:

```{r}

usethis::use_git_config(
  user.name = "Jane Doe",          # actual first and last name
  user.email = "jane@example.com"  # email associated with GitHub account
  )
```

Communicating with GitHub will require authentication. Instead of typing in your username and password each time, use a PAT (personal access token)

Create a PAT with:

```{r}
usethis::create_github_token()
```

-   Give the token a descriptive name
-   Copy and also store this token somewhere (you won't be able to see it again!)

Now put your PAT into the Git credential store with:

```{r}
gitcreds::gitcreds_set()
```

::: aside
You may need to install **`gitcreds`** [@gitcreds].
:::

You can check your set up by asking for a "situation report":

```{r}
usethis::git_sitrep()
```

The output for this function shows information about the link between RStudio and GitHub, but not all of it is relevant now. It is essential to check whether your name and email are correct and the PAT is showing as "discovered":

    Personal access token for 'https://github.com': '<discovered>'

### Personal Access Token

The [Managing Git(Hub) Credentials](https://usethis.r-lib.org/articles/articles/git-credentials.html) vignette in the **`usethis`** [@usethis] package has all the details on PATs!