dependencies: Find R Package Dependencies in a Project

In wnattt/renv: Project Environments

Description

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.

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:

• library(package)

• require(package)

• requireNamespace("package")

• package::method()

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.

Value

An R data.frame of discovered dependencies, mapping inferred package names to the files in which they were discovered.

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=FALSE in the chunk header. For example:

```{r chunk-label, renv.ignore=FALSE}
# code in this chunk will be ignored by renv
```

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/

Errors

renv's attempts to enumerate package dependencies in your project can fail – most commonly, because of parse errors in 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

## Not run: 

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


## End(Not run)

wnattt/renv documentation built on Dec. 23, 2021, 5:19 p.m.