dependencies() will crawl files within your project, looking for R files
and the packages used within those R files. This is done primarily by
parsing the code and looking for calls of the form library(package),
require(package), requireNamespace("package"), and package::method().
renv also supports package loading with
box (box::use(...)) and
pacman (pacman::p_load(...))
.
For R package projects, dependencies expressed in the DESCRIPTION file
will also be discovered.
Note that the rmarkdown package is required in order to crawl dependencies in R Markdown files.
dependencies(
path = getwd(),
root = NULL,
...,
quiet = NULL,
progress = TRUE,
errors = c("reported", "fatal", "ignored"),
dev = FALSE
)An R
data.frame of discovered dependencies, mapping inferred
package names to the files in which they were discovered. Note that the
Package field might name a package remote, rather than just a plain
package name.
The path to a .R, .Rmd, .qmd, DESCRIPTION, a directory
containing such files, or an R function. The default uses all files
found within the current working directory and its children.
The root directory to be used for dependency discovery.
Defaults to the active project directory. You may need to set this
explicitly to ensure that your project's .renvignores (if any) are
properly handled.
Unused arguments, reserved for future expansion. If any arguments
are matched to ..., renv will signal an error.
Boolean; be quiet while checking for dependencies?
Setting quiet = TRUE is equivalent to setting progress = FALSE
and errors = "ignored", and overrides those options when not NULL.
Boolean; report progress output while enumerating dependencies?
How should errors that occur during dependency enumeration be handled?
"reported" (the default): errors are reported to the user, but
otherwise ignored.
"fatal": errors are fatal and stop execution.
"ignored": errors are ignored and not reported to the user.
Boolean; include development dependencies? These packages are typically required when developing the project, but not when running it (i.e. you want them installed when humans are working on the project but not when computers are deploying it).
Development dependencies include packages listed in the Suggests field
of a DESCRIPTION found in the project root, and roxygen2 or devtools if
their use is implied by other project metadata. They also include packages
used in ~/.Rprofile if config$user.profile() is TRUE.
dependencies() uses static analysis to determine which packages are used
by your project. This means that it inspects, but doesn't run, your
source. Static analysis generally works well, but is not 100% reliable in
detecting the packages required by your project. For example, renv is
unable to detect this kind of usage:
for (package in c("dplyr", "ggplot2")) {
library(package, character.only = TRUE)
}
It also can't generally tell if one of the packages you use, uses one of
its suggested packages. For example, tidyr::separate_wider_delim()
uses the stringr package which is only suggested, not required by tidyr.
If you find that renv's dependency discovery misses one or more packages
that you actually use in your project, one escape hatch is to include a file
called _dependencies.R that includes straightforward library calls:
library(dplyr)
library(ggplot2)
library(stringr)
Alternatively, you can suppress dependency discover and instead rely
on an explicit set of packages recorded by you in a project DESCRIPTION file.
Call renv::settings$snapshot.type("explicit") to enable "explicit" mode,
then enumerate your dependencies in a project DESCRIPTION file.
In that case, your DESCRIPTION might look something like this:
Type: project
Description: My project.
Depends:
tidyverse,
devtools,
shiny,
data.table
By default, renv will read your project's .gitignores (if present) to
determine whether certain files or folders should be included when traversing
directories. If preferred, you can also create a .renvignore file (with
entries of the same format as a standard .gitignore file) to tell renv
which files to ignore within a directory. If both .renvignore and
.gitignore exist within a folder, the .renvignore will be used in lieu of
the .gitignore.
See https://git-scm.com/docs/gitignore for documentation on the
.gitignore format. Some simple examples here:
# ignore all R Markdown files
*.Rmd# ignore all data folders
data/
# ignore only data folders from the root of the project
/data/
Using ignore files is important if your project contains a large number
of files; for example, if you have a data/ directory containing many
text files.
renv's attempts to enumerate package dependencies in your project can fail
-- most commonly, because of failures when attempting to parse your R code.
You can use the errors argument to suppress these problems, but a
more robust solution is tell renv not to look at the problematic code.
As well as using .renvignore, as described above, you can also suppress errors
discovered within individual .Rmd chunks by including renv.ignore=TRUE
in the chunk header. For example:
```{r chunk-label, renv.ignore=TRUE}
# code in this chunk will be ignored by renv
```
Similarly, if you'd like renv to parse a chunk that is otherwise ignored
(e.g. because it has eval=FALSE as a chunk header), you can set:
```{r chunk-label, eval=FALSE, renv.ignore=FALSE}
# code in this chunk will _not_ be ignored
```
renv has some support for distinguishing between development and run-time dependencies. For example, your Shiny app might rely on ggplot2 (a run-time dependency) but while you use usethis during development, your app doesn't need it to run (i.e. it's only a development dependency).
You can record development dependencies by listing them in the Suggests
field of your project's DESCRIPTION file. Development dependencies will be installed by
install() (when called without arguments) but will not be tracked in
the project snapshot. If you need greater control, you can also try project
profiles as discussed in vignette("profiles").
if (FALSE) {
# find R package dependencies in the current directory
renv::dependencies()
}
Run the code above in your browser using DataLab