install.packages(
c("devtools", "roxygen2", "testthat", "rmarkdown", "pkgdown", "purrr")
)
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:
You can verify your system is set up for package development by running:
::has_devel() devtools
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. It is not strictly necessary for the workshop, but you will benefit greatly by using it.
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
Register a GitHub account at github.com.
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:
::use_git_config(
usethisuser.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:
::create_github_token() usethis
- 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”:
::git_sitrep() usethis
── 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>'