forked from r-lib/usethis
/
usethis-setup.Rmd
228 lines (152 loc) · 12.4 KB
/
usethis-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
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
---
title: "usethis setup"
---
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
```
You will get the most out of usethis if you do some setup. These setup tasks do not need to be done all at once or even done at all. But usethis can offer the most support for package development and Git/GitHub workflows with some advance configuration. usethis can even help you with this!
Key steps that accelerate your R development workflow (details on *how* to do all this follow):
* Make usethis available in interactive R sessions.
* Provide usethis with info to use in all new R packages you create.
* Use the "sitrep" functions to get a health check or gather info when you're
going to ask for help.
* Sign up for a free GitHub.com account, if you plan to use GitHub.
* Install Git.
* Configure your Git `user.name` and `user.email`.
* If you use RStudio, make sure RStudio can find your Git executable. If you use GitHub, make sure you can pull/push from your local computer to GitHub.com, in general and from RStudio.
* Get a personal access token from GitHub.com and make it available in R sessions.
* Prepare your system to build R packages from source.
## Use usethis or devtools in interactive work
The usethis package was carved out of the [devtools package](https://devtools.r-lib.org) as part of its "conscious uncoupling" in [the v2.0.0 release](https://www.tidyverse.org/articles/2018/10/devtools-2-0-0/). But note that devtools makes all of usethis's functions available and they should feel like they are part of devtools itself. In addition, devtools offers some functions of its own and exposes selected functionality from a few other packages. You might enjoy making devtools (and therefore usethis) available in all your interactive R work.
Call `usethis::use_devtools()` for prompts to do this:
```{r, eval = FALSE}
library(devtools) ## or library(usethis)
use_devtools()
```
This will:
* Open your `.Rprofile` startup file for editing.
* Show the necessary code snippet in the console and put it on your clipboard.
* Prompt you to paste, save, close, restart R. Done!
The suggested snippet looks like this:
```{r, eval = FALSE}
if (interactive()) {
suppressMessages(require(devtools))
}
```
If, for some reason, you would prefer to do same, but only for usethis, call `usethis::use_usethis()` instead. If you decide to attach both packages, we recommend attaching devtools, then usethis.
```{r, eval = FALSE}
if (interactive()) {
suppressMessages(require(devtools))
suppressMessages(require(usethis))
}
```
More resources on `.Rprofile`:
* The official [Startup documentation](https://stat.ethz.ch/R-manual/R-patched/library/base/html/Startup.html)
* The [Startup chapter](https://whattheyforgot.org/r-startup.html) of the What They Forgot to Teach You About R workshop materials
* Kevin Ushey's blog post [RProfile Essentials](http://kevinushey.github.io/blog/2015/02/02/rprofile-essentials/)
## Store default values for DESCRIPTION fields and other preferences
Certain options are consulted by usethis and allow you to set personal defaults:
* `usethis.full_name`: consulted for making, e.g., supplemental license files.
* `usethis.protocol`: specifies your preferred transport protocol for
Git. Either "ssh" or "https". See the help for `git_protocol()` for more.
* `usethis.description`: named list of default DESCRIPTION fields for new
packages made with `usethis::create_package()`.
Define any of these options in your `.Rprofile`, which can be opened for editing via `usethis::edit_r_profile()`. Here is example code:
```{r, eval = FALSE}
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"
)
```
Save similar code in your `.Rprofile` and restart R for it to take effect.
## The "sitrep" functions
These functions gather information that help you or others troubleshoot things:
* `proj_sitrep()`: prints info about the active usethis project, working
directory, and the active RStudio Project. Points out when things are
peculiar and how to fix.
* `git_sitrep()`: prints info about your current Git, git2r, and GitHub setup.
## Get a GitHub.com account
Sign up for a free account with [GitHub.com](https://github.com/). [Happy Git and GitHub for the useR](https://happygitwithr.com/github-acct.html) provides more advice about picking your username and discusses ways to get private repositories.
## Install Git
Please see [Happy Git and GitHub for the useR](https://happygitwithr.com/install-git.html) for instructions on how to install Git. It is beyond the scope of this article.
usethis itself does not actually need the Git that you install, because it uses the [git2r](https://cran.r-project.org/package=git2r) package which wraps [libgit2](https://libgit2.github.com). But, chances are, you want to do normal Git things, like diff and commit and push, from RStudio or in the shell and for that you must install Git.
## Configure `user.name` and `user.email`
Once Git is installed, introduce yourself to Git.
```{r, eval = FALSE}
library(usethis) ## or library(devtools)
use_git_config(user.name = "Jane Doe", user.email = "jane@example.com")
## check by running a git situation-report:
## - your user.name and user.email should appear under "User"
git_sitrep()
```
`usethis::use_git_config()` helps you configure your `user.name` and `user.email`. Substitute **your name** and **your email address**.
What user name should you give to Git? This does not have to be your GitHub username, although it can be. Another good option is your actual first name and last name. Your commits will be labelled with this name, so this should be informative to potential collaborators.
What email should you give to Git? This must be the email associated with your GitHub account.
`usethis::git_sitrep()` generates a git situation-report. It can help you confirm things will work as expected; it can also help you diagnose problems.
### Equivalent Git commands
The code chunk above is doing the equivalent of this:
```{sh, eval = FALSE}
git config --global user.name 'Jane Doe'
git config --global user.email 'jane@example.com'
git config --global --list
```
### Optional: configure Git's editor
Another Git option that many people eventually configure is the editor. This will come up if you use Git from a shell. At some point, you will fail to give Git what it wants in terms of a commit message and it will kick you into an editor. This can be distressing, if it’s not your editor of choice and you don’t even know how to save and quit. You can enforce your will by executing this in a shell (not in R!):
```{sh, eval = FALSE}
git config --global core.editor emacs
```
Substitute your preferred editor for emacs here. A popular choice is [nano](https://www.nano-editor.org/). The default, if you don't configure `core.editor`, is usually vim.
## Connections: Git, GitHub, RStudio
As stated above, usethis doesn't actually use the Git you install and has no absolute requirement that you use GitHub or use RStudio. But use of usethis is highly correlated with the desire to do all of these things, in a pleasant way.
If you plan to use GitHub, you need to make sure your local Git can pull from and push to GitHub.com. That is beyond the scope of this article, but see the [Connect to GitHub](https://happygitwithr.com/push-pull-github.html) section in Happy Git. You probably don't want to enter your username and password all the time, so either [cache credentials for HTTPS](https://happygitwithr.com/credential-caching.html) or [set up SSH keys](https://happygitwithr.com/ssh-keys.html). Then set the `usethis.protocol` option to match, i.e. to either "https" or "ssh". This setup makes functions like `usethis::use_github()` much easier to use.
If you want to use RStudio to work with Git (and therefore GitHub, see previous paragraph), you need to make sure RStudio can find your Git executable. This usually "just works". The [Connect RStudio to Git and GitHub](https://happygitwithr.com/rstudio-git-github.html) section of Happy Git helps you confirm that all is well. If all is not well, there are also [troubleshooting tips](https://happygitwithr.com/rstudio-see-git.html).
## Get and store a GitHub personal access token
A GitHub personal access token (PAT) is required if you want to use `usethis::use_github()` and `usethis::create_from_github(..., fork = TRUE)`. In both cases, usethis must create a new GitHub repository on your behalf. This is **not** a regular Git operation (like pulling and pushing to existing repos) and your usual method of providing credentials to GitHub does not work for this.
Other functions, such as the `pr_*()` family, may also use your GitHub PAT for fetch/pull/push if you are using the HTTPS protocol.
```{r, eval = FALSE}
library(usethis)
browse_github_token()
```
`usethis::browse_github_token()` takes you to a pre-filled form to request a PAT. You can get to the same page in the browser by clicking on "Generate new token" from <https://github.com/settings/tokens>.
As the page says, you must **store this token somewhere** because you'll never be able to see it again, once you leave that page or close the windows. If you somehow goof this up, just generate a new PAT and, so you don't confuse yourself, delete the lost token.
`browse_github_token()` provides advice on how to store your PAT, also repeated here. It is customary to save the PAT as an environment variable in your `.Renviron`, with the name `GITHUB_PAT`.
```{r, eval = FALSE}
library(usethis)
edit_r_environ()
```
`usethis::edit_r_environ()` will open `.Renviron` for editing. Add a line like this, **but substitute your PAT**:
```{sh}
GITHUB_PAT=8c70fd8419398999c9ac5bacf3192882193cadf2
```
Make sure this file ends in a newline! Lack of a newline can lead to silent failure to load this environment variable, which can be tricky to debug.
Restart R and confirm your PAT is now available:
```{r, eval = FALSE}
Sys.getenv("GITHUB_PAT")
## or, alternatively,
library(usethis)
github_token()
```
The GitHub section of `usethis::git_sitrep()` will also reveal if a PAT is found and, if so, the associated user.
```{r, eval = FALSE}
git_sitrep()
```
Now usethis (and a few other packages) can find this PAT automatically in order to deal with GitHub on your behalf.
## Prepare your system to build packages from source
As you participate more in R development, you will inevitably want to run development versions of other people's packages, i.e. not the version available from CRAN. A typical way to do this is to install a package from GitHub with `devtools::install_github("OWNER/REPO")`.
But, unlike using `install.packages()` and CRAN, you will be downloading and installing a *source* package, not a *binary* package. This means your system needs to be set up for building R packages. And, before long, you will need to build an R package with compiled code in it.
A full description of setting up an R development environment is beyond the scope of this article, but we give some pointers and diagnostics to get you started.
Update R and all of your packages. And expect to keep doing so frequently.
**Mac OS**: A convenient way to get the tools needed for compilation is to install Xcode Command Line Tools. Note that this is *much smaller* than full Xcode. In a shell, enter `xcode-select --install`. For installing almost anything else, consider using [Homebrew](https://brew.sh).
**Windows**: Install Rtools. This is not an R package! It is "a collection of resources for building packages for R under Microsoft Windows, or for building R itself". Go to <https://cran.r-project.org/bin/windows/Rtools/> and install as instructed.
There are functions that verify whether R package build tools are installed and available. The home and name of this function is in flux, as it is affected by the restructing of the devtools universe (written early 2018).
* `pkgbuild::check_build_tools()` is the most current function. It can be installed via `install.packages("pkgbuild")`.
* `devtools::has_devel()` was a function in devtools, at least up to v1.13.5, so you might still see references to that. All functionality related to package building now lives in pkgbuild. But once you have installed pkgbuild, you should just use the function `pkgbuild::check_build_tools()` instead.