renv (version 0.8.0)

paths: Path Customization

Description

Access the paths that renv uses for global state storage.

Usage

paths

Format

An object of class list of length 3.

Local Sources

If your project depends on one or R packages that are not available in any remote location, you can still provide a locally-available tarball for renv to use during restore. By default, these packages should be made available in the folder as specified by the RENV_PATHS_LOCAL environment variable. The package sources should be placed in a file at one of these locations:

• ${RENV_PATHS_LOCAL}/<package>/<package>_<version>.<ext>

• <project>/renv/local/<package>/<package>_<version>.<ext>

where .<ext> is .tar.gz for source packages, or .tgz for binaries on macOS and .zip for binaries on Windows. During a restore(), packages installed from an unknown source will be searched for in this location.

Projects

In order to determine whether a package can safely be removed from the cache, renv needs to know which projects are using packages from the cache. Since packages may be symlinked from the cache, and symlinks are by nature a one-way link, projects need to also report that they're using the renv cache.

To accomplish this, whenever renv is used with a project, it will record itself as being used within a file located at:

• ${RENV_PATHS_ROOT}/projects

This file is list of projects currently using the renv cache. With this, renv can crawl projects registered with renv and use that to determine if any packages within the cache are no longer in use, and can be removed.

Details

By default, renv collects state into these folders:

Platform	Location
Linux	~/.local/share/renv
macOS	~/Library/Application Support/renv
Windows	%LOCALAPPDATA%/renv

If desired, this path can be adjusted by setting the RENV_PATHS_ROOT environment variable. This can be useful if you'd like, for example, multiple users to be able to share a single global cache.

The various state sub-directories can also be individually adjusted, if so desired (e.g. you'd prefer to keep the cache of package installations on a separate volume). The various environment variables that can be set are enumerated below:

Environment Variable	Description
RENV_PATHS_ROOT	The root path used for global state storage.
RENV_PATHS_LIBRARY	The root path containing different R libraries.
RENV_PATHS_LOCAL	The path containing local package sources.
RENV_PATHS_SOURCE	The path containing downloaded package sources.
RENV_PATHS_BINARY	The path containing downloaded package binaries.
RENV_PATHS_CACHE	The path containing cached package installations.
RENV_PATHS_RTOOLS	(Windows only) The path to Rtools.
RENV_PATHS_EXTSOFT	(Windows only) The path containing external software needed for compilation of Windows source packages.

Note that renv will append platform-specific and version-specific entries to the set paths as appropriate. For example, if you have set:

Sys.setenv(RENV_PATHS_CACHE = "/mnt/shared/renv/cache")

then the directory used for the cache will still depend on the R version (e.g. 3.5) and the renv cache version (e.g. v2). For example:

/mnt/shared/renv/cache/R-3.5/v2

This ensures that you can set a single RENV_PATHS_CACHE environment variable globally without worry that it may cause collisions or errors if multiple versions of R needed to interact with the same cache.

If reproducibility of a project is desired on a particular machine, it is highly recommended that the renv cache of installed packages + binary packages is stored, so that packages can be easily restored in the future -- installation of packages from source can often be arduous.

If you want these settings to persist in your project, it is recommended that you add these to an appropriate R startup file. For example, these could be set in:

• A project-local .Renviron;

• The user-level .Renviron;

• A file at $(R RHOME)/etc/Renviron.site.

Please see ?Startup for more details.

Examples

# NOT RUN {
# get the path to the project library
path <- renv::paths$library()
# }