To get started, make sure you have the latest version of R (at least 4.2.0, which is the version being used to render this book), then run the following code to get the packages you’ll need:
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.
- Preview version: https://www.rstudio.com/products/rstudio/download/preview/
- Released version: https://www.rstudio.com/products/rstudio/download/
- Most readers can use the free, open source version of RStudio Desktop.
“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
fooin a qualified call of the form
fooshould be the package where
- 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.
- devtools should rarely appear in the role of
- 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:
If that same functionality is used inside an R package, this is the preferred call:
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
You can attach devtools like so:
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:
For convenience, the function
.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
The following code installs the development versions of devtools and usethis, which may be important during the revision of the book.
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 15). 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.
On Windows the collection of tools needed for building packages from source is called Rtools.
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
PATHautomatically when it is needed.
- Do select the box for “Save version information to registry”. It should be selected by default.
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:
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.
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
You can request a “(package) development situation report” with
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: 184.108.40.20600 #> • 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.