setup.qmd

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

You will require the following software installed and configured for the workshop.
Please have this set up and ready to go **before** we start.

## Computing requirements

You will need:

-   A laptop computer with administrative privileges
-   [R and RStudio](#install-r-and-rstudio)
-   [R package development toolchain](#install-r-package-development-tools)
-   [Several R packages](#packages)
-   [Git]
-   [GitHub account](#github)
-   [GitHub linked to R](#check-link-between-r-and-github)

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

You will need:

-   R version \>= 4.2.0
-   RStudio \>= 2023.03.1

### Install R

Download and install R for your operating system from <https://cloud.r-project.org/>.

### Install R Studio

Download and install RStudio Desktop from <https://posit.co/download/rstudio-desktop/>.
This page should automatically offer you the version suitable for your operating system, but you can scroll down to find versions for all operating systems.

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

#### For Windows

Download and run the latest **Rtools** installer, `Rtools.exe`, from <https://cran.r-project.org/bin/windows/Rtools/>.

-   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**.
The easiest way is to open a Terminal window (Applications \> Utilities \> Terminal.app; or use the Terminal pane in RStudio) and type the following:

```
xcode-select --install
```

You will be prompted to confirm the install, and possibly enter your computer password.
Do so to complete the installation.

Alternatively you can:

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

#### For Linux

If you installed `r-base-dev` when installing R, you should have all you need to build packages from source.
If not, go back to <https://cloud.r-project.org/> and follow the instructions for your distribution (Ubuntu and Debian are likely the most common, and install it with `sudo apt-get install r-base-dev`).

## Install packages {#packages}

In R, install the necessary packages by running:

```{r}
#| eval: false
install.packages(
  c("devtools", "roxygen2", "testthat", "rmarkdown", "pkgdown", "purrr")
)
```

You can verify your system is set up for package development by running:

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

## Git

We will be demonstrating the use of Git and GitHub for tracking changes during package development, and sharing and collaborating on our package.

### Windows

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

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

-   Download and install from <https://git-scm.com/downloads>
-   Keep all the default settings. If asked about "Adjusting your PATH environment", make sure to select "Git from the command line and also from 3rd-party software".
-   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 in `C:/Users/[username]/AppData/Local/Programs/Git/`

### Mac

Check if Git is installed by running `which git` in the Terminal.
You should see something like `/usr/bin/git`, `/usr/local/bin/`, or `/opt/homebrew/bin/git`.

If you are 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`

::: aside
If you do lots of scientific computing and especially if you use command-line programs in the Terminal, we recommend using Homebrew.
See [brew.sh](https://brew.sh/) for installation instructions.
To install Git using Homebrew, run the following in the Terminal: `brew install git`
:::

## GitHub {#github}

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

I highly recommend the book [Happy Git with R](https://happygitwithr.com/) for advice on setting up and using Git with R [@bryan].

## Check link between R and GitHub {#check-link-between-r-and-github}

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

```{r}
#| eval: false
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 requires authentication with your GitHub account.
This is achieved by creating and securely storing a Personal Access Token (PAT).
The [Managing Git(Hub) Credentials](https://usethis.r-lib.org/articles/articles/git-credentials.html) vignette in the **`usethis`** [@usethis] package has details on using PATs, but for now the following should suffice.

Create a PAT with:

```{r}
#| eval: false
usethis::create_github_token()
```

-   Give the token a descriptive name, accept the default scopes, and click "Generate Token".
-   Copy the newly generated PAT to your clipboard.
-   Run `gitcreds::gitcreds_set()` in R and paste in your PAT when prompted.
-   After you close the PAT webpage, you won't be able to see your PAT again! You can store it somewhere secure, such as in a password manager.

### Caveat about storing PATs on Linux:

macOS and Windows both have built-in credential managers that will securely store your PAT, however the same does not exist in Linux.
[Happy Git with R has a section on options for storing your PAT on Linux](https://happygitwithr.com/https-pat#pat-doesnt-persist-on-linux).

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

You can now check your Git setup by asking for a "situation report":

```{r}
#| eval: false
usethis::git_sitrep()
```

::: cell-output
```
── Git global (user)
• Name: 'Andy Teucher'
• Email: 'andy.teucher@gmail.com'
• Global (user-level) gitignore file: '/Users/andy/.gitignore'
• Vaccinated: TRUE
ℹ Defaulting to 'https' Git protocol
• Default Git protocol: 'https'
• Default initial branch name: 'main'

── GitHub user
• Default GitHub host: 'https://github.com'
• Personal access token for 'https://github.com': '<discovered>'
• GitHub user: 'ateucher'
• Token scopes: 'gist, repo, user, workflow'
• Email(s): 'andy.teucher@gmail.com (primary)'
ℹ No active usethis project
```
:::

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

::: cell-output
```
Personal access token for 'https://github.com': '<discovered>'
```
:::

## Troubleshooting

If you are having issues with the setup please start a discussion on GitHub [here](https://github.com/ateucher/pkg-dev-dfo-2024-11/discussions).

### References

::: {#refs}
:::