Common Configurations

rv was designed to provide a simple, reproducible way to manage packages, approachable even for those without a computer science background, while still being powerful and flexible enough to fit the most demanding developer needs. To help explore the configurations possible with rv, we will first go over the most common configuration options.

name

The name field is not used by rv, but is required for your own organization. Recommended to have the same name as the directory/repository.

name = "common configurations"

r_version

rv will look on the path, and in /opt/R for unix-like systems, for the R version specified in the config. The version must contain at least the major and minor version and is hazy matched to the version(s) found on the system. For example, 4.4 will match 4.4.1 and 4.4.2, but 4.4.1 will only match 4.4.1.

r_version = "4.4"

Note

R packages are compatible across patch versions of R, therefore for most situations it is recommended to specify only the major and minor to increase cross-system compatibility.

repositories

A list of CRAN-like repositories to fetch packages from. The order in which the repositories are listed matters. For example, if a package is listed in two repositories, rv will install it from the first repository a resolvable version can be found in. Packages will be installed as binary when found by default.

Options:

• alias - Used for self-organization and to specify a dependency to come from a certain repository.
• url - The CRAN-like from which to fetch packages from. Linux binaries are automatically found using the Posit Package Manager spec.
• force_source optional - Force all packages coming from the repository to be source.

  Default: false

repositories = [
    { alias = "PPM", url = "https://packagemanager.posit.co/cran/2024-01-01" },
    { alias = "CRAN", url = "https://cran.r-project.org", force_source = true },
]

dependencies

This is the main element of the config file, most commonly edited. It specifies which packages (or project “dependencies”) to install in your project, as well as some options to further tune the installation.

There are 4 types of dependency configurations, sorted by their source, each of which have individual configurations corresponding with them.

All dependencies types have the following configurations:

• install_suggestions optional: Install the suggested dependencies of the package

  Default: false

• dependencies_only optional: Install only the dependencies of the package, not the package itself. Used primarily for package development.

  Default: false

Repository

The most common/default type. The packages will be sourced from the CRAN-like repositories listed in the repositories section, preferring binaries unless otherwise specified.

Configurations:

• name - The name of the package.

• repository optional - Used to specify that a package must come from a specific repository, by setting to the alias corresponding alias from the repositories section.

  Default: first resolvable repository

• force_sourceoptional - Force the package to be fetched as source.

  Default: false

dependencies = [
    "dplyr", # a simple string is equivalent to `{ name = "dplyr" }`
    { name = "purrr", force_source = true },
    { name = "ggplot2", repository = "CRAN" },
]

Note

rv does not directly support the installation of specify package versions from repositories.

In a CRAN-like repository, only one package version is available at a time. While this is often inconvient, CRAN also provides the guarantee that all packages are compatible with each other at any point in time.

In order to take advantage of this stability win, we have conciously decided to not add direct version support yet. Adding additional repository snapshot date(s) containing the versions of interest, and specifying the repository arguement can often lead to the same result, in a more stable manner.

Git

Used to install packages from a git repository from either a branch, tag, or commit. Requires the git CLI to be available.

Configurations:

• name - The name of the package. Must match the name of the package found in the repository.
• git - The git repository url.
• tag or commit or branch - Must specify one. commit must be the full hash.
• path optional - a path to a subdirectory inside of the repository containing the R package

  Default: None

dependencies = [
    { name = "git-tag", git = "https://github.com/a2-ai/git-tag", tag = "v1.0.0" },
    { name = "git-commit", git = "https://github.com/a2-ai/git-commit", commit = "bc50e550e432c3c620714f30dd59115801f89995" },
    { name = "git-branch", git = "https://github.com/a2-ai/git-branch", branch = "main", path = "r" },
]

Local

Install a package from a local source. Can be a directory or archive containing a source or binary R package.

Configurations:

• name - The name of the package. Must match the name of the package found at the path.
• path - The path pointing to the package directory or archive

dependencies = [
    { name = "local-dir", path = "path/to/my/package", dependencies_only = true },
    { name = "local-archive", path = "path/to/my/archive.tar.gz" },
]

URL

Install a source or binary package directly from a URL.

Configurations:

• name - The name of the package. Must match the name of the package found at the url.
• url - The url pointing to the package archive from which to download.

    { name = "dplyr", url = "https://cran.r-project.org/src/contrib/Archive/dplyr/dplyr_1.1.3.tar.gz" },