A package reference (ref) specifies a location from which an R package can be obtained from. The full syntax of a reference is type::ref, but type can be often omitted, the common ref types have shortcuts.

Details

Introduction

The currently supported reference types are:

  • cran: a CRAN package.

  • bioc: A Bioconductor package.

  • standard: a package from CRAN or Bioconductor.

  • github: A package from GitHub.

  • local: A local package file or directory.

  • url: An URL to a package archive.

  • installed An installed package.

  • deps The dependencies of a local package file or directory.

If a ref does not explicitly specify a type, then the following rules are applied:

  • if the ref is a valid standard ref type (without the standard:: prefix), then standard is used;

  • if the ref is a valid github ref type (without the github:: prefix), then github is used;

  • if the ref is a GitHub URL, then github is used;

  • otherwise an error is thrown.

Parameters

Package refs may have optional parameters, added after a question mark. Different parameters are separated by an ampersand (&) character. Parameters might be binary, or have a string value, assigned with an equal sign (=). If no value is assigned, then we assume the true value. For example these two package refs are the same:

cran::testthat?source&nocache
cran::testthat?source=true&nocache=true

Currently supported parameters: * source is a binary parameter. If specified, then a source R package is requested from a CRAN-like repository. For package installations source always triggers a re-install. In other words, source implies the reinstall parameter. This parameter is supported for bioc::, cran:: and standard:: remote types, and it is ignore for others. * reinstall requests a re-install for package installations. It is supported by the bioc::, cran::, github::, local::, standard::, and url:: remote types. * nocache will ignore the package cache. It will always download the package file, and it will not add the downloaded (and built) file to the package cache. It is supported by the bioc::, cran::, github::, standard:: and url:: remote types.

CRAN packages:

A package from CRAN. Full syntax:

[cran::]<package>[@[>=]<version> | current | last]
  • <package> is a valid package name.

  • <version> is a version or a version requirement.

Examples:

forecast
forecast@8.8
forecast@>=8.8
cran::forecast
forecast@last
forecast@current

Note: pkgdepends currently parses the version specification part (everything after @), but does not use it.

Bioconductor packages:

A package from Bioconductor. The syntax is the same as for CRAN packages, except of the prefix of course:

[bioc::]<package>[@[>=]<version> | current | last]

Standard packages:

These are packages either from CRAN or Bioconductor, the full syntax is the same as for CRAN packages, except for the prefix:

[standard::]<package>[@[>=]<version> | current | last]

GitHub packages:

Packages from a GitHub repository. Full syntax:

[<package>=][github::]<username>/<repository>[/<subdir>][<detail>]
  • <package> is the name of the package. If this is missing, then the name of the repository is used.

  • <username> is a GitHub username or organization name.

  • <repository> is the name of the repository.

  • <subdir> optional subdirectory, if the package is within a subdirectory in the repository.

  • <detail> specifies a certain version of the package, see below.

<detail> may specify:

  • a git branch, tag or (prefix of) a commit hash: @<commitish>;

  • a pull request: #<pull-request>; or

  • the latest release: @*release.

If <detail> is missing, then the latest commit of the default branch is used.

Examples:

r-lib/crayon
github::r-lib/crayon
r-lib/crayon@84be6207
r-lib/crayon@branch
r-lib/crayon#41
r-lib/crayon@release

For convenience GitHub HTTP URLs can also be used to specify a package from GitHub. Examples:

https://github.com/r-lib/withr
# A branch:
https://github.com/r-lib/withr/tree/ghactions
# A tag:
https://github.com/r-lib/withr/tree/v2.1.1
# A commit:
https://github.com/r-lib/withr/commit/8fbcb548e316
# A pull request:
https://github.com/r-lib/withr/pull/76
# A release:
https://github.com/r-lib/withr/releases/tag/v2.1.0

A GitHub remote string can also be used instead of an URL, for example: git@github.com:r-lib/pkgdepends.git

Local packages:

A path that refers to a package file built with R CMD build, or a directory that contains a package. Full syntax:

local::<path>

For brevity, you can omit the local:: prefix, if you specify an absolute path, a path from the user’s home directory, starting with ~, or a relative path starting with ./ or .\.

A single dot (".") is considered to be a local package in the current working directory.

Examples:

local::/foo/bar/package_1.0.0.tar.gz
local::/foo/bar/pkg
local::.
/absolute/path/package_1.0.0.tar.gz
~/path/from/home
./relative/path
.

URLs:

You can use url:: to refer to URLs that hold R package archives (i.e. properly built with R CMD build), or compressed directories of package trees (i.e. not built with R CMD build). pkgdepends will figure out if it needs to run R CMD build on the package first.

This remote type supports .tar.gz and .zip files.

Note that URLs are not ideal remote types, because pkgdepends needs to download the package file to resolve its dependencies. When this happens, it puts the package file in the cache, so no further downloads are needed when installing the package later.

Examples:

url::https://cloud.r-project.org/src/contrib/Archive/cli/cli_1.0.0.tar.gz
url::https://github.com/tidyverse/stringr/archive/HEAD.zip

Installed packages:

This is usually used internally, but can also be used directly. Full syntax:

installed::<path>/<package>
  • <path> is the library the package is installed to.

  • <package> is the package name.

Example:

installed::~/R/3.6/crayon

Package dependencies:

Usually used internally, it specifies the dependencies of a local package. It can be used to download or install the dependencies of a package, without downloading or installing the package itself. Full syntax:

deps::<path>

Examples:

deps::/foo/bar/package_1.0.0.tar.gz
deps::/foo/bar/pkg
deps::.