reproducible (version 1.1.1)

Require: Repeatability-safe install and load packages, optionally with specific versions

Description

maturing

Usage

Require(
  packages,
  packageVersionFile,
  libPath = .libPaths()[1],
  install_githubArgs = list(),
  install.packagesArgs = list(),
  standAlone = FALSE,
  repos = getOption("repos"),
  forget = FALSE
)

Arguments

packages

Character vector of packages to install via install.packages, then load (i.e., with library). If it is one package, it can be unquoted (as in require)

packageVersionFile

If provided, then this will override all install.package calls with versions::install.versions

libPath

The library path where all packages should be installed, and looked for to load (i.e., call library)

install_githubArgs

List of optional named arguments, passed to install_github.

install.packagesArgs

List of optional named arguments, passed to install.packages.

standAlone

Logical. If TRUE, all packages will be installed and loaded strictly from the libPaths only. If FALSE, all .libPaths will be used to find the correct versions. This can be create dramatically faster installs if the user has a substantial number of the packages already in their personal library. In the case of TRUE, there will be a hidden file place in the libPath directory that lists all the packages that were needed during the Require call. Default FALSE to minimize package installing.

repos

The remote repository (e.g., a CRAN mirror), passed to either install.packages, install_github or installVersions.

forget

Internally, this function identifies package dependencies using a memoised function for speed on reuse. But, it may be inaccurate in some cases, if packages were installed manually by a user. Set this to TRUE to refresh that dependency calculation.

Details

This is an "all in one" function that will run install.packages for CRAN packages, remotes::install_github for https://github.com/ packages and will install specific versions of each package if there is a packageVersionFile supplied. Plus, when packages is provided as a character vector, or a packageVersionFile is supplied, all package dependencies will be first assessed for unique(dependencies) so the same package is not installed multiple times. Finally library is called on the packages. If packages are already installed (packages supplied), and their version numbers are exact (when packageVersionFile is supplied), then the "install" component will be skipped very quickly with a message.

standAlone will either put the Required packages and their dependencies all within the libPath (if TRUE) or if FALSE will only install packages and their dependencies that are otherwise not installed in .libPaths(), i.e., the personal or base library paths. Any packages or dependencies that are not yet installed will be installed in libPath. Importantly, a small hidden file (named ._packageVersionsAuto.txt) will be saved in libPath that will store the information about the packages and their dependencies, even if the version used is located in .libPaths(), i.e., not the libPath provided. This hidden file will be used if a user runs pkgSnapshot, enabling a new user to rebuild the entire dependency chain, without having to install all packages in an isolated directory (as does packrat). This will save potentially a lot of time and disk space, and yet maintain reproducibility. NOTE: since there is only one hidden file in a libPath, any call to pkgSnapshot will make a snapshot of the most recent call to Require.

To build a snapshot of the desired packages and their versions, first run Require with all packages, then pkgSnapshot. If a libPath is used, it must be used in both functions.

This function works best if all required packages are called within one Require call, as all dependencies can be identified together, and all package versions will be saved automatically (with standAlone = TRUE or standAlone = FALSE), allowing a call to pkgSnapshot when a more permanent record of versions can be made.

Examples

# NOT RUN {
# simple usage, like conditional install.packages then library
Require("stats") # analogous to require(stats), but slower because it checks for
                 #   pkg dependencies, and installs them, if missing
tempPkgFolder <- file.path(tempdir(), "Packages")

# use standAlone, means it will put it in libPath, even if it already exists
#   in another local library (e.g., personal library)
Require("crayon", libPath = tempPkgFolder, standAlone = TRUE)

# make a package version snapshot
packageVersionFile <- file.path(tempPkgFolder, ".packageVersion.txt")
pkgSnapshot(libPath=tempPkgFolder, packageVersionFile)

# confirms that correct version is installed
Require("crayon", packageVersionFile = packageVersionFile)

# Create mismatching versions -- desired version is older than current installed
# This will try to install the older version, overwriting the newer version
desiredVersion <- data.frame(instPkgs="crayon", instVers = "1.3.2", stringsAsFactors = FALSE)
write.table(file = packageVersionFile, desiredVersion, row.names = FALSE)
# won't work because newer crayon is loaded
Require("crayon", packageVersionFile = packageVersionFile)

# unload it first
detach("package:crayon", unload = TRUE)

# run again, this time, correct "older" version installs in place of newer one
Require("crayon", packageVersionFile = packageVersionFile)

# Mutual dependencies, only installs once -- e.g., httr
Require(c("cranlogs", "covr"), libPath = tempPkgFolder)
# }
# NOT RUN {
# }