Help for package pkgdepends

Title:

Package Dependency Resolution and Downloads

Version:

0.9.0

Description:

Find recursive dependencies of 'R' packages from various sources. Solve the dependencies to obtain a consistent set of packages to install. Download packages, and install them. It supports packages on 'CRAN', 'Bioconductor' and other 'CRAN-like' repositories, 'GitHub', package 'URLs', and local package trees and files. It caches metadata and package files via the 'pkgcache' package, and performs all 'HTTP' requests, downloads, builds and installations in parallel. 'pkgdepends' is the workhorse of the 'pak' package.

License:

MIT + file LICENSE

URL:

https://r-lib.github.io/pkgdepends/, https://github.com/r-lib/pkgdepends

BugReports:

https://github.com/r-lib/pkgdepends/issues

Depends:

R (≥ 3.5)

Imports:

callr (≥ 3.3.1), cli (≥ 3.6.0), curl, desc (≥ 1.4.3), filelock (≥ 1.0.2), jsonlite, lpSolve, pkgbuild (≥ 1.0.2), pkgcache (≥ 2.2.0), processx (≥ 3.4.2), ps, R6, stats, utils, zip (≥ 2.3.0)

Suggests:

asciicast (≥ 2.2.0.9000), codetools, covr, debugme, fansi, fs, gh, gitcreds, glue, htmlwidgets, mockery, pak, pingr (≥ 2.0.0), rmarkdown, rstudioapi, spelling, svglite, testthat (≥ 3.2.0), tibble, webfakes (≥ 1.1.5.9000), withr (≥ 2.1.1)

Config/Needs/builder:

gh, pkgsearch, withr (>= 2.1.1)

Config/Needs/coverage:

r-lib/asciicast, covr

Config/Needs/website:

r-lib/asciicast, pkgdown (>= 2.0.2), tidyverse/tidytemplate

Config/testthat/edition:

Config/usethis/last-upkeep:

2025-05-05

Encoding:

UTF-8

RoxygenNote:

7.3.2.9000

NeedsCompilation:

yes

Packaged:

2025-05-27 06:58:41 UTC; gaborcsardi

Author:

Gábor Csárdi [aut, cre], Posit Software, PBC

[cph, fnd]

Maintainer:

Gábor Csárdi <csardi.gabor@gmail.com>

Repository:

CRAN

Date/Publication:

2025-05-27 07:40:02 UTC

pkgdepends: Package Dependency Resolution and Downloads

Description

pkgdepends is a toolkit for package dependencies, downloads and installations, to be used in other packages. If you are looking for a package manager, see pak.

Features

Look up package dependencies recursively.
Visualize package dependencies.
Download packages and their dependencies.
Install downloaded packages.
Includes a dependency solver to find a consistent set of dependencies.
Supports CRAN and Bioconductor packages automatically.
Supports packages on GitHub and GitLab.
Supports packages in git repositories.
Supports package bundles or files on the web.
Supports local package file and trees.
Supports the Remotes entry in the DESCRIPTION file.
Caches metadata and downloaded packages via pkgcache
Performs all downloads and HTTP queries concurrently.
Builds and installs packages in parallel.

Install

Install the package with:

install.packages("pkgdepends")

If you need the development version, install it with

pak::pak("r-lib/pkgdepends")

Usage

library(pkgdepends)

Package references

A package reference (ref) specifies a location from which an R package can be obtained from. Examples:

devtools
cran::devtools
bioc::Biobase
r-lib/pkgdepends
https://github.com/r-lib/pkgdepends
local::~/works/shiny

See “Package references” for details.

Package dependencies

Dependencies of the development version of the cli package:

pd <- new_pkg_deps("r-lib/pkgcache")
pd$solve()
pd$draw()

## ✔ Loading metadata database ... done                                    
## r-lib/pkgcache 2.1.0.9000 ✨👷🏽🔧                                          
## ├─callr 3.7.3 ✨ ⬇ (431.00 kB)                                           
## │ ├─processx 3.8.1 ✨ ⬇ (316.20 kB)                                      
## │ │ ├─ps 1.7.5 ✨ ⬇ (313.92 kB)                                          
## │ │ └─R6 2.5.1 ✨                                                        
## │ └─R6                                                                  
## ├─cli 3.6.1 ✨ ⬇ (1.38 MB)                                               
## ├─curl 5.0.0 ✨ ⬇ (777.64 kB)                                            
## ├─filelock 1.0.2 ✨ ⬇ (29.58 kB)                                         
## ├─jsonlite 1.8.4 ✨ ⬇ (1.13 MB)                                          
## ├─prettyunits 1.1.1 ✨ ⬇ (35.23 kB)                                      
## ├─processx                                                              
## ├─R6                                                                    
## └─rappdirs 0.3.3 ✨ ⬇ (47.50 kB)                                         
##                                                                         
## Key:  ✨ new |  ⬇ download | 👷🏽 build | 🔧 compile

See the pkg_deps class for details.

Package downloads

Downloading all dependencies of a package:

pdl <- new_pkg_download_proposal("r-lib/cli")
pdl$resolve()
pdl$download()

## ℹ No downloads are needed, 1 pkg is cached                              
##

See the pkg_download_proposal class for details.

Package installation

Installing or updating a set of package:

lib <- tempfile()
dir.create(lib)
pdi <- new_pkg_installation_proposal(
  "r-lib/cli",
  config = list(library = lib)
)
pdi$solve()
pdi$download()
pdi$install()

## ℹ No downloads are needed, 1 pkg is cached                              
## ✔ Installed cli 3.6.1.9000 (github::r-lib/cli@c37f34b) (36ms)           
## ✔ Summary:  ✨ 1 new  in 36ms

Dependency resolution

pkg_deps, pkg_download_proposal and pkg_installation_proposal all resolve their dependencies recursively, to obtain information about all packages needed for the specified package references. See “Dependency resolution” for details.

The dependency solver

The dependency solver takes the resolution information, and works out the exact versions of each package that must be installed, such that version and other requirements are satisfied. See “The dependency solver” for details.

Installation plans

pkg_installation_proposal can create installation plans, and then also install them. It is also possible to import installation plans that were created by other tools. See “Installation plans” for details.

Configuration

The details of pkg_deps, pkg_download_proposal and pkg_installation_proposal can be tuned with a list of configuration options. See “Configuration” for details.

pak – R package manager
pkgcache – Metadata and package cache
devtools – Tools for R package developers

Code of Conduct

Please note that the pkgdepends project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

License

MIT (c) RStudio

Author(s)

Maintainer: Gábor Csárdi csardi.gabor@gmail.com

Other contributors:

Posit Software, PBC (ROR) [copyright holder, funder]

Shorthands for dependency specifications

Description

Shorthands for dependency specifications

Usage

as_pkg_dependencies(deps)

Arguments

deps

See below.

Details

R packages may have various types of dependencies, see Writing R Extensions.

pkgdepends groups dependencies into three groups:

hard dependencies: "Depends", "Imports", and "LinkingTo",
soft dependencies: "Suggests" and "Enhances",
extra dependencies, see below.

pkgdepends supports concise ways of specifying which types of dependencies of a package should be installed. It is similar to how utils::install.packages() interprets its dependencies argument.

You typically use one of these values:

NA or "hard" to install a package and its required dependencies,
TRUE to install all required dependencies, plus optional and development dependencies.

If you need more flexibility, the full description of possible values for the deps argument are:

TRUE: This means all hard dependencies plus Suggests for direct installations, and hard dependencies only for dependent packages.
FALSE: no dependencies are installed at all.
NA (any atomic type, so NA_character_, etc. as well): only hard dependencies are installed. See pkg_dep_types_hard().
If a list with two entries named direct and indirect, it is taken as the requested dependency types, for direct installations and dependent packages.
If a character vector, then it is taken as the dependency types for direct installations, and the hard dependencies are used for the dependent packages.

If "hard" is included in the value or a list element, then it is replaced by the hard dependency types. If "soft" or "all" is included, then it is replaced by all hard and soft dependency.

Extra dependencies

pkgdepends supports extra dependency types for direct installations not from CRAN-like repositories. These are specified with a ⁠Config/Needs/⁠ prefix in the DESCRIPTION and they can contain package references, separated by commas. For example you can specify packages that are only needed for the pkgdown website of the package:

Config/Needs/website: r-lib/pkgdown

To use these dependency types, you need to specify them in the deps argument to pkgdepends functions.

Note that ⁠Config/Needs/*⁠ fields are currently not used from CRAN packages, and packages in CRAN-like repositories in general.

Usually you specify that a ⁠Config/Needs/*⁠ dependency type should be installed together with "hard" or "all", to install all hard or soft dependencies as well.

Value

A named list with two character vectors: direct, indirect, the dependency types to use for direct installations and dependent packages.

Package configuration (internals)

Description

Internal machinery for pkgdepends configuration. See current_config() for how this machinery can be used to define the configuration of a package.

This is a standalone file that can be copied into another package without changes.

Usage

config

Format

config is a list of functions with a closure. You can use it two ways.

For one set of configuration values in a package, include this in .onLoad():

conf <- config$new("prefix")
conf$add("myenrry", "string", "default-value")
...
conf$lock()

For _multiple _ sets of configuration values (e.g. one per object), include a function like this in the package:

current_config <- function() {
  conf <- config$new("prefix")
  conf$add("myentry", "string", "default-value")
  ...
  conf$lock()
  conf
}

and then call current_config() every time you need to create a new set of configuration values.

Terminology

Config entry (or entry)

A single configurable entity. A config entry has a name. This name is always standardized by replacing dashes with underscores.

A config entry has a type: a string, a flag, or some user defined type. It can also have a default value. Examples:

The URL of an API, which can be a string.
Path to a directory to use for caching, either a string, or NULL (string_or_null type).
Number of processor cores to use, a positive integer (count type).

Configuration (or config)

A set of configuration entries. config$new() returns a configuration. A configuration can be extended by adding new entries to it, until it is locked.

R option (or option)

An option set with base::options() and queried with base::getOption().

Configuration prefix

A prefix that is typically package specific, and it is used for all config entries of a package, to avoid environment variable and option name clashes between packages.

Config entry type

It defines the allowed values of configuration entries, and also how a string from an environment variable is translated to the value of the entry. See the list of builtin types below. You can also define new types.

Built-in types

`string`

String scalar, NA is not allowed.

`count`

Non-negative integer, NA is not allowed.

`flag`

Logical scalar, NA is not allowed. For environment variables the TRUE values are: yes, true, 1 and on, and the FALSE values are: no, false, 0, off. (All are case insensitive.)

`string_or_null`

String or NULL. NA is not allowed. In environment variables the string NULL means an R NULL value.

`character`

Character vector without NA values. In environment variables the entries are separated by a semicolon.

`custom`

Custom type. An env_decode function must be specified for each config entry of this type, otherwise an error is throw if the corresponding environment variable is set.

`config$onload_hook()`: pretty-printing configuration

Call config$onload_hook() from the package's .onLoad() function if you want to define S3 methods to print the package configuration nicer.

Usage

config$onload_hook()

`config$new()`: Create a new configuration

Typically new() is called outside of the functions of the package, so the config object is created at install time.

Usage

conf <- config$new(prefix = utils::packageName(parent.frame()))

Arguments

prefix: prefix of the config entry names. For environment variables it is converted to uppercase, and dots are converted to underscores. The default prefix is the name of the calling package. An underscore separator is used between the prefix and the entry name for environment variable names. A dot separator is used for R option names.

Value

new() returns a config object, which is a list containing the configuration data and functions (methods) to query and change it.

conf <- config$new()

Configuration methods

`conf$add()`: add a new configuration entry

Usage

conf$add(
  name,
  type = conf$types,
  default = NULL,
  check = type[1],
  env_decode = type[1]
)

Arguments

name: name of the entry.
type: type of the entry, string.
default: default value of config entry. If this is a function, then it is called to generate the default, at the time the config entry's value is queried.
check: if it is a function, it is called to check the value of the entry. The function should return TRUE for successful and FALSE for unsuccessful checks. If NULL, then no check is performed. It can also be the name of a type, then the default check for that type is performed, if any.
env_decode: if it is a function, then it is used to decode the value of the entry from an environment variable, i.e. a string. It can also be the name of a type, then the env_decode() function of that type is used for decoding.

Value

The configuration, invisibly.

`conf$get()`: query the value of a configuration entry

Usage

conf$get(name)

Arguments

name: name of the entry.

Value

Value of the entry.

If the entry was set via conf$set() or conf$update(), then that value is returned.
Otherwise, if the entry is set via an R option (see base::getOption()), then that value is returned. The config prefix is used to get the option name, with a dot separator. I.e. for an entry called 'foo', and prefix 'pkg', the pkg.foo option is used. If the entry has a check function, that is called before returning.
Otherwise, if the entry is set via an environment variable, then that value is returned. The config prefix is used to get the name of the environment variable. In addition, dots are replaced with underscores and the name is converted to uppercase. I.e. for an entry called 'foo.bar', and prefix 'pkg', the 'PKG_FOO_BAR' environment variable is used.
Otherwise, if the entry has a default value, that is returned. The default value might be a function, in which case that function is called to produce a default value. If the entry has a check function, that is called before returning.

`conf$set()`: set the value of a configuration entry

If you ⁠$set()⁠ a config entry, then the value used in ⁠$set()⁠ will be returned by ⁠$get()⁠, without consulting R options or environment variables.

Usage

conf$set(name, value)

Arguments

name: name of the entry.
value: value of the entry. If the entry has a check function, it is called here.

Value

The configuration, invisibly.

`⁠$conf$unset()⁠`: unset a configuration entry

Note that this function does not unset R options and environment variables. It merely removes a value that was assigned by ⁠$set()⁠ or ⁠$update()⁠.

Usage

conf$unset(name)

Arguments

name: name of the entry.

Value

The configuration, invisibly.

`cond$update()`: update the values of configuration entries

You can use this method to set()and/or$unset()⁠multiple config entries.⁠NULL⁠values in⁠new' will unset the corresponding entry.

Usage

conf$update(new)

Arguments

new: named list, where names are config entry names and values are the corresponding config entry values. NULL values will unset the config entry. The list is processed sequentially, so for duplicates the latest values will be in effect. (But every value is checked with its check function, if any.)

Value

The configuration, invisibly.

`conf$list()`: query the names of all config entries

Note that their order is non-deterministic currently.

Usage

conf$list()

Value

Character vector.

`conf$exists()`: check if a config entry exists

Usage

conf$exists(name)

Arguments

name: name of the entry.

Value

Logical scalar, TRUE if the entry exists in the configuration, FALSE otherwise. Note that TRUE does not mean that the value of the entry was set.

`conf$lock()`: lock the configuration

If a configuration is locked, then no more entries can be added to it.

Usage

conf$lock()

Value

The configuration, invisibly.

`conf$fix()`: fix the value of a single configuration entry

The currently ⁠$set()⁠ value is fixed and cannot be changed any more. You can fix an entry without setting its value, in which case R options and environment variables can still be used to update it.

Usage

conf$unset(name)

Arguments

name: name of the entry.

Value

The configuration, invisibly.

`conf$add_type()`: add a new config entry type to a configuration

After this the new type can be used in conf$add() calls.

Usage

conf$add_type(type_name, check, env_decode)

Arguments

type_name: type name.
check: default check function of the type. Use NULL for no checks.
env_decode: function to use to decode a value of the type from an environment variable (i.e. string).

Value

The configuration, invisibly.

R platforms

Description

default_platfoms() returns the default platforms for the current R session. These typically consist of the detected platform of the current R session, and "source", for source packages.

Usage

current_r_platform()

default_platforms()

Details

current_r_platform() detects the platform of the current R version.

By default pkgdepends works with source packages and binary packages for the current platform. You can change this, see 'Configuration'.

The following platform names can be configured and returned by current_r_platform() and default_platforms():

"source" for source packages,
A platform string like R.version$platform, but on Linux the name and version of the distribution are also included. Examples:
- x86_64-apple-darwin17.0: macOS High Sierra.
- aarch64-apple-darwin20: macOS Big Sur on arm64.
- x86_64-w64-mingw32: 64 bit Windows.
- i386-w64-mingw32: 32 bit Windows.
- i386+x86_64-w64-mingw32: 64 bit + 32 bit Windows.
- i386-pc-solaris2.10: 32 bit Solaris. (Some broken 64 Solaris builds might have the same platform string, unfortunately.)
- x86_64-pc-linux-gnu-debian-10: Debian Linux 10 on x86_64.
- ⁠x86_64-pc-linux-musl-alpine-3.14.1⁠: Alpine Linux.
- x86_64-pc-linux-gnu-unknown: Unknown Linux Distribution on x86_64.
- s390x-ibm-linux-gnu-ubuntu-20.04: Ubuntu Linux 20.04 on S390x.
- amd64-portbld-freebsd12.1: FreeBSD 12.1 on x86_64.

In addition, the following platform names can be used to configure pkgdepends:

"macos" for macOS binaries that are appropriate for the R versions pkgdepends is working with (defaulting to the version of the current session), as defined by CRAN binaries. E.g. on R 3.5.0 macOS binaries are built for macOS El Capitan.
"windows" for Windows binaries for the default CRAN architecture. This is currently Windows Vista for all supported R versions, but it might change in the future. The actual binary packages in the repository might support both 32 bit and 64 builds, or only one of them. In practice 32-bit only packages are very rare. CRAN builds before and including R 4.1 have both architectures, from R 4.2 they are 64 bit only. "windows" is an alias to i386+x86_64-w64-mingw32 currently.

Value

current_r_platform() returns a string, the name of the current platform.

default_platforms() returns a character vector of platform names.

Examples

current_r_platform()
default_platforms()

GitHub Releases

Description

Functions to query and manipulate GitHub releases. These functions are currently experimental.

Details

List releases

Description

ghr$list() lists the last 100 releases for a GitHub repository. ghr$async_list() is the async version of ghr$list().

Usage

ghr$list(repo)
ghr$async_list(repo)

Arguments

repo: repository slug, e.g. "cran/cli".

Value

Data frame with columns:

id: release id,
name: release name, usually the version number, possibly with a v prefix: ⁠3.6.1⁠ or v3.6.1, but can be different.
tag_name: usually the same as name.
created_at: POSIXct vector.

Get information about a release

Description

ghr$get() downloads information about a release, including release assets.

ghr$async_get is the async version of ghr$get.

Usage

ghr$get(repo, tag)

Arguments

repo: repository slug, e.g. "cran/cli".
tag: tag to get.

Value

Named list, see https://docs.github.com/en/rest/releases/releases#get-a-release for the entries.

List assets of a release

Description

ghr$list_assets() lists the last 100 assets of a release.

ghr$async_list_assets() is the async version of ghr$list_assets()

Usage

ghr$list_assets(repo, tag)

Arguments

repo: repository slug, e.g. "cran/cli".
tag: tag to query.

Value

Data frame with columns:

id: asset id,
name: file name of the asset,
download_url: download URL,
size: size in bytes,
created_at: POSIXct vector,
updated_at: POSXct vector,
content_type: content type of asset.

Add a release asset

Description

ghr$add_asset() adds an asset to a GitHub release.

ghr$async_add_asset() is the async version of ghr$add_asset().

Usage

ghr%add_asset(repo, file, tag, name = basename(file))

Arguments

repo: repository slug, e.g. cran/cli.
file: path to file to upload as an asset.
tag: tag name to add the asset to. It must exist on GitHub.
name: file name of the asset in the release.

Details

If an asset with the same name already exists, then that will be deleted first.

Value

Response from GitHub as a named list. See https://docs.github.com/en/rest/releases/assets#upload-a-release-asset for the structure.

Delete a release asset

Description

ghr$delete_asset() deleted a release asset.

ghr$async_delete_asset() is an async version of ghr$delete_asset().

Usage

ghr$delete_asset(repo, tag, name)
ghr$async_delete_asset(repo, tag, name)

Arguments

repo: repository slug, e.g. cran/cli.
tag: tag name to create a release for. It must exist on GitHub.
name: name of the asset.

Value

A list with entries:

release: a list with the data about the release, before the deletion. It has the same format as the return value of ghr$get().
deleted: TRUE if the asset was deleted. FALSE if the asset did not exist.

Create a GitHub release

Description

ghr$create() creates a GitHub release from a tag.

ghr$async_create() is an async version of ghr$create().

Usage

ghr$create(
  repo,
  tag,
  description = "",
  draft = FALSE,
  prerelease = FALSE,
  generage_release_notes = FALSE
)

Arguments

repo: repository slug, e.g. cran/cli.
tag: tag name to create a release for. It must exist on GitHub.
description: release description.
draft: whether to create a draft release.
prerelease: whether to create a prerelease.
generate_release_notes: whether to auto-generate release notes.

Value

Response from GitHub as a named list. See https://docs.github.com/en/rest/releases/releases#create-a-release for the structure.

Update a CRAN-like repository of binary packages at GitHub

Description

These functions are currently experimental.

Details

Update a CRAN-like repository of binary packages at GitHub

ghrepo$update() updates a binary package mirror.

Usage

ghrepo$update(
  repo,
  subdir,
  release_org = "cran",
  source_repo = "https://cran.r-project.org",
  packages = NULL
)

Arguments

repo: GitHub slug, e.g. r-hub/repos.
subdir: subdirectory in the GitHub repository, where the R package metadata should be updated. It must exist in the repository. If it does not have ⁠PACKAGES*⁠ files, then they will be created.
release_org: GitHub organization or user name where the packages will be published as releases.
source_repo: A CRAN-like repository, where source packages are taken from.
packages: A character vector of package names to add to the binary repository, in addition to updating the ones that are already there.

git protocol notes, for developers

Description

Assumptions, they might be relaxed or checked for later:

The server must speak the smart protocol, version 1 or 2. (Although I added some functions specifically for the dumb protocol, but they are pretty limited.)
We use HTTP transport, not SSH.
The server should have the shallow capability.
The server should have the filter capability if protocol version 2.
Only SHA-1 hashing is supported.

Details

Improvements needed:

DONE Tests. (Can always have more.)
DONE Use async HTTP.
DONE Support packfiles with deltas. (ofs-delta objects are still not supported.)
DONE Optionally send authorization. Already possibly in the URL.
DONE Better error messages.
Better errors for non-existing user, repository, ref, PR, etc.

Optional improvements:

Support ofs-delta objects in packfiles. Not necessarily, unless we send this capability, the server is not sending ofs-delta objects.
Make unpacking faster. It is not fast currently, with all the bit arithmetic in R. But it is already faster than a tar.gz + uncompress download from GitHub, so not really needed.

Docs and other helpful links:

Download a blob for a remote git repository

Description

Download a blob for a remote git repository

Usage

git_download_file(url, sha, output = sha)

Arguments

url

Repository URL, e.g. ⁠https://github.com/r-lib/pak.git⁠. It might include authentication information, e.g. a GitHub token.

sha

SHA hash of the blob.

output

Path where the blob will be written. It's directory is created if it does not exist.

Value

A list that corresponds to a git packfile entry, invisibly. It has entries: type (always "blob"), object (raw object, the blob itself), size, packed_size, hash.

Examples

Download a DESCRIPTION file from GitHub:

pak_repo <- "https://github.com/r-lib/pak.git"
fls <- git_list_files(pak_repo, "HEAD")
git_download_file(
  pak_repo,
  fls$files$hash[fls$files$path == "DESCRIPTION"],
  output = tmp <- tempfile()
)
readLines(tmp)[1:5]
#> [1] "Package: pak"                                                                  
#> [2] "Version: 0.3.1.9999"                                                           
#> [3] "Title: Another Approach to Package Installation"                               
#> [4] "Description: The goal of 'pak' is to make package installation faster and"     
#> [5] "    more reliable. In particular, it performs all HTTP operations in parallel,"

Get a packfile for an object from a remote git repository

Description

Get a packfile for an object from a remote git repository

Usage

git_fetch(url, sha, blobs = FALSE)

Arguments

url

Repository URL, e.g. ⁠https://github.com/r-lib/pak.git⁠. It might include authentication information, e.g. a GitHub token.

sha

SHA of the object to get.

blobs

Whether we want to download all blobs as well or not. We are still always requesting a shallow (depth = 1) clone.

Details

It uses ⁠filter blob:none⁠, so extra blobs are not downloaded, only trees.

Value

A list of git objects. Each element has entries:

type: commit, tree, blob or tag.
object: the object itself. It is a
- character scalar for commits,
- a data frame for trees, with columns: type, mode, path, hash,
- a raw vector for blobs,
- a raw vector for tags. (We could probably do better here.)

Examples

ft <- git_fetch(
  "https://github.com/r-lib/filelock.git",
  "9fdba75a62facaa3e818902f58891166e45eabe9"
)
ft
#> [[1]]
#> [[1]]$type
#> [1] "commit"
#> 
#> [[1]]$object
#> [1] "tree f92fab4f8594bd2e6c10f6f3e5dd44e556d7bb7e\nparent 7c5389719fa50e1827195771ac07c01d44ababa1\nauthor Gábor Csárdi <csardi.gabor@gmail.com> 1538733728 +0100\ncommitter Gábor Csárdi <csardi.gabor@gmail.com> 1538733728 +0100\n\nFix spelling\n"
#> 
#> [[1]]$size
#> [1] 239
#> 
#> [[1]]$packed_size
#> [1] 162
#> 
#> [[1]]$raw
#>   [1] 74 72 65 65 20 66 39 32 66 61 62 34 66 38 35 39 34 62 64 32 65 36 63 31 30
#>  [26] 66 36 66 33 65 35 64 64 34 34 65 35 35 36 64 37 62 62 37 65 0a 70 61 72 65
#>  [51] 6e 74 20 37 63 35 33 38 39 37 31 39 66 61 35 30 65 31 38 32 37 31 39 35 37
#>  [76] 37 31 61 63 30 37 63 30 31 64 34 34 61 62 61 62 61 31 0a 61 75 74 68 6f 72
#> [101] 20 47 c3 a1 62 6f 72 20 43 73 c3 a1 72 64 69 20 3c 63 73 61 72 64 69 2e 67
#> [126] 61 62 6f 72 40 67 6d 61 69 6c 2e 63 6f 6d 3e 20 31 35 33 38 37 33 33 37 32
#> [151] 38 20 2b 30 31 30 30 0a 63 6f 6d 6d 69 74 74 65 72 20 47 c3 a1 62 6f 72 20
#> [176] 43 73 c3 a1 72 64 69 20 3c 63 73 61 72 64 69 2e 67 61 62 6f 72 40 67 6d 61
#> [201] 69 6c 2e 63 6f 6d 3e 20 31 35 33 38 37 33 33 37 32 38 20 2b 30 31 30 30 0a
#> [226] 0a 46 69 78 20 73 70 65 6c 6c 69 6e 67 0a
#> 
#> [[1]]$hash
#> [1] "9fdba75a62facaa3e818902f58891166e45eabe9"
#> 
#> 
#> [[2]]
#> [[2]]$type
#> [1] "tree"
#> 
#> [[2]]$object
#>    type   mode          path                                     hash
#> 1  blob 100644 .Rbuildignore 45181a7157bdd799f225dd8d5b27a224b6a9a2d2
#> 2  blob 100644    .gitignore 9cb99ac4c7fa31d5450f62f8da3487c8a4162e96
#> 3  blob 100644   .travis.yml 85a387228f1b4a0c70d359122f487979ed5eb4a9
#> 4  blob 100644   DESCRIPTION 6013cb378eb62302ec176334b0ab4a2993da1e5e
#> 5  blob 100644       LICENSE 1fd2b3ad1dc5f2f946eae143ee3b45da36180bdd
#> 6  blob 100644      Makefile dd7836b14f4a04d20a3139c05c76b01a258ffcf3
#> 7  blob 100644     NAMESPACE 906fa2f11a0ba9b43a3e43c9b0cf840fb13dde1b
#> 8  blob 100644       NEWS.md f84230bc2ae5f2768677ee72d1085e599263c202
#> 9  tree  40000             R 9c8a4edfaff37a8ee20afe3ff0ec7e18b29b6d3e
#> 10 blob 100644    README.Rmd b270933f20b5e16c8a3b3fb3e9bf6a8cfd464ec0
#> 11 blob 100644     README.md d037742ef37ecb903a55d7484cfa30f725085162
#> 12 blob 100644  appveyor.yml 6168ec3805795bd92657ee8bc0208931f4b807d1
#> 13 tree  40000          inst 22c1c69cb093311abb2983012e26bbc20e9fe753
#> 14 tree  40000           man 674f6be38465d83b3f8b44d97bab040ff84b4794
#> 15 tree  40000           src abeb2f2376694746a00797a2c20df24daea66ba3
#> 16 tree  40000         tests 00ad597f0ec5aa7aab56afce1088d67685ef7395
#> 
#> [[2]]$size
#> [1] 566
#> 
#> [[2]]$packed_size
#> [1] 505
#> 
#> [[2]]$raw
#>   [1] 31 30 30 36 34 34 20 2e 52 62 75 69 6c 64 69 67 6e 6f 72 65 00 45 18 1a 71
#>  [26] 57 bd d7 99 f2 25 dd 8d 5b 27 a2 24 b6 a9 a2 d2 31 30 30 36 34 34 20 2e 67
#>  [51] 69 74 69 67 6e 6f 72 65 00 9c b9 9a c4 c7 fa 31 d5 45 0f 62 f8 da 34 87 c8
#>  [76] a4 16 2e 96 31 30 30 36 34 34 20 2e 74 72 61 76 69 73 2e 79 6d 6c 00 85 a3
#> [101] 87 22 8f 1b 4a 0c 70 d3 59 12 2f 48 79 79 ed 5e b4 a9 31 30 30 36 34 34 20
#> [126] 44 45 53 43 52 49 50 54 49 4f 4e 00 60 13 cb 37 8e b6 23 02 ec 17 63 34 b0
#> [151] ab 4a 29 93 da 1e 5e 31 30 30 36 34 34 20 4c 49 43 45 4e 53 45 00 1f d2 b3
#> [176] ad 1d c5 f2 f9 46 ea e1 43 ee 3b 45 da 36 18 0b dd 31 30 30 36 34 34 20 4d
#> [201] 61 6b 65 66 69 6c 65 00 dd 78 36 b1 4f 4a 04 d2 0a 31 39 c0 5c 76 b0 1a 25
#> [226] 8f fc f3 31 30 30 36 34 34 20 4e 41 4d 45 53 50 41 43 45 00 90 6f a2 f1 1a
#> [251] 0b a9 b4 3a 3e 43 c9 b0 cf 84 0f b1 3d de 1b 31 30 30 36 34 34 20 4e 45 57
#> [276] 53 2e 6d 64 00 f8 42 30 bc 2a e5 f2 76 86 77 ee 72 d1 08 5e 59 92 63 c2 02
#> [301] 34 30 30 30 30 20 52 00 9c 8a 4e df af f3 7a 8e e2 0a fe 3f f0 ec 7e 18 b2
#> [326] 9b 6d 3e 31 30 30 36 34 34 20 52 45 41 44 4d 45 2e 52 6d 64 00 b2 70 93 3f
#> [351] 20 b5 e1 6c 8a 3b 3f b3 e9 bf 6a 8c fd 46 4e c0 31 30 30 36 34 34 20 52 45
#> [376] 41 44 4d 45 2e 6d 64 00 d0 37 74 2e f3 7e cb 90 3a 55 d7 48 4c fa 30 f7 25
#> [401] 08 51 62 31 30 30 36 34 34 20 61 70 70 76 65 79 6f 72 2e 79 6d 6c 00 61 68
#> [426] ec 38 05 79 5b d9 26 57 ee 8b c0 20 89 31 f4 b8 07 d1 34 30 30 30 30 20 69
#> [451] 6e 73 74 00 22 c1 c6 9c b0 93 31 1a bb 29 83 01 2e 26 bb c2 0e 9f e7 53 34
#> [476] 30 30 30 30 20 6d 61 6e 00 67 4f 6b e3 84 65 d8 3b 3f 8b 44 d9 7b ab 04 0f
#> [501] f8 4b 47 94 34 30 30 30 30 20 73 72 63 00 ab eb 2f 23 76 69 47 46 a0 07 97
#> [526] a2 c2 0d f2 4d ae a6 6b a3 34 30 30 30 30 20 74 65 73 74 73 00 00 ad 59 7f
#> [551] 0e c5 aa 7a ab 56 af ce 10 88 d6 76 85 ef 73 95
#> 
#> [[2]]$hash
#> [1] "f92fab4f8594bd2e6c10f6f3e5dd44e556d7bb7e"
#> 
#> 
#> [[3]]
#> [[3]]$type
#> [1] "tree"
#> 
#> [[3]]$object
#>   type   mode         path                                     hash
#> 1 blob 100644 assertions.R c6931259482e745c75d48325f23dc2fcd06f56ff
#> 2 blob 100644    package.R 88554b8a205c4005d6f7025c21463a8182f458ab
#> 
#> [[3]]$size
#> [1] 77
#> 
#> [[3]]$packed_size
#> [1] 81
#> 
#> [[3]]$raw
#>  [1] 31 30 30 36 34 34 20 61 73 73 65 72 74 69 6f 6e 73 2e 52 00 c6 93 12 59 48
#> [26] 2e 74 5c 75 d4 83 25 f2 3d c2 fc d0 6f 56 ff 31 30 30 36 34 34 20 70 61 63
#> [51] 6b 61 67 65 2e 52 00 88 55 4b 8a 20 5c 40 05 d6 f7 02 5c 21 46 3a 81 82 f4
#> [76] 58 ab
#> 
#> [[3]]$hash
#> [1] "9c8a4edfaff37a8ee20afe3ff0ec7e18b29b6d3e"
#> 
#> 
#> [[4]]
#> [[4]]$type
#> [1] "tree"
#> 
#> [[4]]$object
#>   type   mode     path                                     hash
#> 1 blob 100644 WORDLIST 538ab5ce786efef03728f2a5b4592a6ae99c35e5
#> 
#> [[4]]$size
#> [1] 36
#> 
#> [[4]]$packed_size
#> [1] 45
#> 
#> [[4]]$raw
#>  [1] 31 30 30 36 34 34 20 57 4f 52 44 4c 49 53 54 00 53 8a b5 ce 78 6e fe f0 37
#> [26] 28 f2 a5 b4 59 2a 6a e9 9c 35 e5
#> 
#> [[4]]$hash
#> [1] "22c1c69cb093311abb2983012e26bbc20e9fe753"
#> 
#> 
#> [[5]]
#> [[5]]$type
#> [1] "tree"
#> 
#> [[5]]$object
#>   type   mode    path                                     hash
#> 1 blob 100644 lock.Rd c3899949a3573e8ad670610ba389812dd3c9bc90
#> 
#> [[5]]$size
#> [1] 35
#> 
#> [[5]]$packed_size
#> [1] 44
#> 
#> [[5]]$raw
#>  [1] 31 30 30 36 34 34 20 6c 6f 63 6b 2e 52 64 00 c3 89 99 49 a3 57 3e 8a d6 70
#> [26] 61 0b a3 89 81 2d d3 c9 bc 90
#> 
#> [[5]]$hash
#> [1] "674f6be38465d83b3f8b44d97bab040ff84b4794"
#> 
#> 
#> [[6]]
#> [[6]]$type
#> [1] "tree"
#> 
#> [[6]]$object
#>   type   mode               path                                     hash
#> 1 blob 100644           Makevars 945ce829c1bc15a9924342767db832184bea2fe7
#> 2 blob 100644       Makevars.win 1f37ea58dd205928e3f499c6e1db91460e220f9c
#> 3 blob 100644    filelock-unix.c 0ecfc663a398a9136ef1e5173f0565a8f733544c
#> 4 blob 100644 filelock-windows.c f1e4aae78e81a193ea6a87b7f465bce0eb98d761
#> 5 blob 100644         filelock.h 4aec0dd604f36863d81e693a1424bcf8388397ba
#> 6 blob 100644             init.c 2fd89e49f397d31cfd33e895f03d598c7eeca119
#> 7 blob 100644         locklist.c 810c2ea35d59f0336b66ab4f5d31a301e4049b85
#> 8 blob 100644             utf8.c 47849fb8467b37da6620ef1a714894142a851139
#> 
#> [[6]]$size
#> [1] 309
#> 
#> [[6]]$packed_size
#> [1] 259
#> 
#> [[6]]$raw
#>   [1] 31 30 30 36 34 34 20 4d 61 6b 65 76 61 72 73 00 94 5c e8 29 c1 bc 15 a9 92
#>  [26] 43 42 76 7d b8 32 18 4b ea 2f e7 31 30 30 36 34 34 20 4d 61 6b 65 76 61 72
#>  [51] 73 2e 77 69 6e 00 1f 37 ea 58 dd 20 59 28 e3 f4 99 c6 e1 db 91 46 0e 22 0f
#>  [76] 9c 31 30 30 36 34 34 20 66 69 6c 65 6c 6f 63 6b 2d 75 6e 69 78 2e 63 00 0e
#> [101] cf c6 63 a3 98 a9 13 6e f1 e5 17 3f 05 65 a8 f7 33 54 4c 31 30 30 36 34 34
#> [126] 20 66 69 6c 65 6c 6f 63 6b 2d 77 69 6e 64 6f 77 73 2e 63 00 f1 e4 aa e7 8e
#> [151] 81 a1 93 ea 6a 87 b7 f4 65 bc e0 eb 98 d7 61 31 30 30 36 34 34 20 66 69 6c
#> [176] 65 6c 6f 63 6b 2e 68 00 4a ec 0d d6 04 f3 68 63 d8 1e 69 3a 14 24 bc f8 38
#> [201] 83 97 ba 31 30 30 36 34 34 20 69 6e 69 74 2e 63 00 2f d8 9e 49 f3 97 d3 1c
#> [226] fd 33 e8 95 f0 3d 59 8c 7e ec a1 19 31 30 30 36 34 34 20 6c 6f 63 6b 6c 69
#> [251] 73 74 2e 63 00 81 0c 2e a3 5d 59 f0 33 6b 66 ab 4f 5d 31 a3 01 e4 04 9b 85
#> [276] 31 30 30 36 34 34 20 75 74 66 38 2e 63 00 47 84 9f b8 46 7b 37 da 66 20 ef
#> [301] 1a 71 48 94 14 2a 85 11 39
#> 
#> [[6]]$hash
#> [1] "abeb2f2376694746a00797a2c20df24daea66ba3"
#> 
#> 
#> [[7]]
#> [[7]]$type
#> [1] "tree"
#> 
#> [[7]]$object
#>   type   mode       path                                     hash
#> 1 blob 100644 testthat.R ba0c4a16402c81fcf9e23f5435e2f3dc00726805
#> 2 tree  40000   testthat 70486852bb6531d18f3ec76170ded201e320bbd8
#> 
#> [[7]]$size
#> [1] 73
#> 
#> [[7]]$packed_size
#> [1] 74
#> 
#> [[7]]$raw
#>  [1] 31 30 30 36 34 34 20 74 65 73 74 74 68 61 74 2e 52 00 ba 0c 4a 16 40 2c 81
#> [26] fc f9 e2 3f 54 35 e2 f3 dc 00 72 68 05 34 30 30 30 30 20 74 65 73 74 74 68
#> [51] 61 74 00 70 48 68 52 bb 65 31 d1 8f 3e c7 61 70 de d2 01 e3 20 bb d8
#> 
#> [[7]]$hash
#> [1] "00ad597f0ec5aa7aab56afce1088d67685ef7395"
#> 
#> 
#> [[8]]
#> [[8]]$type
#> [1] "tree"
#> 
#> [[8]]$object
#>   type   mode   path                                     hash
#> 1 blob 100644 test.R c1ec36f67434b9e03524180ed3646121ec03e113
#> 
#> [[8]]$size
#> [1] 34
#> 
#> [[8]]$packed_size
#> [1] 43
#> 
#> [[8]]$raw
#>  [1] 31 30 30 36 34 34 20 74 65 73 74 2e 52 00 c1 ec 36 f6 74 34 b9 e0 35 24 18
#> [26] 0e d3 64 61 21 ec 03 e1 13
#> 
#> [[8]]$hash
#> [1] "70486852bb6531d18f3ec76170ded201e320bbd8"

List files in a remote git repository

Description

List files in a remote git repository

Usage

git_list_files(url, ref = "HEAD")

Arguments

url

Repository URL, e.g. ⁠https://github.com/r-lib/pak.git⁠. It might include authentication information, e.g. a GitHub token.

ref

Either a SHA or a ref name. It may also be a branch name without the refs/heads prefix, or a partial (but unique) SHA of at least seven hexadecimal digits. See git_list_refs() for how branches, tags and GitHub pull requests are named.

Value

A list with entries:

ref: The ref the function was called with.
sha: SHA of ref.
commit: named character vector of the data of the commit object belonging to ref. It has fields named: tree, parent, author, committer, encoding, message.
tree: SHA of the tree object belonging to commit.
files: a data frame of files and directories. It has columns:
- hash: SHA hash of the tree or blob.
- type: Either "tree" or "blob".
- mode: Unix mode.
- path: Relative path from the repository's root directory.

Examples

fls <- git_list_files("https://github.com/r-lib/pak.git", "refs/heads/main")
fls$files
#>                                         hash type   mode
#> 1   78637c7741f1d05b867e6380b39841f1cc93c6ae blob 100644
#> 2   09365afed2c2de2690f0a2242998b429a74385ee tree  40000
#> 3   2d19fc766d98a08d9d1437896bfb008a7b15f340 blob 100644
#> 4   3e048b6fbe23121b71a8b6e49d78c75b8a211ced tree  40000
#> 5   9b71b7d8638f643f41d9d2eb13017ce72bb60134 blob 100644
#> 6   d906b2bad68d3d516127d003f005a5ccef912235 blob 100644
#> 7   2718673d32485ebc9a92c2b6dfde4e444ab55e7a blob 100644
#> 8   b9f2c86fd564d49bb17b3c5001f8fc3889172e14 blob 100644
#> 9   27a004b785b382edc66d48a4e23d03a255d5de5c blob 100644
#> 10  0d8d414b0375b28538cdf8389691fe2fecfbd47e blob 100644
#> 11  97271eb29faf3b1cecb81f5f7e7caf732c380bc4 blob 100644
#> 12  4b65418291f5c25e76750e3506a05430f623f73f blob 100644
#> 13  02fe05be5eaedabc818c6a3a4494b86561146815 blob 100644
#> 14  398a86d33a97dda48ddf5d8d775a3acab11bd02f blob 100644
#> 15  e0871627c1a339b113f3c37b558c1d9c361d0613 blob 100644
#> 16  ab25a2db01855917a3cee50cba8dcbbdff008e27 blob 100644
#> 17  b464e4652c292e274d1557a59ccf77c31ff1d0ea blob 100644
#> 18  16634163e7dd63b68dde40f6d33a368c0f52ad7b tree  40000
#> 19  cc0b4c1a148451aed7508a6dceef65734e1e81ae blob 100644
#> 20  d992e9f19ef2cdae01f31a59a4c5c2ca42e8bc6e blob 100644
#> 21  ddee0eaff1186dc75bd892ceeb4bb6a763553dbd blob 100644
#> 22  34860cf4adecb83d71e481dce5377c56c7aff53d blob 100644
#> 23  0e5cae27866cdd3dbb334c2d756b120f74d3acf2 blob 100644
#> 24  8d7b0b5e9ed3f6c183fd8ca9b8639156bd6568f9 blob 100644
#> 25  c45156b7dcf689e2bec9c38fa7760c04c665489c blob 100644
#> 26  bbad5095b4f5da6707fe7636a26d0cbe3b76f562 blob 100644
#> 27  d2236e702180ce578b7af8c10ff22a73f47bac5c blob 100644
#> 28  e8df0e553f1235e493264cf2b66981772de10f71 blob 100644
#> 29  5e3f4c049761c50c636d02f0c7214f84c3155302 blob 100644
#> 30  c6a2c28489f590160a7e75a18b910b6d0834ab4c blob 100644
#> 31  09123886d32910c815f53809098e09304518420f blob 100644
#> 32  07e5117d02d56f17864435cb4711d44c9b402d77 blob 100644
#> 33  8b4046c479b3ef98e995c898a20ade4280eb0838 blob 100644
#> 34  6d0209d93f8e87c08c038e9ddffba176294369a3 blob 100644
#> 35  2b615ee9e1f062391280476a558f65edb7a7908e blob 100644
#> 36  9f6edd092486f92a080df8b6712f503fd7824193 blob 100644
#> 37  3b46adf93274cfc402f3a24abb123101ce401a8e blob 100644
#> 38  8e7d159dbdc6ae2f2cd021576c62de37d0407633 blob 100644
#> 39  3cf6e5a441eb00a227a98a2b0c32da7e34dd8d52 blob 100644
#> 40  f277587288a01b20b1b896b70b59fc0ca4422428 blob 100644
#> 41  23bc3da8517a75db4ad69e30f7e79f6da52b4758 blob 100644
#> 42  40f6f0162de3172cd27b140809a91da2f61f1499 blob 100644
#> 43  3356ee4bb7ef406f1103669be14b5df4368dfe9b blob 100644
#> 44  a8ade609dd10a9da209277238e3d5fba586918be blob 100644
#> 45  db30fdc8f45f09108b2e543027f9b4532797a1a7 blob 100644
#> 46  8ebbddd4fa5fec9941ac149b442aa2ead1df6b54 blob 100644
#> 47  99fa806f2a20f2e31d0c5fda57296cde323b2ed0 blob 100644
#> 48  ece743c56ec87c879f8feae78b369dc74fafa903 blob 100644
#> 49  c91a1ebf5bd3a065fab680e19e06a9a2fb361169 blob 100644
#> 50  435614511f3e6fb4f3ce083eda7a5fd708aa16d5 blob 100644
#> 51  062b171dfe9761cc1b6fef5dcdebdfb54a455484 blob 100644
#> 52  db73a46218520379d4a322c26fec19a68f802fbb blob 100644
#> 53  7d168c39d4a6d7bcc08216d5cdd69d32c10544ee blob 100644
#> 54  2e2f5dd3d7e95a8efe14b66ee11f71b3d4b2dff1 blob 100644
#> 55  ca48de1b748b8cd82fe6251cdf67e9dcc02d1e12 blob 100644
#> 56  ba16de3e25c0b98d1d7d1fcaf1cd5ed377d46975 blob 100644
#> 57  391e1fa7b5334b8c4ec7609b1cb7428cdb4602e7 blob 100644
#> 58  34509a42215e00f1a2b2e83eebe52d8433451dd6 blob 100644
#> 59  351c3e7bc9eae89276958ab699d2aec059650c12 blob 100644
#> 60  0adcdf2b124cbced9bf4b2ba3aa373e35db7ad8a blob 100644
#> 61  a351cb8fa452aa7a3d5219be475795c9dbf81a78 blob 100644
#> 62  597abaccad4473498e2ae58c2521d35e0c699bd6 blob 100755
#> 63  04c55859903c1a7db8ce30f4a37f144795cce7c4 blob 100644
#> 64  a6fbe0b30e28e44255d7bb7860e155a235062c9a blob 100755
#> 65  994f9fdcd999611bc799761323fba728edf79389 blob 100644
#> 66  025b39ee265412d822f515f991ce81d39d52cb8b tree  40000
#> 67  cdf512b63d1e4709f538107ad9bdfec0828e56b8 blob 100644
#> 68  f6138ff9081cd95a7d18801e1d89c5f04e5866f1 tree  40000
#> 69  c3b2104e779ca5ca3a79ee69fc7d1041cbe977f6 blob 100644
#> 70  99d774f214e479cfb5d63055afa8fbcb583111f2 blob 100644
#> 71  e8e94bf558013a41dca7de2200ffb2daa3c46770 tree  40000
#> 72  a82fed0623dc0a20a0ccfceb0baceda61144801a blob 100644
#> 73  d6459e005434a49a66a3ddec92279a86160ad71f blob 100644
#> 74  ba11122d4ef6842a3901dfe4f08b9e91aadf1bfb blob 100644
#> 75  25b6e2293346439646077441c41ffc77c20fad1d blob 100644
#> 76  e3b63731626da84ef1f4af9d63c5284408629b4c blob 100644
#> 77  a8afa85ec5c8fd965b74e31a9267e20ad75f5243 blob 100644
#> 78  c32822a40b4a26156da35265d219e15b1b8ba51b blob 100644
#> 79  4c1a1aeb066f22b0ec1f71ae0b42dc9c686b899b tree  40000
#> 80  19a17499e520a9040d13cdb46c98605b4ec21b9d blob 100644
#> 81  fbd95956ddddff2c33a7095103d7a3435b837fdc tree  40000
#> 82  6c613005a2b2b5b1892f2220888c625f992d29ee blob 100644
#> 83  88302306891209038aa0d25f3e5bf5002812e086 blob 100644
#> 84  ab19d1cc3798b651f02a28ceb2cd00cd432207b6 blob 100644
#> 85  621ab042b5c98815ce2eaa25f65eaed1851d6d05 blob 100644
#> 86  c5b9874a2f342052f690e622163d7fa202439dcf blob 100644
#> 87  bb7c1c80e1675267d35174a3c7af47c1132b142b blob 100644
#> 88  95c7c05cd177ad28aa6a1fa00d5b67d2cf954077 tree  40000
#> 89  4d3a18e1abbc29f0facacb0e48e2c00cc3113e16 blob 100644
#> 90  863a64ce1d9c96ba0dc0a7d1832f9c9fb0e9f0ee blob 100644
#> 91  a16a6b75c8a0c73ac56d3f851de1d5ce3e3e97a2 blob 100644
#> 92  d26b353c949e4720978a24f847a5488422b23ab7 blob 100644
#> 93  57e26c7eeccb26cec849f3de52e640fb81076013 blob 100644
#> 94  4071a5a590525325930c0242bfd1f33503bf195c blob 100644
#> 95  2f7049ae7f268d4185333718813e23895ab769ea blob 100644
#> 96  65304a330f52028b5622f227502267a6f1cadcdd blob 100644
#> 97  bc278d72b4f342585d3a9dc4a15dab610298c58e blob 100644
#> 98  51cd88fcf36a1a40da3d5c4ed9739e5047230de7 blob 100644
#> 99  3b20bab9000d791e1991947ac5525b141c5b5dd8 blob 100644
#> 100 9836125cb5dc016f22c6cdea72edfec7477f968d blob 100644
#> 101 6ff2166291d7e9514cb7561b4dd6f59adf9ffa1b blob 100644
#> 102 379c0aa9015ff343d73da8ec37f39fe60f275e21 blob 100644
#> 103 e206c9ea9faabc2c765fe08df489861cfb13273a blob 100644
#> 104 7220d3271aa842edf6d21fc74ca08763a29ddf9a blob 100644
#> 105 c41dd490b63048c5c763a94ff8bfba1be1913dde blob 100644
#> 106 f7bb775c4cdb68b6e3dfeb6bf81246028559f812 blob 100644
#> 107 f657cb12851b53427e799ed39810d0f6cccf8721 blob 100644
#> 108 f74333c25f4691082e1dca8a68f8893a0961f975 blob 100644
#> 109 8a66ec44325a69c96b6409e1d680f934db005a9f blob 100644
#> 110 c5514b382cc5acb15fd55bf65bc3cf57343ed442 blob 100644
#> 111 c75bf73c8a095046862ff2d88cc00bda55c964ba blob 100644
#> 112 3b34b39ffbf4459bfb61f26f10bac2c37d067a74 blob 100644
#> 113 5c40d48c034b2c140b411cc97249cbc29928e3d5 tree  40000
#> 114 ec5c3152480c860a7891341f922352cbd2578c49 blob 100644
#> 115 779824c68264b03ca1b370493c68935c05111dd0 blob 100644
#> 116 64d294582713e9179c5021027699e3cbf0e2064f blob 100644
#> 117 945355ddf0b1a401b43d2587871eecef560ccb87 blob 100644
#> 118 14ebcc4bf98a8df856723a58b30715a474f79683 blob 100644
#> 119 0f290b95d53ce469fe776d2d9e49826b658c98a8 blob 100644
#> 120 21a2426182a8685d40ef20e2641d8f81fd700db8 blob 100644
#> 121 6570312475be4e1a077725cccf3c48af49d89ed5 blob 100644
#> 122 0c107388edf8276ddb41345ae12800af4f10861f blob 100644
#> 123 933f9c94ee403ef0abd8c35c9ef5f73b47ebfeee blob 100644
#> 124 feec47fafdf68fb5252d4f7068977e9a17d6df44 blob 100644
#> 125 ab3ad9618f073b704509fb6db338164c09e652f0 blob 100644
#> 126 606507c0cbc321dac5da2faebc3f687160310725 blob 100644
#> 127 0c6844a99c5f86a1f992061f77a1bf0e5be5185f blob 100644
#> 128 10eee6579377f6c1bbd4f2816a171777105dd935 blob 100644
#> 129 34ae0b70c57113e27cd8570aeaccdb75d0d7aa10 blob 100644
#> 130 902d269ac9e6ed617245785eafcf86097683b080 blob 100644
#> 131 56bd4dded11a76997485fbb42670194c4b6af022 blob 100644
#> 132 c77ac48379e2b00d18f6091ca459fbadd7cc9bd7 blob 100644
#> 133 45ccd98504cf1334c36930ec6adf4bcb87b07454 blob 100644
#> 134 11c167b9d57d7f8e6da22a991c8cff651d7ddf95 blob 100644
#> 135 4e631fe83ce7a46b4bf6d5ac890e6d2551f714d8 blob 100644
#> 136 b71efd8f0f61d95e8ada1088b3be41743a4b8b3e blob 100644
#> 137 1ef531fdc641016b347eb39ae7a4d31af30c541f blob 100644
#> 138 4a48f62c7f735c48ef4c93e0b79a4e7eb40d9f42 blob 100644
#> 139 721eb3e08884c2bfca365183d80ed24ad1dcd6f3 tree  40000
#> 140 2bb9ea0544508dcf9d419bf976bf6e0b9ca249cb blob 100644
#> 141 270314b87d171300f76501b32e8a0354926d9c84 blob 100644
#> 142 261949d09b1fb399b89e48430f5ca18d3a41b34a tree  40000
#> 143 65d5e8e273c120c2bfe0f73a3a4a934e5c81c7eb blob 100644
#> 144 b556efa9133831e2c7fd52092b4b9b74d5b5234f tree  40000
#> 145 9043e8f13610b5e4d25b3520959704058e8df210 tree  40000
#> 146 53589d891b748348206f5b3660a2eab2cfad868e blob 100644
#> 147 ee1b568a9714489e1f2afe58af5517402dd67288 blob 100644
#> 148 93cdf17fc1fc85b62e344dee549e6679c15daf1f blob 100644
#> 149 669cbd2f5b3c5c493f3139d2731b8a0ff52e4dc4 blob 100644
#> 150 e64a41a84776f9d52a4016f1363f648c3403621b blob 100644
#> 151 0ff31ac05c572f1b797faa1de823bbf64a156773 blob 100644
#> 152 7083b82932c1df6117ed4348a6b75eba0210e9e6 blob 100644
#> 153 ab41d001d7a5b8a0e6ebead68844106b905add60 blob 100644
#> 154 bf707418d737259ecdefeee50358f4b904b6b2c6 blob 100644
#> 155 63c494c86d0721196c560f2abb05ed5def1bf5bf blob 100644
#> 156 01b5f065f869e4dd302c86983d76fc5561f61d46 blob 100644
#> 157 1cb24179f61be7f6257c505b0ef8e64a6666d8c7 blob 100644
#> 158 9448734642b391308c0cc142d2ea2c5eee5e58ac blob 100644
#> 159 071c6c4c9c83d52c3609f31ffd8b25333308ca2d tree  40000
#> 160 cc96b41c901541add156a02c39dbfda0ff1cb898 tree  40000
#> 161 552a325bc9790007ec52353c33d03e57ad263978 tree  40000
#> 162 0ce1318498219e9783606b303c90cf2fc893369d blob 100644
#> 163 49e8e97903bde8a58026712473021d5d3ff17da7 blob 100644
#> 164 088477679097737cccdc1bd46d90b577b88a4817 blob 100644
#> 165 9811c5c118d9d190eee3d605bb38c42cf6a3f3d9 blob 100644
#> 166 fc40496978d53be1e58be4a1359cc10b15d23c96 tree  40000
#> 167 58efaf8c4bfed6d3624b0e9fb1bef845951b09a9 blob 100644
#> 168 2ec0d3edc4c016a043028bd748ee09b6f8df0273 blob 100644
#> 169 f8090ad4071bf668868f50c7754ad968cf85cdbf blob 100644
#> 170 7e62ecf2bdea2bdbb1d530cf79c0d451bc9cc294 blob 100755
#> 171 165c68c868430f8129739ca53631645545f4c2bb tree  40000
#> 172 a65b41774ad52b3cc7b60496d35eaafc5da4bb16 blob 100644
#> 173 8260e0f7ee227b2fc002179bb7fe6720ddf2cb34 blob 100644
#> 174 dd8700466c8dafabf9ab08c0bc9dc6fe5ea8b82b blob 100644
#> 175 13f0120982af72c5ed254fcbb74192dc5c20a3f0 tree  40000
#> 176 9d2d50de04bfa00067b74c6d5428d266d8674a7e blob 100644
#>                                                path
#> 1                                     .Rbuildignore
#> 2                                           .github
#> 3                                .github/.gitignore
#> 4                                 .github/workflows
#> 5                .github/workflows/R-CMD-check.yaml
#> 6              .github/workflows/build-package.yaml
#> 7                      .github/workflows/build.yaml
#> 8   .github/workflows/linux-builder-containers.yaml
#> 9                    .github/workflows/nightly.yaml
#> 10                   .github/workflows/pkgdown.yaml
#> 11               .github/workflows/pr-commands.yaml
#> 12             .github/workflows/test-coverage.yaml
#> 13                                       .gitignore
#> 14                                      DESCRIPTION
#> 15                                         Makefile
#> 16                                        NAMESPACE
#> 17                                          NEWS.md
#> 18                                                R
#> 19                           R/aaa-rstudio-detect.R
#> 20                             R/build-pak-binary.R
#> 21                                        R/cache.R
#> 22                                 R/compat-vctrs.R
#> 23                                 R/confirmation.R
#> 24                           R/cran-install-order.R
#> 25                          R/default-cran-mirror.R
#> 26                                 R/deps-explain.R
#> 27                                     R/dev-mode.R
#> 28                                         R/docs.R
#> 29                               R/embed-ca-certs.R
#> 30                                    R/embed-lib.R
#> 31                                       R/errors.R
#> 32                                        R/extra.R
#> 33                                    R/formatted.R
#> 34                               R/global-handler.R
#> 35                                         R/json.R
#> 36                                      R/library.R
#> 37                                        R/local.R
#> 38                                     R/lockfile.R
#> 39                                   R/name-check.R
#> 40                                       R/onload.R
#> 41                                      R/package.R
#> 42                                  R/pak-cleanup.R
#> 43                                  R/pak-install.R
#> 44                                   R/pak-update.R
#> 45                                          R/pak.R
#> 46                                        R/print.R
#> 47                                  R/private-lib.R
#> 48                                R/push-packages.R
#> 49                                         R/repo.R
#> 50                               R/rstudio-detect.R
#> 51                            R/safe-cran-install.R
#> 52                                       R/search.R
#> 53                                   R/subprocess.R
#> 54                          R/system-requirements.R
#> 55                                    R/terminate.R
#> 56                                       R/unload.R
#> 57                                        R/utils.R
#> 58                                  R/warn-loaded.R
#> 59                                       README.Rmd
#> 60                                        README.md
#> 61                                     _pkgdown.yml
#> 62                                          cleanup
#> 63                                      codecov.yml
#> 64                                        configure
#> 65                                    configure.win
#> 66                                             data
#> 67                           data/pak_sitrep_data.R
#> 68                                             inst
#> 69                                    inst/WORDLIST
#> 70                                   inst/header.md
#> 71                                       inst/tools
#> 72                         inst/tools/pkg_1.0.0.tgz
#> 73                                   inst/tools/xxx
#> 74                               inst/tools/xxx.bz2
#> 75                                inst/tools/xxx.gz
#> 76                            inst/tools/xxx.tar.gz
#> 77                                inst/tools/xxx.xz
#> 78                               inst/tools/xxx.zip
#> 79                                              man
#> 80                                     man/cache.Rd
#> 81                                       man/chunks
#> 82                               man/chunks/FAQ.Rmd
#> 83                          man/chunks/features.Rmd
#> 84                           man/chunks/install.Rmd
#> 85                              man/chunks/tldr.Rmd
#> 86                                       man/faq.Rd
#> 87                                  man/features.Rd
#> 88                                      man/figures
#> 89                        man/figures/cran-dark.svg
#> 90                             man/figures/cran.svg
#> 91                        man/figures/deps-dark.svg
#> 92                             man/figures/deps.svg
#> 93                     man/figures/explain-dark.svg
#> 94                          man/figures/explain.svg
#> 95                          man/figures/gh-dark.svg
#> 96                               man/figures/gh.svg
#> 97                       man/figures/local-dark.svg
#> 98                            man/figures/local.svg
#> 99                        man/figures/tldr-cran.svg
#> 100                              man/get-started.Rd
#> 101                 man/handle_package_not_found.Rd
#> 102                                  man/install.Rd
#> 103                               man/lib_status.Rd
#> 104                               man/local_deps.Rd
#> 105                       man/local_deps_explain.Rd
#> 106                            man/local_install.Rd
#> 107                       man/local_install_deps.Rd
#> 108                   man/local_install_dev_deps.Rd
#> 109                      man/local_package_trees.Rd
#> 110                man/local_system_requirements.Rd
#> 111                          man/lockfile_create.Rd
#> 112                         man/lockfile_install.Rd
#> 113                                      man/macros
#> 114                              man/macros/eval.Rd
#> 115                                 man/metadata.Rd
#> 116                 man/package-dependency-types.Rd
#> 117                               man/pak-config.Rd
#> 118                                      man/pak.Rd
#> 119                              man/pak_cleanup.Rd
#> 120                        man/pak_install_extra.Rd
#> 121                      man/pak_package_sources.Rd
#> 122                                man/pak_setup.Rd
#> 123                               man/pak_sitrep.Rd
#> 124                               man/pak_solver.Rd
#> 125                               man/pak_update.Rd
#> 126                                 man/pkg_deps.Rd
#> 127                         man/pkg_deps_explain.Rd
#> 128                            man/pkg_deps_tree.Rd
#> 129                             man/pkg_download.Rd
#> 130                              man/pkg_history.Rd
#> 131                              man/pkg_install.Rd
#> 132                           man/pkg_name_check.Rd
#> 133                               man/pkg_remove.Rd
#> 134                               man/pkg_search.Rd
#> 135                               man/pkg_status.Rd
#> 136                                 man/repo_add.Rd
#> 137                                 man/repo_get.Rd
#> 138                              man/repo_status.Rd
#> 139                                     man/roxygen
#> 140                              man/roxygen/meta.R
#> 141                                       pak.Rproj
#> 142                                           tests
#> 143                                tests/testthat.R
#> 144                                  tests/testthat
#> 145                           tests/testthat/_snaps
#> 146                  tests/testthat/_snaps/print.md
#> 147                        tests/testthat/helpers.R
#> 148                          tests/testthat/setup.R
#> 149                    tests/testthat/test-bundle.R
#> 150           tests/testthat/test-create-pak-repo.R
#> 151                  tests/testthat/test-platform.R
#> 152                     tests/testthat/test-print.R
#> 153               tests/testthat/test-private-lib.R
#> 154                      tests/testthat/test-repo.R
#> 155                tests/testthat/test-subprocess.R
#> 156       tests/testthat/test-system-requirements.R
#> 157                        tests/testthat/test-ui.R
#> 158                     tests/testthat/test-utils.R
#> 159                                           tools
#> 160                                     tools/build
#> 161                               tools/build/linux
#> 162                    tools/build/linux/Dockerfile
#> 163            tools/build/linux/Dockerfile-builder
#> 164                      tools/build/linux/Makefile
#> 165              tools/build/linux/Makevars-builder
#> 166                               tools/build/macos
#> 167                    tools/build/macos/.gitignore
#> 168                      tools/build/macos/Makefile
#> 169              tools/build/macos/Makevars-curl.in
#> 170                   tools/build/macos/download.sh
#> 171                             tools/build/windows
#> 172                  tools/build/windows/.gitignore
#> 173                    tools/build/windows/Makefile
#> 174                            tools/dynamic-help.R
#> 175                                       vignettes
#> 176                         vignettes/internals.Rmd

List references in a remote git repository

Description

List references in a remote git repository

Usage

git_list_refs(url, prefixes = NULL)

Arguments

url

Repository URL, e.g. ⁠https://github.com/r-lib/pak.git⁠. It might include authentication information, e.g. a GitHub token.

prefixes

If not NULL, then only references of which one of prefixes is a prefix, are listed.

Details

Branches have references named ⁠refs/heads/<branch>⁠, e.g. refs/heads/main.
Tags have references named ⁠refs/tags/<tag>⁠, e.g. refs/tags/v1.0.2.
On GitHub pull requests have references named ⁠refs/pull/<pr-number>/head⁠, e.g. refs/pull/37/head. For open pull requests there should be a ⁠refs/pull/<pr-number>/merge⁠ reference as well, which is the branch after the pull request has been merged.
There is a special reference called HEAD. This points to the default branch on GitHub.

Value

A list with entries: refs and caps. caps is a character vector of capabilities advertised by the server. refs is a data frame of git refs, it has columns ref and hash.

Examples

git_list_refs("https://github.com/r-lib/filelock.git")
#> $refs
#>                                       ref
#> 1                                    HEAD
#> 2                   refs/heads/cran-1-0-2
#> 3  refs/heads/fix/testthat-error-parallel
#> 4                     refs/heads/gh-pages
#> 5                         refs/heads/main
#> 6                  refs/heads/refcounting
#> 7                       refs/pull/14/head
#> 8                       refs/pull/37/head
#> 9                      refs/pull/37/merge
#> 10                      refs/pull/38/head
#> 11                      refs/pull/40/head
#> 12                       refs/tags/v1.0.2
#>                                        hash
#> 1  0331c49c0b17845468b5f3e2da75680475bc9989
#> 2  dfc615b14dfc030df3f44bd377e752728f76df3d
#> 3  6f4b4bfcc1d3442d63496c7640984c0d9570a05a
#> 4  2956fbdcbab65b75e3347048a9dc18b15fe377d2
#> 5  0331c49c0b17845468b5f3e2da75680475bc9989
#> 6  48e5bbe0e031897c7f0e194edbf6897f813fbaee
#> 7  48e5bbe0e031897c7f0e194edbf6897f813fbaee
#> 8  6f4b4bfcc1d3442d63496c7640984c0d9570a05a
#> 9  74b253543f6d2e7213a8174ebbe8e397b9cc866b
#> 10 c7e58188a55844e6e75cd38cf81388c3452b1259
#> 11 10421f0b7117244002d377d7a9699c2742abdfcc
#> 12 9fdba75a62facaa3e818902f58891166e45eabe9
#> 
#> $caps
#>  [1] "multi_ack"                      "thin-pack"                     
#>  [3] "side-band"                      "side-band-64k"                 
#>  [5] "ofs-delta"                      "shallow"                       
#>  [7] "deepen-since"                   "deepen-not"                    
#>  [9] "deepen-relative"                "no-progress"                   
#> [11] "include-tag"                    "multi_ack_detailed"            
#> [13] "allow-tip-sha1-in-want"         "allow-reachable-sha1-in-want"  
#> [15] "no-done"                        "symref=HEAD:refs/heads/main"   
#> [17] "filter"                         "object-format=sha1"            
#> [19] "agent=git/github-g8119c27a9d8d"

List only references having a certain prefix:

git_list_refs("https://github.com/r-lib/filelock.git", "refs/heads/main")
#> $refs
#>               ref                                     hash
#> 1 refs/heads/main 211dde89c4974b295aa02c5c77b5570ead0fc458
#> 
#> $caps
#> [1] "version 2"                          "agent=git/github-1c5ee477c782"     
#> [3] "ls-refs=unborn"                     "fetch=shallow wait-for-done filter"
#> [5] "server-option"                      "object-format=sha1"

Various services:

git_list_refs("https://gitlab.com/Linaro/tuxmake.git", "HEAD")
#> $refs
#>    ref                                     hash
#> 1 HEAD 9441c1f6ae68148882e9d15ab2d6b3008f4c2c19
#> 
#> $caps
#> [1] "version 2"                          "agent=git/2.40.0.gl1"              
#> [3] "ls-refs=unborn"                     "fetch=shallow wait-for-done filter"
#> [5] "server-option"                      "object-format=sha1"                
#> [7] "object-info"
git_list_refs("https://bitbucket.org/gaborcsardi/cli.git")
#> $refs
#>                                        ref
#> 1                                     HEAD
#> 2                           refs/heads/ask
#> 3                    refs/heads/cran-3.0.0
#> 4                   refs/heads/cran/v3.0.1
#> 5      refs/heads/feature/cli-capabilities
#> 6   refs/heads/feature/cli-condition-width
#> 7  refs/heads/feature/format-error-options
#> 8           refs/heads/feature/rstudio-job
#> 9          refs/heads/feature/span-bullets
#> 10                refs/heads/feature/table
#> 11            refs/heads/fix/pkgdown-2.0.0
#> 12                     refs/heads/gh-pages
#> 13                         refs/heads/main
#> 14    refs/heads/use-glue-literal-argument
#> 15                        refs/tags/v1.0.1
#> 16                        refs/tags/v1.1.0
#> 17                    refs/tags/v1.1.0-pre
#> 18                        refs/tags/v2.0.0
#> 19                        refs/tags/v2.0.1
#> 20                        refs/tags/v2.0.2
#> 21                        refs/tags/v2.1.0
#> 22                        refs/tags/v2.2.0
#> 23                        refs/tags/v2.3.0
#> 24                        refs/tags/v2.3.1
#> 25                        refs/tags/v2.4.0
#> 26                        refs/tags/v2.5.0
#> 27                        refs/tags/v3.0.0
#> 28                        refs/tags/v3.0.1
#> 29                        refs/tags/v3.1.0
#>                                        hash
#> 1  928ff3e6a52a08bbabadc57027c43de13b0d7601
#> 2  736e5824c082e94fc1acc68fb604fa66b19d1826
#> 3  75f3f185c116ff69f3abd56bf89fa9032a9eb965
#> 4  722cd638ebe4529db20442962cd2d7dc56c694d7
#> 5  b6ebff6771ff9ee8e5b19f8b6c20e142182ab866
#> 6  ee931427a9ee51bdfd837bd03c22d2d60ad81946
#> 7  28d4efb9b8875e933d682285b65ab05c61f6aef2
#> 8  8ddc6e68b970f14d45af6109108b17352dc8a4e7
#> 9  bfaabf3658c229d406591b4436991e37720476cf
#> 10 0d4089fc2f6cf8c7364f02698cf257363e877660
#> 11 be878b57b6f9978953916b0a1d7272f104e27309
#> 12 928ff3e6a52a08bbabadc57027c43de13b0d7601
#> 13 f6794c4a2d845b6706a41c58f63b4acbbc663968
#> 14 5c2904c05e8f809d0136e2253e2e6ea4b7743992
#> 15 6e0ffb0de1b54953583e01068a8052ae4cbe72aa
#> 16 d4f0e8618aba3475974394075f3f5384695d1d28
#> 17 57fb26d1c4582fc73a3a8531aa534948f88e96bc
#> 18 9a133422f200f7aa0cdc78b28eb42770cdfe4b35
#> 19 31aaccbdb3904c5b681175483a95688940345725
#> 20 19f3b864f4ee04c31627a3246dbea44bc07b7967
#> 21 a914e326aea8a9ec7d07f7accd64bb624065ba8a
#> 22 e0d0668030b482c1bda1fce66db63f402c4e9c5a
#> 23 e4c9180c5b53f68c3f938473c0d5871ceefe9991
#> 24 5c0c8a88549050e156ea4469adf536e1c0ac0881
#> 25 251c84f298b46e0529dd992b9ec86da4aaaf4fa8
#> 26 17fd0dc202a51aa82a7704786712d9f77c690c4d
#> 27 df963095361d77322676260e60c549d8807ded1d
#> 28 525e785e8b34e889707bbbe354287bd4a60e8fcb
#> 29 e40cfd4eedad58c22c3e7bcfdba6f23f11a79e13
#> 
#> $caps
#>  [1] "multi_ack"                       "thin-pack"                      
#>  [3] "side-band"                       "side-band-64k"                  
#>  [5] "ofs-delta"                       "shallow"                        
#>  [7] "deepen-since"                    "deepen-not"                     
#>  [9] "deepen-relative"                 "no-progress"                    
#> [11] "include-tag"                     "multi_ack_detailed"             
#> [13] "allow-tip-sha1-in-want"          "allow-reachable-sha1-in-want"   
#> [15] "no-done"                         "symref=HEAD:refs/heads/gh-pages"
#> [17] "object-format=sha1"              "agent=git/2.32.0"
git_list_refs("https://git.savannah.nongnu.org/git/administration/savane.git")
#> $refs
#>                         ref                                     hash
#> 1                      HEAD bdfce5e39c3ebb36b748925dfc8a0cde483fda6a
#> 2           refs/heads/i18n e5f2c309b038789a82ab5a54d723a3564f1bde58
#> 3         refs/heads/master bdfce5e39c3ebb36b748925dfc8a0cde483fda6a
#> 4    refs/tags/release-3.10 e1db1a011effeb7d16a5af9c15b91d8998579ad7
#> 5 refs/tags/release-3.10^{} d16b7e7e849d5d63794b1c48847e8a57250ce2bd
#> 6    refs/tags/release-3.11 7d5723e022a7144c077501ecff5ac23984effe8d
#> 7 refs/tags/release-3.11^{} af29b8a99fe4b4e7deefb6bcbf9a6d98f43228bf
#> 
#> $caps
#>  [1] "multi_ack"                     "thin-pack"                    
#>  [3] "side-band"                     "side-band-64k"                
#>  [5] "ofs-delta"                     "shallow"                      
#>  [7] "deepen-since"                  "deepen-not"                   
#>  [9] "deepen-relative"               "no-progress"                  
#> [11] "include-tag"                   "multi_ack_detailed"           
#> [13] "no-done"                       "symref=HEAD:refs/heads/master"
#> [15] "agent=git/2.17.1"

Perform a package installation plan

Description

See 'Installation plans' for the details and the format.

Usage

install_package_plan(
  plan,
  lib = .libPaths()[[1]],
  num_workers = 1,
  cache = NULL
)

Arguments

plan

Package plan object, a data frame, see 'Installation plans' for the format.

lib

Library directory to install to.

num_workers

Number of worker processes to use.

cache

Package cache to use, or NULL.

Value

Information about the installation process.

Installation plans

Description

An installation plan contains all data that is needed to install a set of package files. It is usually created from an installation proposal with solving the dependencies and downloading the package files.

Details

It is also possible to create an installation plan a different way. An installation plan object must be a data frame, with at least the following columns:

package: The name of the package.
type: The type of the package reference.
binary: Whether the package is a binary package.
file: Full path to the package file or directory.
dependencies: A list column that lists the names of the dependent packages for each package.
needscompilation: Whether the package needs compilation. This should be FALSE for binary packages.

For installation plans created via pkg_installation_proposal, the plan contains all columns from pkg_download_result objects, and some additional ones:

library: the library the package is supposed to be installed to.
direct: whether the package was directly requested or it is installed as a dependency.
vignettes: whether the vignettes need to be (re)built.
packaged: whether ⁠R CMD build⁠ was already called for the package.

Examples

## Not run: 
pdi <- new_pkg_installation_proposal(
  "pak",
  config = list(library = tempfile())
)
pdi$resolve()
pdi$solve()
pdi$download()
pdi$get_install_plan()

## End(Not run)

Check whether a package name is valid

Description

Check whether a package name is valid

Usage

is_valid_package_name(nm)

Arguments

nm

Potential package name, string of length 1.

Value

Logical flag. If FALSE, then the reason attribute contains a character string, the explanation why the package name is invalid. See examples below.

Examples

is_valid_package_name("pak")
is_valid_package_name("pkg")
is_valid_package_name("pak\u00e1ge")
is_valid_package_name("good-package")
is_valid_package_name("x")
is_valid_package_name("1stpackage")
is_valid_package_name("dots.")

Status of packages in a library

Description

Query data of all packages in a package library.

Usage

lib_status(library = .libPaths()[1], packages = NULL)

Arguments

library

Path to library.

packages

If not NULL, then only these packages are shown.

Value

Data frame that contains data about the packages installed in the library.

It has always has columns:

biocviews: the corresponding field from DESCRIPTION, it must be present for all Bioconductor packages, other packages typically don't have it.
built: the Built field from DESCRIPTION.
depends, suggests, Imports, linkingto, enhances: the corresponding fields from the DESCRIPTION files.
deps: A list or data frames, the dependencies of the package. It has columns: ref, type (dependency type in lowercase), package (dependent package, or R), op and version, for last two are for version requirement. op can be >=, >, == or <=, although the only the first one is common in practice.
library: path to the package library containing the package.
license: from DESCRIPTION.
md5sum: from DESCTIPTION, typically NA, except on Windows.
needscompilation: from DESCRIPTION, this column is logical.
package: package name.
platform: from the Built field in DESCRIPTION, the current platform if missing from DESCRIPTION.
priority: from DESCRIPTION, usually base, recommended, or missing.
ref: the corresponding ⁠installed::*⁠ package reference.
repository: from DESCRIPTION. For packages from a CRAN repository this is CRAN, some other repositories, e.g. R-universe adds the repository URL here.
repotype: cran, bioc or missing.
rversion: from the Built field. If no such field, then the current R version.
sysreqs: the SystemRequirements field from DESCRIPTION.
title: package title.
type: always installed.
version: package version (as string).

Most of these columns are unchanged from DESCRIPTION, but pkgdepends also adds a couple.

Notes:

In addition, it also has all ⁠remote*⁠ and ⁠config/needs/*⁠ entries from the DESCRIPTION files. (Case insensitive.)
All columns are of type character, except for needscompilation, which is logical and deps, which is a list columns.
If an entry is missing for a package, it is set to NA.
Note that column names are lowercase, even if the corresponding entries are not in DESCRIPTION.
The order of the columns is not deterministic, so don't assume any order.
Additional columns might be present, these are internal for pkgdepends and should not be used in user code.

R6 class for package dependency lookup

Description

Look up dependencies of R packages from various sources.

Usage

new_pkg_deps(refs, ...)

Arguments

refs

Package names or references. See 'Package references' for the syntax.

...

Additional arguments, passed to pkg_deps$new().

Details

new_pkg_deps() creates a new object from the pkg_deps class. The advantage of new_pkg_deps() compared to using the pkg_deps constructor directly is that it avoids making pkgdepends a build time dependency.

The usual steps to query package dependencies are:

Create a pkg_deps object with new_pkg_deps().
Resolve all possible dependencies with pkg_deps$resolve().
Solve the dependencies, to obtain a subset of all possible dependencies that can be installed together, with pkg_deps$solve().
Call pkg_deps$get_solution() to list the result of the dependency solver.

Value

new_pkg_deps() returns a new pkg_deps object.

Methods

Method `new()`

Create a new pkg_deps object. Consider using new_pkg_deps() instead of calling the constructor directly.

The returned object can be used to look up (recursive) dependencies of R packages from various sources. To perform the actual lookup, you'll need to call the resolve() method.

Usage

pkg_deps$new(
  refs,
  config = list(),
  policy = c("lazy", "upgrade"),
  remote_types = NULL
)

Arguments

refs: Package names or references. See 'Package references' for the syntax.
config: Configuration options, a named list. See 'Configuration'.
policy: Solution policy. See 'The dependency solver'.
remote_types: Custom remote ref types, this is for advanced use, and experimental currently.

Returns

A new pkg_deps object.

Method `get_refs()`

The package refs that were used to create the pkg_deps object.

Usage

pkg_deps$get_refs()

Returns

A character vector of package refs that were used to create the pkg_deps object.

Method `get_config()`

Configuration options for the pkg_deps object. See 'Configuration' for details.

Usage

pkg_deps$get_config()

Returns

See 'Configuration' for the configuration entries.

Method `resolve()`

Resolve the dependencies of the specified package references. This usually means downloading metadata from CRAN and Bioconductor, unless already cached, and also from GitHub if GitHub refs were included, either directly or indirectly. See 'Dependency resolution' for details.

Usage

pkg_deps$resolve()

Returns

The pkg_deps object itself, invisibly.

Method `async_resolve()`

The same as resolve(), but asynchronous. This method is for advanced use.

Usage

pkg_deps$async_resolve()

Returns

A deferred value.

Method `get_resolution()`

Query the result of the dependency resolution. This method can be called after resolve() has completed.

Usage

pkg_deps$get_resolution()

Returns

A pkg_resolution_result object, which is also a data frame. See 'Dependency resolution' for its columns.

Method `get_solve_policy()`

Returns the current policy of the dependency solver. See 'The dependency solver' for details.

Usage

pkg_deps$get_solve_policy()

Returns

A character vector of length one.

Method `set_solve_policy()`

Set the current policy of the dependency solver. If the object already contains a solution and the new policy is different than the old policy, then the solution is deleted. See 'The dependency solver' for details.

Usage

pkg_deps$set_solve_policy(policy = c("lazy", "upgrade"))

Arguments

policy: Policy to set.

Method `solve()`

Solve the package dependencies. Out of the resolved dependencies, it works out a set of packages, that can be installed together to create a functional installation. The set includes all directly specified packages, and all required (or suggested, depending on the configuration) packages as well. It includes every package at most once. See 'The dependency solver' for details.

solve() calls resolve() automatically, if it hasn't been called yet.

Usage

pkg_deps$solve()

Returns

The pkg_deps object itself, invisibly.

Method `get_solution()`

Returns the solution of the package dependencies.

Usage

pkg_deps$get_solution()

Returns

A pkg_solution_result object, which is a list. See pkg_solution_result for details.

Method `stop_for_solution_error()`

Error if the dependency solver failed to find a consistent set of packages that can be installed together.

Usage

pkg_deps$stop_for_solution_error()

Method `draw()`

Draw a tree of package dependencies. It returns a tree object, see cli::tree(). Printing this object prints the dependency tree to the screen.

Usage

pkg_deps$draw()

Returns

A tree object from the cli package, see cli::tree().

Method `format()`

Format a pkg_deps object, typically for printing.

Usage

pkg_deps$format(...)

Arguments

...: Not used currently.

Returns

A character vector, each element should be a line in the printout.

Method `print()`

Prints a pkg_deps object to the screen. The printout includes:

The package refs.
Whether the object has the resolved dependencies.
Whether the resolution had errors.
Whether the object has the solved dependencies.
Whether the solution had errors.
Advice on which methods to call next.

See the example below.

Usage

pkg_deps$print(...)

Arguments

...: not used currently.

Returns

The pkg_deps object itself, invisibly.

Method `clone()`

The objects of this class are cloneable with this method.

Usage

pkg_deps$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

Examples


# Method initialize()
pd <- pkg_deps$new("r-lib/pkgdepends")
pd


# Method get_refs()
pd <- new_pkg_deps(c("pak", "jsonlite"))
pd$get_refs()


# Method get_config()
pd <- new_pkg_deps("pak")
pd$get_config()


# Method resolve()
pd <- new_pkg_deps("pak")
pd$resolve()
pd$get_resolution()


# Method get_resolution()
pd <- new_pkg_deps("r-lib/pkgdepends")
pd$resolve()
pd$get_resolution()


# Method get_solve_policy()
pdi <- new_pkg_deps("r-lib/pkgdepends")
pdi$get_solve_policy()
pdi$set_solve_policy("upgrade")
pdi$get_solve_policy()


# Method set_solve_policy()
pdi <- new_pkg_deps("r-lib/pkgdepends")
pdi$get_solve_policy()
pdi$set_solve_policy("upgrade")
pdi$get_solve_policy()


# Method solve()
pd <- new_pkg_deps("r-lib/pkgdepends")
pd$resolve()
pd$solve()
pd$get_solution()


# Method get_solution()
pd <- new_pkg_deps("pkgload")
pd$resolve()
pd$solve()
pd$get_solution()


# Method stop_for_solution_error()
# This is an error, because the packages conflict:
pd <- new_pkg_deps(
  c("r-lib/pak", "cran::pak"),
  config = list(library = tempfile())
)
pd$resolve()
pd$solve()
pd
# This fails:
# pd$stop_for_solution_error()


# Method draw()
pd <- new_pkg_deps("pkgload")
pd$solve()
pd$draw()


# Method print()
pd <- new_pkg_deps("r-lib/pkgdepends")
pd

pd$resolve()
pd

pd$solve()
pd

R6 class for package downloads

Description

Download packages with their dependencies, from various sources.

Usage

new_pkg_download_proposal(refs, ...)

Arguments

refs

Package names or references. See 'Package references' for the syntax.

...

Additional arguments, passed to pkg_download_proposal$new().

Details

new_pkg_download_proposal() creates a new object from the pkg_download_proposal class, that can be used to look up and download R packages and their dependencies. The advantage of new_pkg_download_proposal() compared to using the pkg_download_proposal constructor directly is that it avoids making pkgdepends a build time dependency.

Typical workflow to download a set of packages:

Create a pkg_download_proposal object with new_pkg_download_proposal().
Resolve all possible dependencies with pkg_download_proposal$resolve().
Download all files with pkg_download_proposal$download().
Get the data about the packages and downloads with pkg_download_proposal$get_downloads().

Value

new_pkg_download_proposal() returns a new pkg_download_proposal object.

Methods

Public methods

pkg_download_proposal$new()
pkg_download_proposal$get_refs()
pkg_download_proposal$get_config()
pkg_download_proposal$resolve()
pkg_download_proposal$async_resolve()
pkg_download_proposal$get_resolution()
pkg_download_proposal$download()
pkg_download_proposal$async_download()
pkg_download_proposal$get_downloads()
pkg_download_proposal$stop_for_download_error()
pkg_download_proposal$format()
pkg_download_proposal$print()
pkg_download_proposal$clone()

Method `new()`

Create a new pkg_download_proposal object. Consider using new_pkg_download_proposal() instead of calling the constructor directly.

The returned object can be used to look up (recursive) dependencies of R packages from various sources, and then to download the package files.

Usage

pkg_download_proposal$new(refs, config = list(), remote_types = NULL)

Arguments

refs

Package names or references. See 'Package references' for the syntax.

config

Configuration options, a named list. See 'Configuration'.

remote_types

Custom remote ref types, this is for advanced use, and experimental currently.

Examples

pdl <- pkg_download_proposal$new("r-lib/pkgdepends")
pdl

Method `get_refs()`

The package refs that were used to create the pkg_download_proposal object.

Usage

pkg_download_proposal$get_refs()

Returns

A character vector of package refs that were used to create the pkg_download_proposal object.

Method `get_config()`

Configuration options for the pkg_download_proposal object. See 'Configuration' for details.

Usage

pkg_download_proposal$get_config()

Returns

Named list. See 'Configuration' for the configuration options.

Method `resolve()`

Usage

pkg_download_proposal$resolve()

Returns

The pkg_download_proposal object itself, invisibly.

Method `async_resolve()`

The same as resolve(), but asynchronous. This method is for advanced use.

Usage

pkg_download_proposal$async_resolve()

Returns

A deferred value.

Method `get_resolution()`

Query the result of the dependency resolution. This method can be called after resolve() has completed.

Usage

pkg_download_proposal$get_resolution()

Returns

A pkg_resolution_result object, which is also a data frame. See 'Dependency resolution' for its columns.

Method `download()`

Download all resolved packages. It uses the package cache in the pkgcache package by default, to avoid downloads if possible.

Usage

pkg_download_proposal$download()

Returns

The pkg_download_proposal object, invisibly.

Method `async_download()`

The same as download(), but asynchronous. This method is for advanced use.

Usage

pkg_download_proposal$async_download()

Returns

A deferred value.

Method `get_downloads()`

Returns the summary of the package downloads.

Usage

pkg_download_proposal$get_downloads()

Returns

A pkg_download_result object, which is a list. See pkg_download_result for details.

Method `stop_for_download_error()`

Throw and error if the some of the downloads have failed for the most recent pkg_download_proposal$download() call.

Usage

pkg_download_proposal$stop_for_download_error()

Method `format()`

Format a pkg_download_proposal object, typically for printing.

Usage

pkg_download_proposal$format(...)

Arguments

...: not used currently.

Returns

Nothing. A character vector, each element should be a line in the printout.

Method `print()`

Prints a pkg_download_proposal object to the screen. The printout includes:

The package refs.
Whether the object has the resolved dependencies.
Whether the resolution had errors.
Whether the downloads were completed.
Whether the downloads had errors.
Advice on which methods to call next.

See the example below.

Usage

pkg_download_proposal$print(...)

Arguments

...: not used currently.

Returns

The pkg_download_proposal object itself, invisibly.

Method `clone()`

The objects of this class are cloneable with this method.

Usage

pkg_download_proposal$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

Examples


# Method get_refs()
pdl <- new_pkg_download_proposal(c("pak", "jsonlite"))
pdl$get_refs()


# Method get_config()
pdl <- new_pkg_download_proposal("pak")
pdl$get_config()


# Method resolve()
pdl <- new_pkg_download_proposal("pak")
pdl$resolve()
pdl$get_resolution()


# Method get_resolution()
pdl <- new_pkg_download_proposal("r-lib/pkgdepends")
pdl$resolve()
pdl$get_resolution()


# Method download()
pdl <- new_pkg_download_proposal("r-lib/pkgdepends")
pdl$resolve()
pdl$download()
pdl$get_downloads()


# Method get_downloads()
pdl <- new_pkg_download_proposal("pkgload")
pdl$resolve()
pdl$download()
pdl$get_downloads()


# Method print()
pdl <- new_pkg_download_proposal("r-lib/pkgdepends")
pdl

pdl$resolve()
pdl

pdl$download()
pdl

R6 class for installation from a lock file

Description

An installation plan is similar to an installation proposal (i.e. pkg_installation_proposal), but it already contains the solved dependencies, complete with download URLs.

Usage

new_pkg_installation_plan(lockfile = "pkg.lock", config = list(), ...)

Arguments

lockfile

Path to the lock file to use.

config

Configuration options, a named list. See 'Configuration'. If it does not include library, then .libPaths()[1] is added as library.

...

Additional arguments, passed to pkg_installation_plan$new().

Details

Typically you create a pkg_installation_plan object with new_pkg_installation_plan() and then call its ⁠$download()⁠ method to download the packages and then its ⁠$install()⁠ method to install them.

Value

new_pkg_installation_plan() returns a pkg_installation_plan object.

Super class

pkgdepends::pkg_installation_proposal -> pkg_installation_plan

Methods

Public methods

pkg_installation_plan$new()
pkg_installation_plan$resolve()
pkg_installation_plan$async_resolve()
pkg_installation_plan$get_solve_policy()
pkg_installation_plan$set_solve_policy()
pkg_installation_plan$solve()
pkg_installation_plan$update()
pkg_installation_plan$update_sysreqs()
pkg_installation_plan$format()
pkg_installation_plan$clone()

Inherited methods

Method `new()`

Create a new pkg_installation_plan object. Consider using new_pkg_installation_plan() instead of calling the constructor directly.

The returned object can be used to download and install packages, according to the plan.

Usage

pkg_installation_plan$new(
  lockfile = "pkg.lock",
  config = list(),
  remote_types = NULL
)

Arguments

lockfile: Path to the lock file to use.
config: Configuration options. See 'Configuration'. It needs to include the package library to install to, in library.
remote_types: Custom remote ref types, this is for advanced use, and experimental currently.

Method `resolve()`

This function is implemented for installation plans, and will error.

Usage

pkg_installation_plan$resolve()

Method `async_resolve()`

This function is implemented for installation plans, and will error.

Usage

pkg_installation_plan$async_resolve()

Method `get_solve_policy()`

Installation plans are already solved, and this method will return NA_character_, always.

Usage

pkg_installation_plan$get_solve_policy()

Method `set_solve_policy()`

This function is implemented for installation plans, and will error.

Usage

pkg_installation_plan$set_solve_policy()

Method `solve()`

This function is implemented for installation plans, and will error.

Usage

pkg_installation_plan$solve()

Method `update()`

Update the plan to the current state of the library. If the library has not changed since the plan was created, then it does nothing. If new packages have been installed, then it might not be necessary to download and install all packages in the plan.

Usage

pkg_installation_plan$update()

Details

This operation is different than creating a new proposal with the updated library, because it uses the the packages and package versions of the original plan. E.g. if the library has a newer version of a package, then ⁠$update()⁠ will downgrade it to the version in the plan.

Method `update_sysreqs()`

Update information about installed and missing system requirements.

Usage

pkg_installation_plan$update_sysreqs()

Method `format()`

Format a pkg_installation_plan object, typically for printing.

Usage

pkg_installation_plan$format(...)

Arguments

...: not used currently.

Returns

A character vector, each element should be a line in the printout.

Method `clone()`

The objects of this class are cloneable with this method.

Usage

pkg_installation_plan$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

R6 class for package download and installation.

Description

Download and install R packages, with their dependencies, from various sources.

Usage

new_pkg_installation_proposal(refs, config = list(), ...)

Arguments

refs

Package names or references. See 'Package references' for the syntax.

config

Configuration options, a named list. See 'Configuration'. If it does not include library, then .libPaths()[1] is added as library.

...

Additional arguments, passed to pkg_installation_proposal$new().

Details

new_pkg_installation_proposal() creates a new object from the pkg_installation_proposal class. The advantage of new_pkg_installation_proposal() compared to using the pkg_installation_proposal constructor directly is that it avoids making pkgdepends a build time dependency.

Typical workflow to install a set of packages:

Create a pkg_installation_proposal object with new_pkg_installation_proposal().
Resolve all possible dependencies with pkg_installation_proposal$resolve().
Solve the package dependencies, to get an installation plan, with pkg_installation_proposal$solve().
Download all files with pkg_installation_proposal$download().
Install the downloaded files with pkg_installation_proposal$install().

Value

new_pkg_installation_proposal() returns a new pkg_installation_proposal object.

Methods

Public methods

pkg_installation_proposal$new()
pkg_installation_proposal$get_refs()
pkg_installation_proposal$get_config()
pkg_installation_proposal$resolve()
pkg_installation_proposal$async_resolve()
pkg_installation_proposal$get_resolution()
pkg_installation_proposal$get_solve_policy()
pkg_installation_proposal$set_solve_policy()
pkg_installation_proposal$solve()
pkg_installation_proposal$get_solution()
pkg_installation_proposal$show_solution()
pkg_installation_proposal$get_sysreqs()
pkg_installation_proposal$show_sysreqs()
pkg_installation_proposal$stop_for_solution_error()
pkg_installation_proposal$create_lockfile()
pkg_installation_proposal$draw()
pkg_installation_proposal$download()
pkg_installation_proposal$async_download()
pkg_installation_proposal$get_downloads()
pkg_installation_proposal$stop_for_download_error()
pkg_installation_proposal$install()
pkg_installation_proposal$install_sysreqs()
pkg_installation_proposal$get_install_plan()
pkg_installation_proposal$format()
pkg_installation_proposal$print()
pkg_installation_proposal$clone()

Method `new()`

Create a new pkg_installation_proposal object. Consider using new_pkg_installation_proposal() instead of calling the constructor directly.

The returned object can be used to look up (recursive) dependencies of R packages from various sources, and then download and install the package files.

Usage

pkg_installation_proposal$new(
  refs,
  config = list(),
  policy = c("lazy", "upgrade"),
  remote_types = NULL
)

Arguments

refs: Package names or references. See 'Package references' for the syntax.
config: Configuration options, a named list. See 'Configuration'. It needs to include the package library to install to, in library.
policy: Solution policy. See 'The dependency solver'.
remote_types: Custom remote ref types, this is for advanced use, and experimental currently.

Method `get_refs()`

The package refs that were used to create the pkg_installation_proposal object.

Usage

pkg_installation_proposal$get_refs()

Returns

A character vector of package refs that were used to create the pkg_installation_proposal object.

Method `get_config()`

Configuration options for the pkg_installation_proposal object. See 'Configuration' for details.

Usage

pkg_installation_proposal$get_config()

Returns

Named list. See 'Configuration' for the configuration options.

Method `resolve()`

Usage

pkg_installation_proposal$resolve()

Returns

The pkg_installation_proposal object, invisibly.

Examples

\dontrun{
pdi <- new_pkg_installation_proposal(
  "pak",
  config = list(library = tempfile())
)

pdi$resolve()
pdi$get_resolution()
}

Method `async_resolve()`

The same as resolve(), but asynchronous. This method is for advanced use.

Usage

pkg_installation_proposal$async_resolve()

Returns

A deferred value.

Method `get_resolution()`

Query the result of the dependency resolution. This method can be called after resolve() has completed.

Usage

pkg_installation_proposal$get_resolution()

Returns

A pkg_resolution_result object, which is also a data frame. See 'Dependency resolution' for its columns.

Examples

\dontrun{
pdi <- new_pkg_installation_proposal(
  "r-lib/pkgdepends",
  config = list(library = tempfile())
)
pdi$resolve()
pdi$get_resolution()
}

Method `get_solve_policy()`

Returns the current policy of the dependency solver. See 'The dependency solver' for details.

Usage

pkg_installation_proposal$get_solve_policy()

Returns

A character vector of length one.

Method `set_solve_policy()`

Usage

pkg_installation_proposal$set_solve_policy(policy = c("lazy", "upgrade"))

Arguments

policy: Policy to set.

Method `solve()`

Usage

pkg_installation_proposal$solve()

Returns

The pkg_installation_proposal object itself, invisibly.

Examples

\dontrun{
pdi <- new_pkg_installation_proposal(
  "r-lib/pkgdepends",
  config = list(library = tempfile())
)
pdi$resolve()
pdi$solve()
pdi$get_solution()
}

Method `get_solution()`

Returns the solution of the package dependencies.

Usage

pkg_installation_proposal$get_solution()

Returns

A pkg_solution_result object, which is a list. See pkg_solution_result for details.

Examples

\dontrun{
pdi <- new_pkg_installation_proposal(
  "r-lib/pkgdepends",
  config = list(library = tempfile())
)
pdi$resolve()
pdi$solve()
pdi$get_solution()
}

Method `show_solution()`

Show the solution on the screen.

Usage

pkg_installation_proposal$show_solution(key = FALSE)

Arguments

key: Whether to show the key to the package list annotation.

Returns

A pkg_solution_result object, which is a list. See pkg_solution_result for details.

Examples

\dontrun{
pdi <- new_pkg_installation_proposal(
  "r-lib/pkgdepends",
  config = list(library = tempfile())
)
pdi$resolve()
pdi$solve()
pdi$get_solution()
pdi$show_solution()
}

Method `get_sysreqs()`

Query and categorize system requirements.

Usage

pkg_installation_proposal$get_sysreqs()

Method `show_sysreqs()`

Show system requirements for the packages in the solution.

Usage

pkg_installation_proposal$show_sysreqs()

Method `stop_for_solution_error()`

Error if the dependency solver failed to find a consistent set of packages that can be installed together.

Usage

pkg_installation_proposal$stop_for_solution_error()

Examples

\dontrun{
# This is an error, because the packages conflict:
pdi <- new_pkg_installation_proposal(
  c("r-lib/pak", "cran::pak"),
  config = list(library = tempfile())
)
pdi$resolve()
pdi$solve()
pdi
# This fails:
# pdi$stop_for_solution_error()
}

Method `create_lockfile()`

Create a lock file that contains the information to perform the installation later, possibly in another R session.

Usage

pkg_installation_proposal$create_lockfile(path = "pkg.lock", version = 1)

Arguments

path: Name of the lock file. The default is pkg.lock in the current working directory.
version: Only version 1 is supported currently.

Details

Note, since the URLs of CRAN and most CRAN-like repositories change over time, in practice you cannot perform the plan of the lock file much later. For example, binary packages of older package version are removed, and won't be found.

Similarly, for ⁠url::⁠ remote types, the URL might hold an updated version of the package, compared to when the lock file was created. Should this happen, pkgdepends prints a warning, but it will try to continue the installation. The installation might fail if the updated package has different (e.g. new) dependencies.

Currently the intended use case of lock files in on CI systems, to facilitate caching. The (hash of the) lock file provides a good key for caching systems.

Method `draw()`

Draw a tree of package dependencies. It returns a tree object, see cli::tree(). Printing this object prints the dependency tree to the screen.

Usage

pkg_installation_proposal$draw()

Returns

A tree object from the cli package, see cli::tree().

Examples

\dontrun{
pdi <- new_pkg_installation_proposal(
  "pak",
  config = list(library = tempfile())
)
pdi$resolve()
pdi$solve()
pdi$draw()
}

Method `download()`

Download all packages that are part of the solution. It uses the package cache in the pkgcache package by default, to avoid downloads if possible.

Usage

pkg_installation_proposal$download()

Returns

The pkg_installation_proposal object itself, invisibly.

Examples

\dontrun{
pdi <- new_pkg_installation_proposal(
  c("r-lib/pak", "cran::pak"),
  config = list(library = tempfile())
)
pdi$resolve()
pdi$solve()
pdi$download()
pdi$get_downloads()
}

Method `async_download()`

The same as download(), but asynchronous. This method is for advanced use.

Usage

pkg_installation_proposal$async_download()

Returns

A deferred value.

Method `get_downloads()`

Returns the summary of the package downloads.

Usage

pkg_installation_proposal$get_downloads()

Returns

A pkg_download_result object, which is a list. See pkg_download_result for details.

Examples

\dontrun{
pdi <- new_pkg_installation_proposal(
  c("r-lib/pak", "cran::pak"),
  config = list(library = tempfile())
)
pdi$resolve()
pdi$solve()
pdi$download()
pdi$get_downloads()
}

Method `stop_for_download_error()`

Throw and error if the some of the downloads have failed for the most recent pkg_installation_proposal$download() call.

Usage

pkg_installation_proposal$stop_for_download_error()

Method `install()`

Install the downloaded packages. It calls install_package_plan().

Usage

pkg_installation_proposal$install()

Returns

The return value of install_package_plan().

Method `install_sysreqs()`

Install system requirements. It does nothing if system requirements are turned off. Create an installation plan for the downloaded packages.

Usage

pkg_installation_proposal$install_sysreqs()

Method `get_install_plan()`

Usage

pkg_installation_proposal$get_install_plan()

Returns

An installation plan, see 'Installation plans' for the format.

Examples

\dontrun{
pdi <- new_pkg_installation_proposal(
  "pak",
  config = list(library = tempfile())
)
pdi$resolve()
pdi$solve()
pdi$download()
pdi$get_install_plan()
}

Method `format()`

Format a pkg_installation_proposal object, typically for printing.

Usage

pkg_installation_proposal$format(...)

Arguments

...: not used currently.

Returns

A character vector, each element should be a line in the printout.

Method `print()`

Prints a pkg_installation_proposal object to the screen.

The printout includes:

The package refs.
The policy of the dependency solver.
Whether the object has the solved dependencies.
Whether the solution had errors.
Whether the object has downloads.
Whether the downloads had errors.
Advice on which methods to call next.

See the example below.

Usage

pkg_installation_proposal$print(...)

Arguments

...: not used currently.

Returns

The pkg_installation_proposal object itself, invisibly.

Method `clone()`

The objects of this class are cloneable with this method.

Usage

pkg_installation_proposal$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

Examples

## Not run: 
pdi <- new_pkg_installation_proposal(
  "pak",
  config = list(library = tempfile())
)
pdi

pdi$resolve()
pdi

pdi$solve()
pdi

pdi$download()
pdi

## End(Not run)

pdi <- new_pkg_installation_proposal(
  "r-lib/pkgdepends",
  config = list(library = tempfile()))
pdi


pdi <- new_pkg_installation_proposal("r-lib/pkgdepends")
pdi$get_refs()


pdi <- new_pkg_installation_proposal(
  "pak",
  config = list(library = tempfile())
)
pdi$get_config()


pdi <- new_pkg_installation_proposal(
  "r-lib/pkgdepends",
  config = list(library = tempfile())
)
pdi$get_solve_policy()
pdi$set_solve_policy("upgrade")
pdi$get_solve_policy()


pdi <- new_pkg_installation_proposal(
  "r-lib/pkgdepends",
  config = list(library = tempfile())
)
pdi$get_solve_policy()
pdi$set_solve_policy("upgrade")
pdi$get_solve_policy()


# Method print
pdi <- new_pkg_installation_proposal(
  "pak",
  config = list(library = tempfile())
)
pdi

pdi$resolve()
pdi

pdi$solve()
pdi

pdi$download()
pdi


## ------------------------------------------------
## Method `pkg_installation_proposal$resolve`
## ------------------------------------------------

## Not run: 
pdi <- new_pkg_installation_proposal(
  "pak",
  config = list(library = tempfile())
)

pdi$resolve()
pdi$get_resolution()

## End(Not run)

## ------------------------------------------------
## Method `pkg_installation_proposal$get_resolution`
## ------------------------------------------------

## Not run: 
pdi <- new_pkg_installation_proposal(
  "r-lib/pkgdepends",
  config = list(library = tempfile())
)
pdi$resolve()
pdi$get_resolution()

## End(Not run)

## ------------------------------------------------
## Method `pkg_installation_proposal$solve`
## ------------------------------------------------

## Not run: 
pdi <- new_pkg_installation_proposal(
  "r-lib/pkgdepends",
  config = list(library = tempfile())
)
pdi$resolve()
pdi$solve()
pdi$get_solution()

## End(Not run)

## ------------------------------------------------
## Method `pkg_installation_proposal$get_solution`
## ------------------------------------------------

## Not run: 
pdi <- new_pkg_installation_proposal(
  "r-lib/pkgdepends",
  config = list(library = tempfile())
)
pdi$resolve()
pdi$solve()
pdi$get_solution()

## End(Not run)

## ------------------------------------------------
## Method `pkg_installation_proposal$show_solution`
## ------------------------------------------------

## Not run: 
pdi <- new_pkg_installation_proposal(
  "r-lib/pkgdepends",
  config = list(library = tempfile())
)
pdi$resolve()
pdi$solve()
pdi$get_solution()
pdi$show_solution()

## End(Not run)

## ------------------------------------------------
## Method `pkg_installation_proposal$stop_for_solution_error`
## ------------------------------------------------

## Not run: 
# This is an error, because the packages conflict:
pdi <- new_pkg_installation_proposal(
  c("r-lib/pak", "cran::pak"),
  config = list(library = tempfile())
)
pdi$resolve()
pdi$solve()
pdi
# This fails:
# pdi$stop_for_solution_error()

## End(Not run)

## ------------------------------------------------
## Method `pkg_installation_proposal$draw`
## ------------------------------------------------

## Not run: 
pdi <- new_pkg_installation_proposal(
  "pak",
  config = list(library = tempfile())
)
pdi$resolve()
pdi$solve()
pdi$draw()

## End(Not run)

## ------------------------------------------------
## Method `pkg_installation_proposal$download`
## ------------------------------------------------

## Not run: 
pdi <- new_pkg_installation_proposal(
  c("r-lib/pak", "cran::pak"),
  config = list(library = tempfile())
)
pdi$resolve()
pdi$solve()
pdi$download()
pdi$get_downloads()

## End(Not run)

## ------------------------------------------------
## Method `pkg_installation_proposal$get_downloads`
## ------------------------------------------------

## Not run: 
pdi <- new_pkg_installation_proposal(
  c("r-lib/pak", "cran::pak"),
  config = list(library = tempfile())
)
pdi$resolve()
pdi$solve()
pdi$download()
pdi$get_downloads()

## End(Not run)

## ------------------------------------------------
## Method `pkg_installation_proposal$get_install_plan`
## ------------------------------------------------

## Not run: 
pdi <- new_pkg_installation_proposal(
  "pak",
  config = list(library = tempfile())
)
pdi$resolve()
pdi$solve()
pdi$download()
pdi$get_install_plan()

## End(Not run)

Parse package location references

Description

See pkg_refs for more about supported package references.

Usage

parse_pkg_refs(refs, remote_types = NULL, ...)

parse_pkg_ref(ref, remote_types = NULL, ...)

Arguments

refs

Character vector of references.

remote_types

Custom remote types can be added here, this is for advanced use, and experimental currently.

...

Additional arguments are passed to the individual parser functions.

ref

A package reference, like refs, but a length one vector, for convenience.

Value

parse_pkg_refs() returns a list of parsed references. parse_pkg_ref() returns one parsed reference. A parsed reference is a list, with at least elements:

ref: The original reference string.
type: The reference type.
package: The package name. It typically contains additional data, specific to the various reference types. See pkg_refs for details. The parsed reference always has class ⁠remote_ref_<type>⁠ and remote_ref.

Create a binary package from an installed package

Description

The built package will be in the current working directory.

Usage

pkg_build(
  pkg,
  library = .libPaths()[1],
  flavor = Sys.getenv("PKG_BUILD_FLAVOR"),
  build_number = 1L
)

Arguments

pkg

Package name.

library

Library path.

flavor

Platform flavor. Defaults to the PKG_BUILD_FLAVOR environment variable. If not NULL or an empty string, then it is appended to the platform string with a dash.

build_number

An integer number that is added to the file name, after the version number, to be able to have multiple builds for the same package version.

Details

This function is currently experimental.

Value

Path to the built package.

pkgdepends configuration

Description

Configuration entries for several pkgdepends classes.

Usage

current_config()

Details

pkgdepends configuration is set from several source. They are, in the order of preference:

Function arguments, e.g. the config argument of new_pkg_installation_proposal().
Global options, set via options(). The name of the global option is the pkg. prefix plus the name of the pkgdepends configuration entry. E.g. pkg.platforms.
Environment variables. The name of the environment variable is the PKG_ prefix, plus the name of the pkgdepends configuration entry, in uppercase. E.g. PKG_PLATFORMS.
Default values.

Not all classes use all entries. E.g. a pkg_download_proposal is not concerned about package libraries, so it'll ignore the library configuration entry.

Call current_config() to print the current configuration.

Configuration entries

build_vignettes: Whether to build vignettes for package trees. This is only used if the package is obtained from a package tree, and not from a source (or binary) package archive. By default vignettes are not built in this case. If you set this to TRUE, then you need to make sure that the vignette builder packages are available, as these are not installed by default currently.
cache_dir: Directory to download the packages to. Defaults to a temporary directory within the R session temporary directory, see base::tempdir().
cran_mirror: CRAN mirror to use. Defaults to the repos option (see base::options()), if that's not set then ⁠https://cran.rstudio.com⁠.
dependencies: Dependencies to consider or download or install. Defaults to the hard dependencies, see pkg_dep_types_hard(). The following values are supported in the PKG_DEPENDENCIES environment variable: "TRUE", "FALSE", "NA", or a semicolon separated list of dependency types. See as_pkg_dependencies() for details.
git_submodules: Whether or not to update submodules in git repositories. This affects ⁠git::⁠ and ⁠gitlab::⁠ package sources only. If the R package is in a subdirectory then only the submodules within that directory are updated. If a submodule appears in .Rbuildignore, then it is skipped.
include_linkingto: Whether to always include LinkingTo dependencies in the solution of and installation, even if they are needed because the packages are installed from binaries. This is sometimes useful, see e.g. https://github.com/r-lib/pak/issues/485 for an example use case.
library: Package library to install packages to. It is also used for already installed packages when considering dependencies in dependency lookup or package installation. Defaults to the first path in .libPaths().
metadata_cache_dir: Location of metadata replica of pkgcache::cranlike_metadata_cache. Defaults to a temporary directory within the R session temporary directory, see base::tempdir().
metadata_update_after: A time interval as a difftime object. pkgdepends will update the metadata cache if it is older than this. The default is one day. The PKG_METADATA_UPDATE_AFTER environment variable may be set in seconds (s suffix), minutes (m suffix), hours (h suffix), or days (d suffix). E.g: ⁠1d⁠ means one day.
package_cache_dir: Package cache location of pkgcache::package_cache. The default is the pkgcache default.
platforms: Character vector of platforms to download or install packages for. See default_platforms() for possible platform names. Defaults to the platform of the current R session, plus "source".
r_versions: Character vector, R versions to download or install packages for. It defaults to the current R version.
sysreqs: Whether to automatically look up and install system requirements. If TRUE, then ⁠r pak_or_pkgdepends()⁠ will try to install required system packages. If FALSE, then system requirements are still printed (including OS packages on supported platforms), but they are not installed. By default it is TRUE on supported platforms, if the current user is the root user or password-less sudo is configured for the current user.
sysreqs_db_update: Whether to try to update the system requirements database from GitHub. If the update fails, then the cached or the build-in database if used. Defaults to TRUE.
sysreqs_db_update_timeout: Timeout for the system requirements database update. Defaults to five seconds, except if the CI environment variable is set, then it is one minute.
sysreqs_dry_run: If TRUE, then pkgdepends only prints the system commands to install system requirements, but does not execute them.
sysreqs_platform: The platform to use for system requirements lookup. On Linux, where system requirements are currently supported, it must be a string containing the distribution name and release, separated by a dash. E.g.: "ubuntu-22.04", or "rhel-9".
sysreqs_rspm_repo_id: Posit Package Manager (formerly RStudio Package Manager) repository id to use for CRAN system requirements lookup. Defaults to the RSPM_REPO_ID environment variable, if set. If not set, then it defaults to 1.
sysreqs_rspm_url: Root URL of Posit Package Manager (formerly RStudio Package Manager) for system requirements lookup. By default the RSPM_ROOT environment variable is used, if set. If not set, it defaults to ⁠https://packagemanager.posit.co⁠.
sysreqs_sudo: Whether to use sudo to install system requirements, on Unix. By default it is TRUE on Linux if the effective user id of the current process is not the root user.
sysreqs_update: Whether to try to update system packages that are already installed. It defaults to TRUE on CI systems: if the CI environment variable is set to true.
sysreqs_verbose: Whether to echo the output of system requirements installation. Defaults to TRUE if the CI environment variable is set.
use_bioconductor: Whether to automatically use the Bioconductor repositories. Defaults to TRUE.
windows_archs: Character scalar specifying which architectures to download/install for on Windows. Its possible values are:
- "prefer-x64": Generally prefer x64 binaries. If the current R session is x64, then we download/install x64 packages. (These packages might still be multi-architecture binaries!) If the current R session is i386, then we download/install packages for both architectures. This might mean compiling packages from source if the binary packages are for x64 only, like the CRAN Windows binaries for R 4.2.x currently. "prefer-x64" is the default for R 4.2.0 and later.
- "both": Always download/install packages for both i386 and x64 architectures. This might need compilation from source if the available binaries are for x64 only, like the CRAN Windows binaries for R 4.2.x currently. "both" is the default for R 4.2.0 and earlier.

Possible package dependency types

Description

Hard dependencies are needed for a package to load, soft dependencies are optional.

Usage

pkg_dep_types_hard()

pkg_dep_types_soft()

pkg_dep_types()

Value

A string vector of dependency types, capitalized.

Package downloads

Description

The pkg_download_proposal and pkg_installation_proposal classes both have download methods, to downloads package files into a configured directory (see 'Configuration').

Details

They return a pkg_download_result object, which is a data frame, that adds extra columns to pkg_resolution_result (for pkg_download_proposal) or pkg_solution_result (for pkg_installation_proposal):

built: the Built field from the DESCRIPTION file of binary packages, for which this information is available.
cache_status: whether the package file is in the package cache. It is NA for ⁠installed::⁠ package refs.
dep_types: character vector of dependency types that were considered for this package. (This is a list column.)
deps: dependencies of the package, in a data frame. See "Package dependency tables" below.
direct: whether this package (ref, really) was directly specified, or added as a dependency.
error: this is a list column that contains error objects for the refs that pkgdepends failed to resolve.
filesize: the file size in bytes, or NA if this information is not available.
license: license of the package, or NA if not available.
md5sum: MD5 checksum of the package file, if available, or NA if not.
metadata: a named character vector. These fields will be (should be) added to the installed DESCRIPTION file of the package.
mirror: URL of the CRAN(-like) mirror site where the metadata was obtained from. It is NA for non-CRAN-like sources, e.g. local files, installed packages, GitHub, etc.
needscompilation: whether the package needs compilation.
package: package name.
priority: this is "base" for base packages, "recommended" for recommended packages, and NA otherwise.
ref: package reference.
remote: the parsed remote_ref objects, see parse_pkg_refs(). This is a list column.
repodir: the directory where this package should be in a CRAN-like repository.
sha256: SHA256 hash of the package file, if available, otherwise NA.
sources: URLs where this package can be downloaded from. This is not necessarily a URL that you can download with a HTTP client. E.g. for ⁠local::⁠ refs it is a path, and for ⁠git::⁠ refs it is a URL for git. It is a zero length vector for ⁠installed::⁠ refs.
status: status of the dependency resolution, "OK" or "FAILED".
target: path where this package should be saved in a CRAN-repository.
type: ref type.
version: package version.
fulltarget: absolute path to the downloaded file. At most one of fulltarget and fulltarget_tree must exist on the disk.
fulltarget_tree: absolute path to a package tree directory. At most one of fulltarget and fulltarget_tree must exist on the disk.
download_status: "Had" or "Got", depending on whether the file was obtained from the cache.
download_error: error object for failed downloads.
file_size: Size of the file, or NA. For ⁠installed::⁠ refs, it is NA, and it is also NA for refs that created fulltarget_tree instead of fulltarget.

fulltarget, if it exists, contains a packaged (via ⁠R CMD build⁠) source R package. If fulltarget_tree exists, it is a package tree directory, that still needs an ⁠R CMD build⁠ call.

Additional columns might be present. They are either used internally or they are experimental. They might be removed or changed at any time.

All columns are of type character, except for direct (logical), needscompilation (logical), filesize (integer), deps (list column, see "Package dependency tables" below), sources (list of character vectors), remote (list), error (list), metadata (list), dep_types (list).

Package dependency tables

A package dependency tables in the deps list column have five columns currently:

ref: the package ref of the dependency.
type: the dependency type, in all lowercase. I.e. imports, suggests, etc.
package: package name of the dependency.
op: operator for version requirements, e.g. >=.
version: version number, for version requirements.

Check if an R package name is available.

Description

Additionally, look up the candidate name in a number of dictionaries, to make sure that it does not have a negative meaning.

Usage

pkg_name_check(name, dictionaries = NULL)

Arguments

name

Package name candidate.

dictionaries

Character vector, the dictionaries to query. Available dictionaries: * wikipedia * wiktionary, * sentiment (https://github.com/fnielsen/afinn), * urban (Urban Dictionary). If NULL (by default), the Urban Dictionary is omitted, as it is often offensive.

Details

Valid package name check

Check the validity of name as a package name. See 'Writing R Extensions' for the allowed package names. Also checked against a list of names that are known to cause problems.

CRAN checks

Check name against the names of all past and current packages on CRAN, including base and recommended packages.

Bioconductor checks

Check name against all past and current Bioconductor packages.

Profanity check

Check name with https://www.purgomalum.com/service/containsprofanity to make sure it is not a profanity.

Dictionaries

See the dictionaries argument.

Value

pkg_name_check object with a custom print method.

Examples


pkg_name_check("cli")

Package references

Description

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.

Package references

Many pkgdepends and pak functions take package names as arguments. E.g. pak::pkg_install() takes the names of the packages to install and pak::pkg_deps_tree() takes the names of the packages to draw dependency trees for.

Most of these functions can also take more generic package references instead of package names. A package reference also tells pkgdepends where to find the package source.

To specify a package source, use its name as a prefix, with a :: separator. E.g. cran::mypkg means the mypkg package from CRAN.

A package name is a special package reference that implicitly specifies the configured CRAN(-like) repositories as the package source (we call this the standard package source). So mypkg is equivalent to standard::mypkg and pkgdepends looks for mypkg in any of the configured CRAN-like repositories. If you did not explicitly specify any CRAN-like repositories (e.g. with options("repos")), then pkgdepends uses the CRAN and Bioconductor repositories by default.

This is the list of the currently supported package sources. We will discuss each in detail below.

cran: a CRAN package.
bioc: a Bioconductor package.
standard: a package from a configured CRAN-like repository.
github: a package from GitHub.
gitlab: a package from GitLab.
git: a package in a Git repository.
local: a local package file or directory.
url: an URL that points to a package archive.
installed: an installed package.
deps: the dependencies of a local package file or directory.
any: a special reference type that accepts a package from any source. See below.
param: a special reference to change how other references are downloaded or installed. See "Parameters" below.

Shorthands

To save typing, you do not always need to fully specify the package source in a package reference. You have seen before that a package name implicitly has a standard package source. Here are the complete rules for such shorthands, in the order they are applied:

If the package reference is

a valid package name, or a package name with an @ version specification, the standard package source is used. E.g. pkg is equivalent to standard::pkg and ⁠pkg@1.0⁠ is equivalent to ⁠standard::pkg@1.0⁠.
a valid github ref type without the ⁠github::⁠ prefix, then github is used. E.g. user/repo is equivalent to github::user/repo and user/repo@tag is equivalent to github::user/repo@tag, etc.
a GitHub URL (see below) without the ⁠github::⁠ prefix, then github is used.
a path that starts with . or / or ⁠\⁠ or ~, then local is used. (pkgdepends does not check if the path exists.)
of the form ⁠<package-name>=?<parameters>⁠, then it will be the special param type. See "Parameters" below.

If the package reference does not have an explicit package source, and the package source cannot be determined from these rules, then pkgdepends throws an error.

Package names

When pkgdepends is looking up the dependencies of a package, it needs to be able to determine the name of the dependency from the package reference. This is sometimes not easy for dependencies in Remotes (or similar) fields.

For ⁠github::⁠ and ⁠gitlab::⁠ dependencies pkgdepends assumes that the package name is the same as the name of the repository. If this does not hold, then you need to specify the package name explicitly, using a ⁠<package>=⁠ prefix. E.g. pins=rstudio/pins-r. To specify both the package source type and the package name at the same time, write it like this: pins=github::rstudio/pins-r.
For ⁠git::⁠ dependencies, pkgdepends assumes that the package name is the same as the last component of the repository. If this does not hold, then you need to specify the package name explicitly, using a ⁠<package>=⁠ prefix. E.g. ⁠pins=git::https://github.com/rstudio/pins-r⁠.
For ⁠local::⁠ dependencies, you always need to specify the package name explicitly. E.g. ⁠pins=local::~/works/pins⁠.
For ⁠url::⁠ dependencies, you always need to specify the package name explicitly. E.g. ⁠ggplot2=url::https://cloud.r-project.org/src/contrib/...⁠.

Parameters

Package references may have optional parameters, added after a question mark. Different parameters are separated by an ampersand (&) character. (This is very similar to how HTTP URLs take query parameters.)

Parameters may be flags that turn on some behavior, or they can have a string value, assigned with an equal sign (=). If no value is assigned, then a true value is assumed. For example, these two package references are equivalent:

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

Parameters for downstream packages

pkgdepends allows specifying parameters for downstream packages, using the ⁠<package>=?<params>⁠ special package reference, where package is the name of the package, and ⁠<params>⁠ are the parameters, as above. This is useful if you want to add a parameter to a downstream dependency.

For example, to install ggplot2, and always reinstall its cli package dependency, you could use the ggplot2 and cli=?reinstall package references. The latter tells pkgdepends to always reinstall cli, even if it is already installed.

Currently supported parameters

ignore is a flag parameter. If specified, the package is ignored. This usually makes sense in the packagename=?ignore form, to ignore a downstream soft dependency. If all versions of a hard dependency are ignored that will lead to a solution error.
ignore-before-r is a version number parameter. The package will be ignored on R versions that are older than the specified one. E.g. ⁠Matrix=?ignore-before-r=4.1.2⁠ will ignore the Matrix package on R versions that are older than 4.1.2. This parameter really only makes sense in the packgename=?ignore-before-r form.
ignore-unavailable is a flag. It can only be specified for soft dependencies. If specified and the package is not available, it will be ignored. This parameter really only makes sense in the packagename=?ignore-unavailable form.
source is a flag 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 ignored for others.
reinstall requests a re-install for package installations. It is supported by the ⁠bioc::⁠, ⁠cran::⁠, ⁠git::⁠, ⁠github::⁠, ⁠gitlab::⁠, ⁠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) package(s) to the package cache. It is supported by the ⁠bioc::⁠, ⁠cran::⁠, ⁠git::⁠, ⁠github::⁠, ⁠gitlab::⁠, ⁠standard::⁠ and ⁠url::⁠ remote types.

Package source details

CRAN packages (`⁠cran::⁠`)

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 (`⁠bioc::⁠`)

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

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

Standard packages (`⁠standard::⁠`)

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 (`⁠github::⁠`)

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>⁠ specifies an 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 a URL, for example: git@github.com:r-lib/pak.git

GitLab packages (`⁠gitlab::⁠`)

Packages from a GitLab repository. Full syntax:

[<package>=][gitlab::]<project-path>/<repository>[/-/<subdir>][<detail>]

⁠<package>⁠ is the name of the package. If this is missing, then the name of the repository is used.
⁠<project-path>⁠ is typically the GitLab user or group name, but it may contain subgroups.
⁠<repository>⁠ is the name of the repository, or the project in GitLab terminology. GitLab subgroups are fully supported.
⁠<subdir>⁠ specifies an optional subdirectory, if the package is within a subdirectory in the repository. Note that for GitLab, this must come after a ⁠/-⁠ prefix, to be able to distinguish it from subgroups.
⁠<detail>⁠ may specify a Git branch, tag or (prefix of) a commit hash.

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

⁠gitlab::⁠ supports Git submodules, see the git-submodules configuration entry.

Examples:

gitlab::gaborcsardi/cli
gitlab::r-hub/filelock@main
gitlab::group/subgroup/subsubgroup/project/-/subdir@ref

Packages in Git repositories (`⁠git::⁠`)

Full syntax:

[<package>=]git::https?://<host>[<detail>]

⁠<package>⁠ is the name of the package. If this is missing, then the last component of the ⁠<host>⁠ is used.
⁠<host>⁠ is the host name and path of the Git repository. Some Git repositories need the .git suffix here, others are more forgiving.
⁠<detail>⁠ specifies a certain version of the package: a Git branch, tag or (prefix of) a commit hash: ⁠@<commitish>⁠.

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

⁠git::⁠ supports Git submodules, see the git-submodules configuration entry.

Examples:

git::https://github.com/r-lib/crayon
git::https://github.com/r-lib/crayon.git
git::https://github.com/r-lib/crayon.git@84be6207
git::https://github.com/r-lib/crayon.git@branch
git::https://gitlab.com/gaborcsardi/cli.git

Note that pkgdepends has a built-in Git client, and does not require a system Git installation.

If the system has Git installed, then pkgdepends will use the credentials stored in the configured Git credential store, automatically, via the gitcreds package.

Local packages (`⁠local::⁠`)

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
.

If you specify a local package in a dependency (i.e. in DESCRIPTION), then you also need to specify the name of the package, see "Package names" above.

URLs (`⁠url::⁠`)

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

If you specify a package from a URL in a dependency (i.e. in DESCRIPTION), then you also need to specify the name of the package, see "Package names" above.

Installed packages (`⁠installed::⁠`)

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 (`⁠deps::⁠`)

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::.

`⁠any::⁠` packages

Sometimes you need to install additional packages, but you don't mind where they are installed from. Here is an example. You want to install cli from GitHub, from r-lib/cli. You also want to install glue, and you don't mind which version of glue is installed, as long as it is compatible with the requested cli version. If cli specifies the development version of glue, then that is fine. If cli is fine with the CRAN version of glue, that's OK, too. If a future version of cli does not depend on glue, you still want glue installed, from CRAN. The ⁠any::⁠ reference type does exactly this.

In our example you might write

pak::pkg_install(c("glue", "r-lib/cli"))

first, but this will fail if rlib/cli requests (say) tidyverse/glue, because in pkg_install() "glue" is interpreted as "standard::glue", creating a conflict with tidyverse/glue. On the other hand

pak::pkg_install(c("any::glue", "r-lib/cli"))

works, independently of which glue version is requested by cli.

Parameter refs (`⁠param::⁠`)

See "Parameters" above.

The `Remotes` field

In the DESCRIPTION file of an R package you can mark any regular dependency defined in the Depends, Imports, Suggests or Enhances fields as being installed from a non-standard package source by adding a package reference to a Remotes entry. pkgdepends will download and install the package from the specified location, instead of a CRAN-like repository.

The remote dependencies specified in Remotes are a comma separated list of package sources:

Remotes: <pkg-source-1>, <pkg-source-2>, [ ... ]

Note that you will still need to add the package to one of the regular dependency fields, i.e. Imports, Suggests, etc. Here is a concrete example that specifies the r-lib/glue package:

Imports: glue
Remotes: r-lib/glue,
  r-lib/httr@v0.4,
  klutometis/roxygen#142,
  r-lib/testthat@c67018fa4970

The CRAN and Bioconductor repositories do not support the Remotes field, so you need to remove this field, before submitting your package to either of them.

Dependency resolution

Description

Collect information about dependencies of R packages, recursively.

Details

pkg_deps, pkg_download_proposal and pkg_installation_proposal all resolve their dependencies recursively, to obtain information about all packages needed for the specified package references.

CRAN and Bioconductor packages

Resolution currently start by downloading the CRAN and Bioconductor metadata, if it is out of date. For CRAN, we also download additional metadata, that includes file sizes, SHA hashes, system requirements, and "built" (for binary packages) and "packaged" time stamps. The extra meta information is updated daily currently, so for some packages it might be incorrect or missing.

GitHub packages

For GitHub packages, we query their download URL to be able to download the package later, and also download their DESCRIPTION file, to learn about their dependencies.

Local packages

From local package files we extract the DESCRIPTION file, to learn about their dependencies.

The `remotes` field in `DESCRIPTION`

We support the non-standard Remotes field in the package DESCRIPTION file. This field may contain a list of package references for any of the dependencies that are specified in one of the Depends, Includes, Suggests or Enhances fields. The syntax is a comma separated list of package references.

The result

The result of the resolution is a data frame with information about the packages and their dependencies.

built: the Built field from the DESCRIPTION file of binary packages, for which this information is available.
cache_status: whether the package file is in the package cache. It is NA for ⁠installed::⁠ package refs.
dep_types: character vector of dependency types that were considered for this package. (This is a list column.)
deps: dependencies of the package, in a data frame. See "Package dependency tables" below.
direct: whether this package (ref, really) was directly specified, or added as a dependency.
error: this is a list column that contains error objects for the refs that pkgdepends failed to resolve.
filesize: the file size in bytes, or NA if this information is not available.
license: license of the package, or NA if not available.
md5sum: MD5 checksum of the package file, if available, or NA if not.
metadata: a named character vector. These fields will be (should be) added to the installed DESCRIPTION file of the package.
mirror: URL of the CRAN(-like) mirror site where the metadata was obtained from. It is NA for non-CRAN-like sources, e.g. local files, installed packages, GitHub, etc.
needscompilation: whether the package needs compilation.
package: package name.
priority: this is "base" for base packages, "recommended" for recommended packages, and NA otherwise.
ref: package reference.
remote: the parsed remote_ref objects, see parse_pkg_refs(). This is a list column.
repodir: the directory where this package should be in a CRAN-like repository.
sha256: SHA256 hash of the package file, if available, otherwise NA.
sources: URLs where this package can be downloaded from. This is not necessarily a URL that you can download with a HTTP client. E.g. for ⁠local::⁠ refs it is a path, and for ⁠git::⁠ refs it is a URL for git. It is a zero length vector for ⁠installed::⁠ refs.
status: status of the dependency resolution, "OK" or "FAILED".
target: path where this package should be saved in a CRAN-repository.
type: ref type.
version: package version.

Additional columns might be present. They are either used internally or they are experimental. They might be removed or changed at any time.

Package dependency tables

A package dependency tables in the deps list column have five columns currently:

ref: the package ref of the dependency.
type: the dependency type, in all lowercase. I.e. imports, suggests, etc.
package: package name of the dependency.
op: operator for version requirements, e.g. >=.
version: version number, for version requirements.

Resolution failures

The resolution process does not stop on error. Instead, failed resolutions return and error object in the error column of the result data frame.

A set of handy regular expressions related to R packages

Description

If you use these in R, make sure you specify perl = TRUE, see base::grep().

Usage

pkg_rx()

Details

Currently included:

pkg_name: A valid package name.
type_cran: A ⁠cran::⁠ package reference.
type_bioc: A ⁠bioc::⁠ package reference.
type_standard: A ⁠standard::⁠ package reference.
type_github: A ⁠github::⁠ package reference.
type_git: A ⁠git::⁠ package reference.
type_local: A ⁠local::⁠ package reference.
type_deps: A ⁠deps::⁠ package reference.
type_installed: An ⁠installed::⁠ package reference.
github_username: A GitHub username.
github_repo: A GitHub repository name.
github_url: A GitHub URL.

Value

A named list of strings.

Examples

pkg_rx()

The dependency solver

Description

The dependency solver takes the resolution information, and works out the exact versions of each package that must be installed, such that version and other requirements are satisfied.

Details

Solution policies

The dependency solver currently supports two policies: lazy and upgrade. The lazy policy prefers to minimize installation time, and it does not perform package upgrades, unless version requirements require them. The upgrade policy prefers to update all package to their latest possible versions, but it still considers that version requirements.

The integer problem

Solving the package dependencies requires solving an integer linear problem (ILP). This subsection briefly describes how the problem is represented as an integer problem, and what the solution policies exactly mean.

Every row of the package resolution is a candidate for the dependency solver. In the integer problem, every candidate corresponds to a binary variable. This is 1 if that candidate is selected as part of the solution, and 0 otherwise.

The objective of the ILP minimization is defined differently for different solution policies. The ILP conditions are the same.

For the lazy policy, ⁠installed::⁠ packaged get 0 points, binary packages 1 point, sources packages 5 points.
For the 'upgrade' policy, we rank all candidates for a given package according to their version numbers, and assign more points to older versions. Points are assigned by 100 and candidates with equal versions get equal points. We still prefer installed packages to binaries to source packages, so also add 0 point for already installed candidates, 1 extra points for binaries and 5 points for source packages.
For directly specified refs, we aim to install each package exactly once. So for these we require that the variables corresponding to the same package sum up to 1.
For non-direct refs (i.e. dependencies), we require that the variables corresponding to the same package sum up to at most one. Since every candidate has at least 1 point in the objective function of the minimization problem, non-needed dependencies will be omitted.
For direct refs, we require that their candidates satisfy their references. What this means exactly depends on the ref types. E.g. for CRAN packages, it means that a CRAN candidate must be selected. For a standard ref, a GitHub candidate is OK as well.
We rule out candidates for which the dependency resolution failed.
We go over all the dependency requirements and rule out packages that do not meet them. For every package A, that requires package B, we select the ⁠B(i, i=1..k)⁠ candidates of B that satisfy A's requirements and add a A - B(1) - ... - B(k) <= 0 rule. To satisfy this rule, either we cannot install A, or if A is installed, then one of the good B candidates must be installed as well.
We rule out non-installed CRAN and Bioconductor candidates for packages that have an already installed candidate with the same exact version.
We also rule out source CRAN and Bioconductor candidates for packages that have a binary candidate with the same exact version.

Explaining why the solver failed

To be able to explain why a solution attempt failed, we also add a dummy variable for each directly required package. This dummy variable has a very large objective value, and it is only selected if there is no way to install the directly required package.

After a failed solution, we look the dummy variables that were selected, to see which directly required package failed to solve. Then we check which rule(s) ruled out the installation of these packages, and their dependencies, recursively.

The result

The result of the solution is a pkg_solution_result object. It is a named list with entries:

status: Status of the solution attempt, "OK" or "FAILED".
data: The selected candidates. This is very similar to a pkg_resolution_result object, but it has two extra columns:
- lib_status: status of the package in the library, after the installation. Possible values: new (will be newly installed), current (up to date, not installed), update (will be updated), no-update (could update, but will not).
- old_version: The old (current) version of the package in the library, or NA if the package is currently not installed.
problem: The ILP problem. The exact representation is an implementation detail, but it does have an informative print method.
solution: The return value of the internal solver.

Query and manipulate CRAN-like repositories

Description

These functions are currently experimental.

Details

List packages in a repository

repo$list() lists packages in a repository. It reads the PACKAGES file containing the repository metadata.

Usage

repo_list(..., path = ".")

Arguments

...: ignored currently.
path: path to repository. Must contain a PACKAGES file.

Value

Data frame of package data, a data frame with at least the following columns, possibly more if there are other entries in the metadata:

Package
Version
Depends
Imports
Suggests
Enhances
LinkingTo
License
File
DownloadURL
OS
Arch
Built
Filesize
SHA256
RVersion
Platform
GraphicsAPIVersion
InternalsId
SystemRequirements

Delete packages from repository metadata

repo$delete() deletes matching packages from the repository metadata.

Description

All matching packages will be removed. It does not delete the files themselves.

Usage

repo$delete(package, ..., path = ".")

Arguments

package: package name.
...: other fields to match, they must be named. Matching is case insensitive.
path: path to repository. Must contain a PACKAGES file.

Add a package to a repository

Description

It does not check if any version of the package is already in the repository. If you want to update a package, use repo$update().

Usage

repo$add(file, ..., path = ".")

Arguments

'file Package file.
'... Ignored currently.
⁠path Path to repository. Must contain a ⁠PACKAGES' file.

Update a package in a repository

Description

Previous version of the same package are removed. In particular, it removes packages with matching:

package name (Package field),
R version (Rversion field),
same OS (OS field), or no OS field,
same architecture (Arch field), or not Arch field.

Usage

repo$update(file, ..., path = ".")

Arguments

'file Package file.
'... Ignored currently.
⁠path Path to repository. Must contain a ⁠PACKAGES' file.

Update a file in a package metadata, stored on GitHub

Description

Clones the GitHub repository.
Calls repo_update() with file, in the subdir directory.
Adds and commits changes.
Pushes the git repository to GitHub. If the push fails, then it resets the git repository, pulls it from GitHub and tries the update process again, until the push succeeds.

This function needs command line git installed.

It sets up a cache credential helper, so the ⁠git push⁠ works without interaction with the user.

Usage

repo$update_gh(repo, subdir, files)

Arguments

repo: GitHub slug, e.g. r-hub/repos.
subdir: subdirectory in the GitHub repository, where the R package metadata should be updated. It must exist in the repository. If it does not have ⁠PACKAGES*⁠ files, then they will be created.
files: package files to add. The files will not be added to the repository, only to the metadata. They should be in the repository already.

Scan R code for dependent packages

Description

Scan all R files of a project or directory for packages used within them. It parses R code to find library(package), package::func(), and similar calls that imply package dependencies. See details below.

Usage

scan_deps(path = NULL, root = NULL)

Arguments

path

Files and/or directories to scan. Defaults to the current project, detected by finding the first parent directory of the current working directory, that contains a file or directory called DESCRIPTION, .git, .Rproj.user, renv.lock, or renv. (Note that this is different from renv::dependencies(), which only scans the current working directory by default!)

If path is not NULL, then only the specified files and directories are scanned, the directories recursively. In this case the root argument is used as the project root, to find .gitignore and .renvignore files. All entries of path must be within the root, the project root.

root

The root directory of the project. It is used to find the .gitignore and .renvignore files. By default the same algorithm is used to detect this as for path. If path is specified and it is not within the detected or specified root, scan_path() throws an error.

Value

Data frame with columns:

path: Path to the file in which the dependencies was found.
package: Detected package dependency. Typically a package name, but it can also be a package reference, e.g. a package from GitHub.
type: Dependency type. It is "prod", "test" or "dev". See 'Dependency types' below.
code: The piece of code the dependency was extracted from.
start_row: Start row of the code the dependency was extracted from.
start_column: Start column of the code the dependency was extracted from.
start_byte: Start byte of the code the dependency was extracted from.

Note the data frame may contain the same package multiple times, if it was detected multiple times, e.g. multiple library() calls load the same package.

Detected dependencies

scan_deps() detects package dependencies from these R expressions:

library(), require(), loadNamespace() and requireNamespace calls.
:: and ::: operators.
Any of the calls in this list in R code from R markdown or quarto R and Rscript (case insensitive) code blocks or inline R code.
A dependency on the methods package is inferred from finding setClass() and/or setGeneric() calls.
xfun::pkg_attach() and xfun::pkg_attach2() calls.
pacman::p_load() calls.
modules::import() and modules::module() calls.
import::from(), import::here() and import::into() calls.
box::use() calls.
targets::tar_option_set(packages = ...) calls.
Any of the calls in this list in R code from glue::glue() strings.
A dependency on the svglite package is inferred from ggplot2::ggsave() calls saving .svg files.
Dependencies from parsnip::set_engine() calls, the default engine to package mapping is:
- "glm" -> stats,
- "glmnet" -> glmnet,
- "keras" -> keras,
- "kknn" -> kknn,
- "nnet" -> nnet,
- "rpart" -> rpart,
- "spark" -> sparklyr,
- "stan" -> rstanarm. You can override the default mapping by setting the renv.parsnip.engines option to a named list.
A dependency on the xml2 package is inferred from using the "Junit" reporter (JunitReporter) from the testthat package.
A dependency on the ragg package is inferred from setting the default knitr device (dev option) to "ragg_png".
A dependency on the hexbin package is inferred from using ggplot2::geom_hex().
A custom symbol name to package name mapping can be defined in the renv.dependencies.database option. This must be a named list of named lists, where the outer names are package names, the inner names are function or object names, and the values are package names. E.g.
```
options(renv.dependencies.database = list(
  ggplot2 = list(geom_hex = "hexbin"),
  testthat = list(JunitReporter = "xml2")
))
```

Dependency types

scan_deps() classifies package dependencies into three groups, based on which files they were found:

Production dependencies: "prod".
Test dependencies: "test".
Development dependencies: "dev".

Check if installed packages have all their system requirements

Description

sysreqs_check_installed() checks if the system requirements of all packages (or a subset of packages) are installed.

sysreqs_fix_installed() installs the missing system packages.

Usage

sysreqs_check_installed(packages = NULL, library = .libPaths()[1])
sysreqs_fix_installed(packages = NULL, library = .libPaths()[1])

Arguments

packages

If not NULL, then only these packages are checked. If a package in packages is not installed, then pkgdepends throws a warning.

library

Library or libraries to check.

Details

These functions use the sysreqs_platform configuration option, see man_config_link("Configuration"). Set this if pkgdepends does not detect your platform correctly.

Value

Data frame with a custom print and format method, and a pkg_sysreqs_check_result class. Its columns are:

system_package: string, name of the required system package.
installed: logical, whether the system package is correctly installed.
packages: list column of character vectors. The names of the installed R packages that need this system package.
pre_install: list column of character vectors. Commands to run before the installation of the the system package.
post_install: list column of character vectors. Commands to run after the installation of the system package.

The data frame also have two attributes with additional data:

sysreqs_records: the raw system requirements records, and
system_packages: the list of the installed system packages.

sysreqs_fix_packages() returns the same value, but invisibly.

Examples


# This only works on supported platforms
sysreqs_check_installed()

List contents of the system requirements DB, for a platform

Description

It also tries to update the system dependency database, if it is outdated. (I.e. older than allowed in the metadata_update_after man_config_link("configuration option").

Usage

sysreqs_db_list(sysreqs_platform = NULL)

Arguments

sysreqs_platform

System requirements platform. If NULL, then the sysreqs_platform man_config_link("configuration option") is used, which defaults to the current platform. Set this option if .packageName does not detect your platform correctly.

Value

Data frame with columns:

name: cross platform system dependency name in the database.
patterns: one or more regular expressions to match to SystemRequirements fields.
packages: one or more system package names to install.
pre_install: command(s) to run before installing the packages.
post_install:: command(s) to run after installing the packages.

Examples


sysreqs_db_list(sysreqs_platform = "ubuntu-22.04")

Match system requirement descriptions to the database

Description

In the usual workflow pkgdepends matches the SystemRequirements fields of the DESCRIPTION files to the database.

Usage

sysreqs_db_match(specs, sysreqs_platform = NULL)

Arguments

specs

Character vector of system requirements descriptions.

sysreqs_platform

Details

The sysreqs_db_match() function lets you match any string, and it is mainly useful for debugging.

Value

Data frame with columns:

spec: the input specs.
sysreq: name of the system library or tool.
packages: system packages, list column of character vectors. Rarely it can be an empty string, e.g. if a pre_install script performs the installation.
pre_install: list column of character vectors. Shell script(s) to run before the installation.
post_install: list column of character vectors. Shell script(s) to run after the installation.

Examples


sysreqs_db_match(
  c("Needs libcurl", "Java, libssl"),
  sysreqs_platform = "ubuntu-22.04"
)

Update the cached copy of the system requirements database

Description

Update the cached copy of the system requirements database

Usage

sysreqs_db_update()

Details

If the the cached copy is recent, then no update is attempted. See the metadata_update_after man_config_link("configuration option").

Create an installation plan for system requirements

Description

This function uses new_pkg_installation_proposal() and its methods to create an installation plan for one or more packages, and then print their system requirements.

Usage

sysreqs_install_plan(refs, upgrade = TRUE, config = list())

Arguments

refs

Packages to install.

upgrade

If TRUE, pkgdepends will choose the latest available versions of packages, instead of preferring binary packages over source packages.

config

Configuration options. See 'Configuration'. If it does not include library, then a temporary library is used, which is equivalent to not assuming any preinstalled packages. Pass sysreqs_platform here if you want a different platform than the one R is running on.

Value

List with entries:

os: character string. Operating system.
distribution: character string. Linux distribution, NA if the OS is not Linux.
version: character string. Distribution version, NA is the OS is not Linux.
pre_install: character vector. Commands to run before the installation of system packages.
install_scripts: character vector. Commands to run to install the system packages.
post_install: character vector. Commands to run after the installation of system packages.
packages: data frame. Information about the system packages that are needed. It has columns:
- sysreq: string, cross-platform name of the system requirement.
- packages: list column of character vectors. The names of the R packages that have this system requirement.
- pre_install: list column of character vectors. Commands run before the package installation for this system requirement.
- system_packages: list column of character vectors. Names of system packages to install.
- post_install: list column of character vectors. Commands run after the package installation for this system requirement.

Examples


sysreqs_install_plan(
  "tidyverse",
  config = list(sysreqs_platform = "ubuntu-22.04")
)

Check if a platform has system requirements support

Description

Check if a platform has system requirements support

Usage

sysreqs_is_supported(sysreqs_platform = NULL)

Arguments

sysreqs_platform

Value

Logical scalar.

Examples


sysreqs_is_supported()

List installed system packages

Description

List installed system packages

Usage

sysreqs_list_system_packages()

Details

This function uses the sysreqs_platform configuration option, see man_config_link("Configuration"). Set this if pkgdepends does not detect your platform correctly.

Value

Data frame with columns:

status. two or three characters, the notation of dpkg on Debian based systems. "ii" means the package is correctly installed. On RPM based systems it is always "ii" currently.
package: name of the system package.
version: installed version of the system package.
capabilities: list column of character vectors, the capabilities provided by the package.

Examples


sysreqs_list_system_packages()[1:10,]

List platforms with system requirements support

Description

List platforms with system requirements support

Usage

sysreqs_platforms()

Value

Data frame with columns:

name: human readable OS name.
os: OS name, e.g. linux.
distribution: OS id, e.g. ubuntu or redhat.
version: distribution version. A star means that all versions are supported, that are also supported by the vendor.
update_command: command to run to update the system package metadata.
install_command: command to run to install packages.
query_command: name of the tool to use to query system package information.

Examples


sysreqs_platforms()

pkgdepends: Package Dependency Resolution and Downloads

Description

Features

Install

Usage

Package references

Package dependencies

Package downloads

Package installation

Dependency resolution

The dependency solver

Installation plans

Configuration

Related

Code of Conduct

License

Author(s)

See Also

Shorthands for dependency specifications

Description

Usage

Arguments

Details

Extra dependencies

Value

See Also

Package configuration (internals)

Description

Usage

Format

Terminology

Config entry (or entry)

Configuration (or config)

R option (or option)

Configuration prefix

Config entry type

Built-in types

string

count

flag

string_or_null

character

custom

config$onload_hook(): pretty-printing configuration

Usage

config$new(): Create a new configuration

Usage

Arguments

Value

Configuration methods

conf$add(): add a new configuration entry

Usage

Arguments

Value

conf$get(): query the value of a configuration entry

Usage

Arguments

Value

conf$set(): set the value of a configuration entry

Usage

Arguments

Value

⁠$conf$unset()⁠: unset a configuration entry

Usage

Arguments

Value

cond$update(): update the values of configuration entries

Usage

Arguments

Value

conf$list(): query the names of all config entries

Usage

Value

conf$exists(): check if a config entry exists

Usage

Arguments

Value

conf$lock(): lock the configuration

Usage

Value

`string`

`count`

`flag`

`string_or_null`

`character`

`custom`

`config$onload_hook()`: pretty-printing configuration

`config$new()`: Create a new configuration

`conf$add()`: add a new configuration entry

`conf$get()`: query the value of a configuration entry

`conf$set()`: set the value of a configuration entry

`⁠$conf$unset()⁠`: unset a configuration entry

`cond$update()`: update the values of configuration entries

`conf$list()`: query the names of all config entries

`conf$exists()`: check if a config entry exists

`conf$lock()`: lock the configuration

`conf$fix()`: fix the value of a single configuration entry

`conf$add_type()`: add a new config entry type to a configuration