2  System setup

2.1 Prepare your system

To get started, make sure you have the latest version of R (at least 4.4.2, which is the version being used to render this book), then run the following code to get the packages you’ll need:

install.packages(c("devtools", "roxygen2", "testthat", "knitr"))

Make sure you have a recent version of the RStudio integrated development environment (IDE). New versions are released regularly, so we recommend updating often to get access to the latest and greatest features.

Download the current version of RStudio Desktop here: https://posit.co/download/rstudio-desktop/. Most readers can use the free, open source version of RStudio Desktop.

2.2 devtools, usethis, and you

“I am large, I contain multitudes.”

— Walt Whitman, Song of Myself

As mentioned in Section 1, devtools is a ‘meta-package’, encompassing and exposing functionality maintained in several smaller packages1. For example, devtools might provide a wrapper function in order to set user-friendly defaults, introduce helpful interactive behaviour, or to combine functionality from multiple sub-packages. In some cases it simply re-exports a function from another package to make it easily available when devtools is attached.

What’s our recommended approach to using devtools and its constituent packages? It varies, depending on your intention:

  • If you are using the functions interactively to help you develop your package, you should think of devtools as the provider of your favorite functions for package development. In this case you should attach devtools with library(devtools) and call the functions without qualification (e.g., load_all()).
  • If you are using functions from devtools and friends within the package code you are writing, you should NOT depend on devtools, but should instead access functions via the package that is their primary home.
    • devtools should rarely appear in the role of pkg in a qualified call of the form pkg::fcn(). Instead, pkg should be the package where fcn() is defined. For example, if you are creating a function in your package in which you need to query the state of the user’s R session, use sessioninfo::session_info() in your package instead of devtools::session_info().
  • If you find bugs, try to report them on the package that is a function’s primary home. The help for devtools::fcn() usually states when devtools is re-exporting a function from another package.

The usethis package is the one constituent package that more people may be aware of and that they may use directly. It holds the functions that act on the files and folders in an R project, most especially for any project that is also an R package. devtools makes it easy to access usethis functions interactively, as when you call library(devtools), usethis is also attached. Then you can use any function in usethis without qualification, e.g., just call use_testthat(). If you choose to specify the namespace, such as when working in a more programmatic style, then make sure you qualify the call with usethis, e.g., usethis::use_testthat().

2.2.1 Personal startup configuration

You can attach devtools like so:

But it soon grows aggravating to repeatedly attach devtools in every R session. Therefore, we strongly recommend attaching2 devtools in your .Rprofile startup file, like so:

For convenience, the function use_devtools() creates .Rprofile, if needed, opens it for editing, and puts the necessary lines of code on the clipboard and the screen.

Warning

In general, it’s a bad idea to attach packages in .Rprofile, as it invites you to create R scripts that don’t reflect all of their dependencies via explicit calls to library(foo). But devtools is a workflow package that smooths the process of package development and is, therefore, unlikely to get baked into any analysis scripts. Note how we still take care to only attach in interactive sessions.

usethis consults certain options when, for example, creating R packages de novo. This allows you to specify personal defaults for yourself as a package maintainer or for your preferred license. Here’s an example of a code snippet that could go in .Rprofile:

options(
  "Authors@R" = utils::person(
    "Jane", "Doe",
    email = "jane@example.com",
    role = c("aut", "cre"),
    comment = c(ORCID = "0000-1111-2222-3333")
  ),
  License = "MIT + file LICENSE"
)

The following code shows how to install the development versions of devtools and usethis. At times, this book may describe new features that are in the development version of devtools and related packages, but that haven’t been released yet.

devtools::install_github("r-lib/devtools")
devtools::install_github("r-lib/usethis")

# or, alternatively
pak::pak("r-lib/devtools")
pak::pak("r-lib/usethis")

2.3 R build toolchain

To be fully capable of building R packages from source, you’ll also need a compiler and a few other command line tools. This may not be strictly necessary until you want to build packages containing C or C++ code. Especially if you are using RStudio, you can set this aside for now. The IDE will alert you and provide support once you try to do something that requires you to setup your development environment. Read on for advice on doing this yourself.

2.3.1 Windows

On Windows the collection of tools needed for building packages from source is called Rtools.

Rtools is NOT an R package. It is NOT installed with install.packages(). Instead, download it from https://cran.r-project.org/bin/windows/Rtools/ and run the installer.

During the Rtools installation you may see a window asking you to “Select Additional Tasks”.

  • Do not select the box for “Edit the system PATH”. devtools and RStudio should put Rtools on the PATH automatically when it is needed.
  • Do select the box for “Save version information to registry”. It should be selected by default.

2.3.2 macOS

You need to install the Xcode command line tools, which requires that you register as an Apple developer. Don’t worry, this is free for an individual who only wishes to install apps, such as Xcode command line tools. Enrolling in the paid developer program is only necessary for those who want distribute apps, access beta software, and integrate with capabilities such as Siri, Apple Pay, and iCloud.

Then, in the shell, do:

xcode-select --install

Alternatively, you can install the current release of full Xcode from the Mac App Store. This includes a very great deal that you do not need, but it offers the advantage of App Store convenience.

2.3.3 Linux

Make sure you’ve installed not only R, but also the R development tools. For example, on Ubuntu (and Debian) you need to install the r-base-dev package with:

sudo apt install r-base-dev

On Fedora and RedHat, the development tools (called R-core-devel) will be installed automatically when you install with R with sudo dnf install R.

2.4 Verify system prep

You can request a “(package) development situation report” with devtools::dev_sitrep():

devtools::dev_sitrep()
#> ── R ───────────────────────────────────────────────────────────────────────
#> • version: 4.1.2
#> • path: '/Library/Frameworks/R.framework/Versions/4.1/Resources/'
#> ── RStudio ─────────────────────────────────────────────────────────────────
#> • version: 2022.2.0.443
#> ── devtools ────────────────────────────────────────────────────────────────
#> • version: 2.4.3.9000
#> • devtools or its dependencies out of date:
#>   'gitcreds', 'gh'
#>   Update them with `devtools::update_packages("devtools")`
#> ── dev package ─────────────────────────────────────────────────────────────
#> • package: 'rpkgs'
#> • path: '/Users/jenny/rrr/r-pkgs/'
#> • rpkgs dependencies out of date:
#>   'gitcreds', 'generics', 'tidyselect', 'dplyr', 'tidyr', 'broom', 'gh'
#>  Update them with `devtools::install_dev_deps()`

If this reveals that certain tools or packages are missing or out-of-date, you are encouraged to update them.

  1. At the time of writing, devtools exposes functionality from remotes, pkgbuild, pkgload, rcmdcheck, revdepcheck, sessioninfo, usethis, testthat, and roxygen2↩︎

  2. This is one of the few cases where we recommend using require() over library(). library() will fail with an error if it is unable to attach the package, and thus abort the execution of your .Rprofile. If require() fails to attach the package it will emit a warning but will allow the remainder of your .Rprofile to execute. This is discussed further in Section 10.4.↩︎