Find R Package Dependencies in a Project

Find R packages used within a project.

Usage

dependencies(
  path = getwd(),
  root = NULL,
  ...,
  progress = TRUE,
  errors = c("reported", "fatal", "ignored"),
  dev = FALSE
)

Arguments

path: The path to a (possibly multi-mode) R file, or a directory containing such files. By default, all files within the current working directory are checked, recursively.
root: 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.
progress: Boolean; report progress output while enumerating dependencies?
errors: How should errors that occur during dependency enumeration be handled? See Errors for more details.
dev: Boolean; include 'development' dependencies as well? That is, packages which may be required during development but are unlikely to be required during runtime for your project. By default, only runtime dependencies are returned.

Value

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.

Details

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:

A subset of popular R packages used for package management are also supported:

box: box::use(...)
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.

Suppressing Errors

Depending on how you've structured your code, renv may emit errors when attempting to enumerate dependencies within .Rmd / .Rnw documents. For code chunks that you'd explicitly like renv to ignore, you can include 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

Ignoring Files

By default, renv will read your project's .gitignores (if any) 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.

Errors

renv's attempts to enumerate package dependencies in your project can fail -- most commonly, because of failures when attempting to parse your R code. The errors parameter can be used to control how renv responds to errors that occur.

Name	Action
`"reported"`	Errors are reported to the user, but are otherwise ignored.
`"fatal"`	Errors are fatal and stop execution.
`"ignored"`	Errors are ignored and not reported to the user.

Depending on the structure of your project, you may want renv to ignore errors that occur when attempting to enumerate dependencies. However, a more robust solution would be to use an .renvignore file to tell renv not to scan such files for dependencies, or to configure the project to require explicit dependency management (renv::settings$snapshot.type("explicit")) and enumerate your dependencies in a project DESCRIPTION file.

Development Dependencies

renv attempts to distinguish between 'development' dependencies and 'runtime' dependencies. For example, you might rely on e.g. devtools and roxygen2 during development for a project, but may not actually require these packages at runtime.

Examples

if (FALSE) {

# find R package dependencies in the current directory
renv::dependencies()

}