Prerequisites

Author

Emma Rand and Ian Lyttle

You will need

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

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

The aim of devtools (Wickham et al. 2021) is to make package development easier by providing R functions that simplify and expedite common tasks. The R Packages (Wickham and Bryan 2020) book and the Building Tidy Tools workshop are based on a devtools workflow.

Install devtools:

install.packages("devtools")

After installing the R package development toolchain and devtools, you can verify your system is set up by running:

devtools::has_devel()
Your system is ready to build packages!

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:

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 for instructions

    • Use Homebrew: Run the following in the Terminal: brew install git

GitHub account

Register a GitHub account at 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 (Bryan and Hester, n.d.)

Check link between RStudio 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 will require authentication. Instead of typing in your username and password each time, use a PAT (personal access token)

Create a PAT with:

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:

gitcreds::gitcreds_set()

You may need to install gitcreds (Csárdi 2020).

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

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 vignette in the usethis (Wickham, Bryan, and Barrett 2022) package has all the details on PATs!

References

Bryan, Jenny, and Jim Hester. n.d. “Happy Git and GitHub for the useR.” https://happygitwithr.com/.
Csárdi, Gábor. 2020. “Gitcreds: Query ’Git’ Credentials from ’r’.” https://CRAN.R-project.org/package=gitcreds.
Wickham, Hadley, Jennifer Bryan, and Malcolm Barrett. 2022. “Usethis: Automate Package and Project Setup.” https://CRAN.R-project.org/package=usethis.
Wickham, Hadley, and Jenny Bryan. 2020. R Packages. The work-in-progress 2nd edition. Online. https://r-pkgs.org/index.html.
Wickham, Hadley, Jim Hester, Winston Chang, and Jennifer Bryan. 2021. “Devtools: Tools to Make Developing r Packages Easier.” https://CRAN.R-project.org/package=devtools.