-
Notifications
You must be signed in to change notification settings - Fork 152
/
README.Rmd
234 lines (174 loc) · 8.17 KB
/
README.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
229
230
231
232
233
234
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# remotes
> Install R Packages from remote or local repositories,
> including GitHub, GitLab, Bitbucket, and Bioconductor
<!-- badges: start -->
[](https://github.com/r-lib/remotes/actions/workflows/R-CMD-check.yaml)
[](https://app.codecov.io/gh/r-lib/remotes?branch=main)
[](https://www.r-pkg.org/pkg/remotes)
[](https://www.r-pkg.org/pkg/remotes)
[](https://lifecycle.r-lib.org/articles/stages.html)
<!-- badges: end -->
Download and install R packages stored in GitHub, GitLab, Bitbucket,
Bioconductor, or plain subversion or git repositories. This package
is a lightweight replacement of the `install_*` functions in
[`devtools`](https://github.com/r-lib/devtools).
Indeed most of the code was copied over from `devtools`.
## Features
* Installers:
* Install packages with their dependencies.
* Install from GitHub, GitLab, Bitbucket.
* Install from git and subversion repositories.
* Install from local files or URLs.
* Install the dependencies of a local package tree.
* Install specific package versions from CRAN.
* Supports [Bioconductor](https://bioconductor.org/) packages.
* Supports the `Remotes` field in `DESCRIPTION`. See more in the
[dependencies](https://github.com/r-lib/remotes/blob/HEAD/vignettes/dependencies.Rmd) vignette.
* Supports the `Additional_repositories` field in `DESCRIPTION`.
* Can install itself from GitHub (see below).
* Does not depend on other R packages.
* Does not contain compiled code, so no compiler is needed.
* Does not need any external software (for most of the functionality
at least).
## Installation
Install the released version of remotes from CRAN:
```r
install.packages("remotes")
```
## Usage
Note that most of the examples here use GitHub. See below for other
supported repository types.
To install the latest version of a package in the default branch from
GitHub, you can use the `user/repo` form. Note that `user` can also be
an organization:
```r
remotes::install_github("r-lib/conflicted")
```
If the R package is inside a subdirectory of the root directory,
then give this subdirectory as well:
```r
# build = FALSE because of some specificities of XGBoost package
install_github("dmlc/xgboost/R-package", build = FALSE)
```
To install a certain branch or commit or tag, append it to the
repo name, after an `@`:
```r
remotes::install_github("gaborcsardi/pkgconfig@v2.0.0")
```
To install the latest release, append `@*release` to the repo
name:
```r
remotes::install_github("gaborcsardi/pkgconfig@*release")
```
To install a pull request, append `#` and the id (an integer number)
of the pull request to the repo name:
```r
remotes::install_github("r-lib/pkgconfig#7")
```
### Dependencies
Dependencies are automatically installed from CRAN. By default,
outdated dependencies are automatically upgraded. In interactive sessions
you can select a subset of the dependencies to upgrade.
#### Dependencies on GitHub
It is also possible to install dependencies from GitHub or other
supported repositories. For this you need to add a `Remotes` field to the
`DESCRIPTION` file. Its format is:
```
Remotes: [remote::]repo_spec, [remote::]repo_spec, ...
```
where `repo_spec` is any repository specification the corresponding
`install_()` function can handle. If `remote::` is missing, `github::` is
assumed. Other possible values: `gitlab::`,`bitbucket::`, `git::`, `local::`,
`svn::`, `url::`, `version::`, `cran::`, `bioc::`.
See more about the `Remotes` field in this
[vignette](https://remotes.r-lib.org/articles/dependencies.html).
#### Additional repositories
remotes supports the `Additional_repositories` field in
`DESCRIPTION`. This is a way to specify dependencies from non-CRAN
package repositories. See the [Writing R extensions](https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Package-Dependencies)
manual for details.
#### Bioconductor packages
Bioconductor packages are automatically detected and their
dependencies are installed from Bioconductor.
#### Currently supported remote types
* GitHub repositories via `install_github`.
* Bitbucket repositories via `install_bitbucket`.
* Generic git repositories via `install_git`. They need either a
system git installation, or the
[git2r](https://github.com/ropensci/git2r) R package.
* Local directories or package archive files via `install_local`.
* Remote package archive files via `install_url`.
* Packages in subversion repositories via `install_svn`. They need
a system subversion installation.
* Specific package versions from CRAN or other CRAN-like
repositories via `install_version`. This includes outdated
and archived packages as well.
* All dependencies of a package in a local directory via
`install_deps`.
### Download methods
* For R older than 3.2, the curl package is required as remotes falls back
to `curl::curl_download` in that case
* For R newer than 3.3, default `download.file()` method is used.
(`method = "auto"`)
* For in between versions,
* `method = "wininet"` is used on windows OS
* `method = "libcurl"` is used on other OS, if available.
See `help("download.file")` for information on these methods and for
setting proxies if needed.
### Standalone mode
remotes will use the curl, git2r and pkgbuild packages if they are
installed to provide faster implementations for some aspects of the install
process. However if you are using remotes to install or update these packages
(or their reverse dependencies) using them during installation may fail
(particularly on Windows).
If you set the environment variable `R_REMOTES_STANDALONE="true"` (e.g.
in R `Sys.setenv(R_REMOTES_STANDALONE="true")`) you can force remotes to
operate in standalone mode and use only its internal R implementations. This
will allow successful installation of these packages.
### Options
remotes uses the following standard R options, see `?options` for their
details:
* `download.file.method` for the default download method. See
`?download.file`.
* `pkgType` for the package type (source or binary, see manual) to install,
download or look up dependencies for.
* `repos` for the locations of the user's standard CRAN(-like) repositories.
It also uses some remotes specific options:
* `BioC_git` for the URL of the default Bioconductor git mirror.
* `BioC_mirror` for the URL of the Bioconductor mirror.
* `unzip` for the path of the external `unzip` program.
### Environment variables
* The `BITBUCKET_USER` and `BITBUCKET_PASSWORD` environment variables
are used for the default Bitbucket user name and password, in
`install_bitbucket()`
* The `GITHUB_PAT` environment variable is used as the default GitHub
personal access token for all GitHub API queries.
* The `R_BIOC_MIRROR` environment variable can be used to specify an
alternative Bioconductor mirror. (The `BioC_mirror` option takes
precedence over this.)
* The `R_BIOC_VERSION` environment variable can be used to force a
Bioconductor version.
* The `R_REMOTES_UPGRADE` environment variable can be used to set a default
preferred value for the `upgrade =` argument accepted by the various
`install_*()` functions. For example, you can set `R_REMOTES_UPGRADE="always"`
to upgrade dependent packages without asking the user.
* Setting `R_REMOTES_STANDALONE="true"` forces remotes to work in standalone
mode and avoid loading its optional dependencies (curl, git2 and pkgbuild
currently. See "Standalone mode" above.
* Setting `R_REMOTES_NO_ERRORS_FROM_WARNINGS="false"` will cause warning
messages during calls to `install.packages()` to become errors. Often warning
messages are caused by dependencies failing to install.
## License
GPL (>= 2) © Ascent Digital Services, Posit Software, PBC