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
R package development toolchain
Several R packages
Git
GitHub account
GitHub linked to R

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

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:

Download and install XCode from the Mac AppStore: http://itunes.apple.com/us/app/xcode/id497799835?mt=12
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

In R, install the necessary packages by running:

install.packages(
  c("devtools", "roxygen2", "testthat", "rmarkdown", "pkgdown", "purrr")
)

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

devtools::has_devel()

Your system is ready to build packages!

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

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 for installation instructions. To install Git using Homebrew, run the following in the Terminal: brew install git

GitHub

I highly recommend the book Happy Git with R for advice on setting up and using Git with R (Bryan and Hester, n.d.).

Check link between R and GitHub

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

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 vignette in the usethis (Wickham et al. 2023) package has details on using PATs, but for now the following should suffice.

Create a PAT with:

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.

You may need to install the gitcreds package (Csárdi 2022).

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

usethis::git_sitrep()

── 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”:

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

Troubleshooting

If you are having issues with the setup please start a discussion on GitHub here.

References

Bryan, Jenny, and Jim Hester. n.d. “Happy Git and GitHub for the useR.” https://happygitwithr.com/.

Csárdi, Gábor. 2022. Gitcreds: Query ’Git’ Credentials from ’r’. https://CRAN.R-project.org/package=gitcreds.

Wickham, Hadley, Jennifer Bryan, Malcolm Barrett, and Andy Teucher. 2023. Usethis: Automate Package and Project Setup. https://CRAN.R-project.org/package=usethis.