lib.load: Load package from R_MV_library

View source: R/VC_library_reading.R

lib.loadR Documentation

Load package from R_MV_library

Description

There are two ways you can provide a package or vector of packages that need to be loaded:
1: just provide them directly (the ... input). All not recognized named variables will be interpreted as package names or (if it's a named argument) as a package name=version combination. lib.load(DBI = '0.5', assertthat, R6) 2: provide the loadPackages input in the following way: lib.load(loadPackages = c(DBI = '0.5', assertthat = '', R6 = ''))

If an empty string e.g. dplyr = '', or only the package name is specified, one of two things will happen: - if one version is available, this one is used. - if multiple versions are available, the first or last version is loaded depending on the 'pick.last' value (FALSE by default).

if >= or > is used, as in dplyr = '>= 2.5', it will decide for the first or last compatible version, depending on the 'pick.last' parameter. If another version is desired, please define it in the input list of packages to load, prior to the package that depends on it.

Usage

lib.load(
  ...,
  loadPackages = NULL,
  lib_location = lib.location(),
  dry_run = FALSE,
  quietly = FALSE,
  verbose = FALSE,
  appendLibPaths = FALSE,
  pick.last = FALSE,
  also_load_from_temp_lib = FALSE,
  .packNameVersionList = c(),
  .skipDependencies = c()
)

Arguments

...

All packages and their versions you would like to load e.g. lib.load(DBI = '0.5', assertthat = '', R6 = '', quietly = TRUE). Input names like quietly will be recognized and interpreted as expected.

loadPackages

Supports providing a named character vector of packages and their versions in the shape that is supported by all other functions in this package. e.g. c(DBI = '0.5', assertthat = '', R6 = '')

lib_location

The folder containing a structure where this package must load packages from. By default, it checks the environment variable R_MV_LIBRARY_LOCATION for this directory.

dry_run

Will make it perform a dry run. It will check all dependencies and if appendLibPaths it will add their paths to .libPaths but it will not load those packages. If the paths are added this way, you should be able to just call the located packages with library(...)

quietly

Indicates if the loading must happen silently. No messages and warnings will be shown if the value is set to true.

verbose

Indicates if additional information must be shown that might help with debugging the decision flow of this function. More specifically, when false, it will wrap 'library' calls in suppressWarnings(suppressMessages(...)) and suppress unloading attempts.

appendLibPaths

When true, the path to every package that is loaded will be appended to .libPath(...). That configured path is the location where library() will look for packages. For a usecase for this feature, see the description above.

pick.last

Changes the way a decision is made. In the scenario where a dependency of > or >= is defined, multiple versions may be available to choose from. By default, the lowest compliant version is chosen. Setting this to true will choose the highest version.

also_load_from_temp_lib

when true, it will also load packages from the temporary installation directory (created when packages are installed in the R_MV_library). Can be usefull when installing using: lib.install("new package!", install_temporarily = TRUE).

.packNameVersionList

See main description. Should be left blank.

.skipDependencies

See main description. Should be left blank.

Details

Dependencies are checked by recursively running this function with dry_run = TRUE. Then the paths of the found dependencies are temporarily appended (.libPaths()) when the actual package is loaded. This makes that dependencies are not loaded automatically, but are added to the namespace. To access a dependency directly, load it explicitly. Because the .libPaths() does not include the package it's location, this still needs to be done by lib.load.
In other words, dependencies are remembered, but not loaded.

Using dry_run will show the packages that will be used and will crash when no option is feasible (not installed or not compliant packages). If you are trying to setup a proper lib.load call, it is always a good idea to work with dry_run's. Once an incorrect package has been loaded, it is very likely you will have to restart your R session to unload it (Ctrl + shift + F10). Unloading packages in R often leaves traces.

The .libPaths of specific package versions can be appended when using 'appendLibPaths = TRUE'. Afterwards, the normal library call can be used to load the package since it's path is in the .LibPaths vector. For example:
lib.load(c(dplyr = '0.5.0'), dry_run = TRUE, appendLibPaths = TRUE) library(dplyr)

How this works is that dry_run skips the loading step, and appendLibPaths adds the paths of dplyr and it's dependencies to .libPaths, which make a library call work.

One reason to use appendLibPaths = TRUE is to make these packages accessible by a new 'child' R session. This is the case if devtools::test() is ran by using cntrl + shift + TRUE in Rstudio. When running it directly, it will use the packages it can find in the available libraries (.libPath()) and return an error if they cannot be found.

The inputs .packNameVersionList [vector of named versions] and .skipDependencies [vector of names] can be left blank in general. They are used internally and might be deprecated in the future.

Value

Will return a named character vector indicating which version of which package is loaded (or will be loaded, when dry_run = TRUE). In general, this function is called for it's side effect. It will load specific versions of specific packages from a special multiversion library.

Major version differences

By default, when chosing the right version to load, only versions are looked up within the same major version. For example, when pick.last = TRUE, the version '> 15.3.0' is requested and the versions c('15.5.0', '15.9.0', '16.0.0') are available, the version 15.9.0 is chosen. When a requested (dependency) version '>= 0.5' is provided, and only the versions c('0.4.0', '1.5.0', '1.7.0') are available, it will throw a warning that the first available version is a major release higher, and pick '1.5.0' or '1.7.0' depending on the pick.last value.

This behavior can be disabled by setting options(mv_prefer_within_major_version = 'no').

Base packages

The packages within the directory returned by .Library are considered 'base packages'. Of these, only one version can exist, and these cannot be included in the multiversion library.

Problem solving

If you receive the error "cannot unload ..." it means that it tries to load a package, but another version is already loaded. To unload this other (older) version, run detach(package = '...'). If it is a dependency of an other package, you will receive this error. Try restarting your RStudio with a clean workspace (environment). If that doesn't help, the only workaround (when using this in R studio) is to close your Rstudio session (NOTE: save your unsaved process before proceeding!!), rename (or remove) the folder "YourRProject/.Rproj.user/.../sources/prop" and start Rstudio again. If it doesn't work, try "/sources/per" also. Where the ... stands for a hash that is used in the current session e.g. /F3B1663E/. After this, the packages should be unloaded and you should be able to load a new batch of packages. Most times it will suffice to clear the workspace (environment) and reload the project while saving the empty environment.


multiversion documentation built on March 22, 2022, 1:07 a.m.