R6 class for package download and installation.
Source:R/pkg-installation.R
pkg_installation_proposal.Rd
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 aslibrary
.- ...
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 withnew_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()
.
Methods
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_config()
Configuration options for the pkg_installation_proposal
object. See
'Configuration' for details.
Returns
Named list. See 'Configuration' for the configuration options.
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.
Method async_resolve()
The same as resolve()
, but asynchronous. This
method is for advanced use.
Method get_resolution()
Query the result of the dependency resolution. This method can be
called after resolve()
has completed.
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.
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_installation_proposal$set_solve_policy(policy = c("lazy", "upgrade"))
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.
Method get_solution()
Returns the solution of the package dependencies.
Returns
A pkg_solution_result object, which is a list. See pkg_solution_result for details.
Method show_solution()
Show the solution on the screen.
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.
Method create_lockfile()
Create a lock file that contains the information to perform the installation later, possibly in another R session.
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.
Returns
A tree
object from the cli package, see cli::tree()
.
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.
Method async_download()
The same as download()
, but asynchronous.
This method is for advanced use.
Method get_downloads()
Returns the summary of the package 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_installation_proposal$download()
call.
Method install()
Install the downloaded packages. It calls install_package_plan()
.
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.
Method get_install_plan()
Returns
An installation plan, see 'Installation plans' for the format.
Method format()
Format a pkg_installation_proposal
object, typically for printing.
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.
Examples
if (FALSE) { # \dontrun{
pdi <- new_pkg_installation_proposal(
"pak",
config = list(library = tempfile())
)
pdi
pdi$resolve()
pdi
pdi$solve()
pdi
pdi$download()
pdi
} # }
pdi <- new_pkg_installation_proposal(
"r-lib/pkgdepends",
config = list(library = tempfile()))
#> ℹ Creating library directory: /tmp/Rtmpkdyqa0/file19845038b8ca
pdi
#> <pkg_installation_proposal>
#> + refs:
#> - r-lib/pkgdepends
#> + solution policy: lazy
#> (use `$solve()` to solve dependencies)
pdi <- new_pkg_installation_proposal("r-lib/pkgdepends")
pdi$get_refs()
#> [1] "r-lib/pkgdepends"
pdi <- new_pkg_installation_proposal(
"pak",
config = list(library = tempfile())
)
#> ℹ Creating library directory: /tmp/Rtmpkdyqa0/file1984696da8a
pdi$get_config()
#> # pkg config
#> ## build_vignettes
#> <default>
#> [1] FALSE
#>
#> ## sysreqs_verbose
#> <default>
#> [1] TRUE
#>
#> ## sysreqs_db_update
#> <default>
#> [1] TRUE
#>
#> ## metadata_cache_dir
#> <default>
#> [1] "/tmp/Rtmpkdyqa0/file19842ed8dc34"
#>
#> ## platforms
#> <default>
#> [1] "x86_64-pc-linux-gnu-ubuntu-22.04" "source"
#>
#> ## goal
#> <set>
#> [1] "install"
#>
#> ## r_versions
#> <default>
#> [1] "4.4.2"
#>
#> ## cache_dir
#> <default>
#> [1] "/tmp/Rtmpkdyqa0/file19844a7eda7d"
#>
#> ## library
#> <set>
#> [1] "/tmp/Rtmpkdyqa0/file1984696da8a"
#>
#> ## metadata_update_after
#> <default>
#> Time difference of 24 hours
#>
#> ## include_linkingto
#> <default>
#> [1] FALSE
#>
#> ## sysreqs_rspm_repo_id
#> <default>
#> [1] "1"
#>
#> ## sysreqs_update
#> <default>
#> [1] TRUE
#>
#> ## package_cache_dir
#> <default>
#> NULL
#>
#> ## sysreqs_rspm_url
#> <default>
#> [1] "https://packagemanager.posit.co"
#>
#> ## sysreqs_sudo
#> <default>
#> [1] TRUE
#>
#> ## sysreqs_db_update_timeout
#> <default>
#> Time difference of 5 secs
#>
#> ## sysreqs_lookup_system
#> <default>
#> [1] TRUE
#>
#> ## git_submodules
#> <default>
#> [1] FALSE
#>
#> ## sysreqs_platform
#> <default>
#> [1] "x86_64-pc-linux-gnu-ubuntu-22.04"
#>
#> ## dependencies
#> <default>
#> [1] "Depends" "Imports" "LinkingTo"
#>
#> ## sysreqs
#> <default>
#> [1] TRUE
#>
#> ## sysreqs_dry_run
#> <default>
#> [1] FALSE
#>
#> ## windows_archs
#> <default>
#> [1] "prefer-x64"
#>
#> ## use_bioconductor
#> <default>
#> [1] TRUE
#>
#> ## cran_mirror
#> <default>
#> CRAN
#> "https://cran.rstudio.com"
#>
if (FALSE) { # \dontrun{
pdi <- new_pkg_installation_proposal(
"pak",
config = list(library = tempfile())
)
pdi$resolve()
pdi$get_resolution()
} # }
if (FALSE) { # \dontrun{
pdi <- new_pkg_installation_proposal(
"r-lib/pkgdepends",
config = list(library = tempfile())
)
pdi$resolve()
pdi$get_resolution()
} # }
pdi <- new_pkg_installation_proposal(
"r-lib/pkgdepends",
config = list(library = tempfile())
)
#> ℹ Creating library directory: /tmp/Rtmpkdyqa0/file19844f9a9a31
pdi$get_solve_policy()
#> [1] "lazy"
pdi$set_solve_policy("upgrade")
pdi$get_solve_policy()
#> [1] "upgrade"
pdi <- new_pkg_installation_proposal(
"r-lib/pkgdepends",
config = list(library = tempfile())
)
#> ℹ Creating library directory: /tmp/Rtmpkdyqa0/file19845514e93d
pdi$get_solve_policy()
#> [1] "lazy"
pdi$set_solve_policy("upgrade")
pdi$get_solve_policy()
#> [1] "upgrade"
if (FALSE) { # \dontrun{
pdi <- new_pkg_installation_proposal(
"r-lib/pkgdepends",
config = list(library = tempfile())
)
pdi$resolve()
pdi$solve()
pdi$get_solution()
} # }
if (FALSE) { # \dontrun{
pdi <- new_pkg_installation_proposal(
"r-lib/pkgdepends",
config = list(library = tempfile())
)
pdi$resolve()
pdi$solve()
pdi$get_solution()
} # }
if (FALSE) { # \dontrun{
pdi <- new_pkg_installation_proposal(
"r-lib/pkgdepends",
config = list(library = tempfile())
)
pdi$resolve()
pdi$solve()
pdi$get_solution()
pdi$show_solution()
} # }
if (FALSE) { # \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()
} # }
if (FALSE) { # \dontrun{
pdi <- new_pkg_installation_proposal(
"pak",
config = list(library = tempfile())
)
pdi$resolve()
pdi$solve()
pdi$draw()
} # }
if (FALSE) { # \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()
} # }
if (FALSE) { # \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()
} # }
if (FALSE) { # \dontrun{
pdi <- new_pkg_installation_proposal(
"pak",
config = list(library = tempfile())
)
pdi$resolve()
pdi$solve()
pdi$download()
pdi$get_install_plan()
} # }
# Method print
pdi <- new_pkg_installation_proposal(
"pak",
config = list(library = tempfile())
)
#> ℹ Creating library directory: /tmp/Rtmpkdyqa0/file198415aaf51d
pdi
#> <pkg_installation_proposal>
#> + refs:
#> - pak
#> + solution policy: lazy
#> (use `$solve()` to solve dependencies)
pdi$resolve()
pdi
#> <pkg_installation_proposal>
#> + refs:
#> - pak
#> + solution policy: lazy
#> (use `$solve()` to solve dependencies)
pdi$solve()
pdi
#> <pkg_installation_proposal>
#> + refs:
#> - pak
#> + solution policy: lazy
#> + has solution
#> (use `$download()` to download packages)
#> (use `$show_solution()` to see the packages to install
#> (use `$get_solution()` to see the full solution results)
#> (use `$draw()` to draw the dependency tree)
#> (use `$create_lockfile()` to write a lock file)
pdi$download()
#> ℹ Getting 1 pkg with unknown size
#> ✔ Got pak 0.8.0 (x86_64-pc-linux-gnu-ubuntu-22.04) (5.98 MB)
pdi
#> <pkg_installation_proposal>
#> + refs:
#> - pak
#> + solution policy: lazy
#> + has solution
#> + has downloads
#> (use `$show_solution()` to see the packages to install
#> (use `$get_solution()` to see the full solution results)
#> (use `$draw()` to draw the dependency tree)
#> (use `$create_lockfile()` to write a lock file)
#> (use `$get_downloads()` to get download data)
#> (use `$get_install_plan()` to get the installation plan)
#> (use `$install()` to install the packages)