/
setup.Rmd
173 lines (127 loc) · 9.75 KB
/
setup.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
# System setup {#sec-setup}
```{r, echo = FALSE}
source("common.R")
```
## Prepare your system {#setup-prep}
To get started, make sure you have the latest version of R (at least `r paste0(version$major, ".", version$minor)`, which is the version being used to render this book), then run the following code to get the packages you'll need:
```{r, eval = FALSE}
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.
## devtools, usethis, and you {#sec-setup-usage}
> "I am large, I contain multitudes."
>
> --- Walt Whitman, Song of Myself
As mentioned in @sec-intro-phil, devtools is a 'meta-package', encompassing and exposing functionality maintained in several smaller packages[^setup-1].
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.
[^setup-1]: At the time of writing, devtools exposes functionality from [remotes](https://remotes.r-lib.org/), [pkgbuild](https://pkgbuild.r-lib.org/), [pkgload](https://pkgload.r-lib.org/), [rcmdcheck](https://rcmdcheck.r-lib.org/), [revdepcheck](https://revdepcheck.r-lib.org/), [sessioninfo](https://sessioninfo.r-lib.org/), [usethis](https://usethis.r-lib.org/), [testthat](https://testthat.r-lib.org), and [roxygen2](https://roxygen2.r-lib.org)
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()`.
### Personal startup configuration
You can attach devtools like so:
```{r, eval = FALSE}
library(devtools)
```
But it soon grows aggravating to repeatedly attach devtools in every R session.
Therefore, we strongly recommend attaching[^setup-2] devtools in your `.Rprofile` startup file, like so:
[^setup-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 @sec-dependencies-attach-vs-load.
```{r eval = FALSE}
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.
::: callout-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`:
```{r, eval = FALSE}
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.
```{r, eval = FALSE}
devtools::install_github("r-lib/devtools")
devtools::install_github("r-lib/usethis")
# or, alternatively
pak::pak("r-lib/devtools")
pak::pak("r-lib/usethis")
```
## R build toolchain {#setup-tools}
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.
### 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.
### macOS
You need to install the Xcode command line tools, which requires that you [register as an Apple developer](https://developer.apple.com/programs/enroll/). 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:
``` shell
xcode-select --install
```
Alternatively, you can install the current release of full [Xcode from the Mac App Store](https://itunes.apple.com/ca/app/xcode/id497799835?mt=12).
This includes a very great deal that you do not need, but it offers the advantage of App Store convenience.
### 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`.
## Verify system prep
You can request a "(package) development situation report" with `devtools::dev_sitrep()`:
```{r, eval = FALSE}
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.