Chapter 3 System setup

3.1 Prepare your system

To get started, make sure you have the latest version of R (at least 4.0.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). In fact, consider using the preview version and updating regularly. Compared to the official released version, the preview gives you access to the latest and greatest features and only slightly increases your chances of finding a bug. It is distinct from the more volatile daily build.

3.2 devtools, usethis, and you

“I am large, I contain multitudes.”

— Walt Whitman, Song of Myself

After 7 years of development, devtools had grown into a rather unwieldy package, making maintenance difficult. Version 2.0.0, released in late 2018, marked the conscious uncoupling of devtools, with most functionality moving into seven smaller packages. Through various means, devtools continues to expose all its usual functionality, although it is mostly maintained elsewhere. 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.

What’s our recommended approach to devtools and its constituent packages? It varies, depending on whether you’re working in useR or developeR mode:

  • For interactive use, useRs should attach devtools and think of it as the provider of your favorite functions for package development.
  • For programmatic use, such as inside another package, developeRs 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 foo in a qualified call of the form foo::fcn(). Instead, foo should be the package where fcn() is defined.
    • An exception to this is that we continue to feature devtools::install_github() as the way to install the development version of a package in its README, even though install_github() actually lives in the remotes package. That’s because this piece of advice pertains to interactive use, where we prefer to emphasize devtools.
  • Try to report bugs on the package that is a function’s primary home.

Example of how to simulate installing and loading a package, during interactive development:

library(devtools)
load_all()

If that same functionality is used inside an R package, this is the preferred call:

pkgload::load_all()

The usethis package is the one constituent package that more people may be aware of and that they may use directly. It now 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. All functions in usethis are made available by devtools. So, once you attach devtools, you can use any function in usethis without qualification, i.e. just call use_testthat(). If you choose to specify the namespace, such as when working in a more programmatic style, then access usethis functions directly: do usethis::use_testthat() instead of devtools::use_testthat().

3.2.1 Personal startup configuration

You can attach devtools like so:

library(devtools)

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

if (interactive()) {
  suppressMessages(require(devtools))
}

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. Another package you may want to handle this way is testthat.

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(
  usethis.full_name = "Jane Doe",
  usethis.description = list(
    `Authors@R` = 'person("Jane", "Doe", email = "jane@example.com", role = c("aut", "cre"), 
    comment = c(ORCID = "YOUR-ORCID-ID"))',
    License = "MIT + file LICENSE",
    Version = "0.0.0.9000"
  ),
  usethis.protocol  = "ssh"  
)

The following code installs the development versions of devtools and usethis, which may be important during the revision of the book.

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

3.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 (the topic of chapter 13). 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.

3.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.

3.3.2 macOS

You need to install the Xcode command line tools, which requires that you register as an Apple developer (don’t worry, it’s free).

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.

3.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.

3.3.4 Verify system prep

You can check that you have everything installed and working by running the following code:

# TODO: replace with whatever results from https://github.com/r-lib/devtools/issues/1970
library(devtools)
has_devel()
#> [1] TRUE

If everything is ok, it returns TRUE. Otherwise, it will reveal some diagnostic info about the problem.