Package {courieR}

courieR: Migrate Installed R Packages Between R Versions

Description

Detects all R installations on the current machine and migrates installed R packages between them. Provides find_routes() to discover R versions, manifest() to scan package libraries via 'subprocess', inventory() to compare two libraries, and ship() to install packages into a target R version using 'pak'. Includes a Shiny dashboard (open_hub()) for interactive one-way and two-way migration.

Author(s)

Maintainer: Lennon Li yeli@biostats.ai

Authors:

• Lennon Li yeli@biostats.ai

See Also

Useful links:

• https://github.com/lennon-li/courieR

• Report bugs at https://github.com/lennon-li/courieR/issues

Run an R command in the background and log output

Description

Run an R command in the background and log output

Usage

dispatch(
  project_path,
  expr,
  phase,
  label,
  rscript_path = NULL,
  timeout_sec = 600L
)

Arguments

Value

A list with process info

Examples

  tmp <- tempdir()
  job <- dispatch(tmp, "message('hello')", "baseline", "document")
  Sys.sleep(1)
  job$process$is_alive()

Detect R installations on the system

Description

Scans the current machine for every R installation it can find, across multiple sources per platform, and returns a tidy data frame of results.

Usage

find_routes(search_paths = NULL)

Arguments

Details

Detection sources by platform:

Windows

• HKLM registry (⁠SOFTWARE\R-core\R⁠) — standard admin installs via the CRAN Windows installer.

• HKCU registry (⁠SOFTWARE\R-core\R⁠) — non-admin installs that register under the current user hive only.

• ⁠%ProgramFiles%\R⁠ — directory scan for admin installs not in the registry.

• ⁠%LOCALAPPDATA%\Programs\R⁠ — rig-managed and other user-local installs.

• ⁠%USERPROFILE%\Documents\R⁠ — installs placed in the user's Documents folder.

• rig (⁠rig list⁠) — any additional versions managed by rig that were not found by path scanning.

macOS

• ⁠/Library/Frameworks/R.framework/Versions⁠ — system-wide CRAN installer.

• ⁠~/Library/Frameworks/R.framework/Versions⁠ — user-local framework installs (no admin required).

• Homebrew: ⁠/opt/homebrew/opt/r⁠ (Apple Silicon) and ⁠/usr/local/opt/r⁠ (Intel).

• rig (⁠rig list⁠) — rig-managed versions.

Linux

• ⁠/opt/R⁠ — rig system-wide installs.

• ⁠~/.local/share/rig/R⁠ — rig user-local installs.

• conda environments (active ⁠$CONDA_PREFIX⁠).

• System Rscript on ⁠$PATH⁠.

Symlinks are resolved via fs::path_real() so that duplicate entries from different detection sources pointing to the same executable are collapsed.

Value

A data frame with one row per unique R installation and the following columns:

version

Character. R version string, e.g. "4.4.1".

rscript_path

Character. Absolute path to the Rscript executable.

is_current

Logical. TRUE for the R session running courieR.

source

Character. Detection source label (e.g. "registry-hklm", "registry-hkcu", "programfiles", "appdata", "documents", "homebrew", "rig", "search_paths").

Examples

routes <- find_routes()
routes[, c("version", "rscript_path", "is_current")]

# include a non-standard install
routes <- find_routes(search_paths = "/opt/custom-r/bin/Rscript")

Detect project characteristics

Description

Detect project characteristics

Usage

inspect_shipment(project_path)

Arguments

Value

A named list

Examples

  res <- inspect_shipment(tempdir())
  res$is_package

Compare two package libraries

Description

Compare two package libraries

Usage

inventory(source_pkgs, target_pkgs)

Arguments

Value

A list of data.tables and a summary data.frame

Examples

src <- data.table::data.table(
  package  = c("dplyr", "ggplot2"),
  version  = c("1.1.4", "3.5.1"),
  priority = NA_character_
)
tgt <- data.table::data.table(
  package = "dplyr",
  version = "1.0.0"
)
inventory(src, tgt)

List packages installed in a library, optionally via a different R executable

Description

List packages installed in a library, optionally via a different R executable

Usage

manifest(
  rscript_path = NULL,
  lib_path = NULL,
  format = c("data.table", "data.frame"),
  timeout_sec = 30L
)

Arguments

Value

data.table

Examples

  pkgs <- manifest()
  head(pkgs)

Ensure the courier depot directory structure exists

Description

Creates ⁠.courier-depot/⁠ and its subdirectories in the project path. Writes a .gitignore to prevent tracking of logs and artifacts.

Usage

open_depot(project_path)

Arguments

Value

Invisibly returns the path to the .courier-depot directory.

Examples

  depot <- open_depot(tempdir())

Launch the courieR delivery hub dashboard

Description

Launch the courieR delivery hub dashboard

Usage

open_hub(project_path = NULL, port = NULL, launch.browser = TRUE)

Arguments

Value

Called for its side effect of launching a Shiny application.

Examples

if (interactive()) {
  open_hub()
}

Parse test log

Description

Parse test log

Usage

parse_dispatch_log(log_path)

Arguments

Value

data.table

Examples

tmp <- tempfile(fileext = ".log")
writeLines(c(
  "-- Failure (test-foo.R:1): addition works ----",
  "Expected 3, got 4."
), tmp)
parse_dispatch_log(tmp)
file.remove(tmp)

Parse R CMD check log

Description

Parse R CMD check log

Usage

parse_inspection_log(log_path)

Arguments

Value

data.table

Examples

tmp <- tempfile(fileext = ".log")
writeLines(c(
  "* checking examples ... WARNING",
  "  An example result is marked with \\donttest."
), tmp)
parse_inspection_log(tmp)
file.remove(tmp)

Classify shipment risk based on check and test results

Description

Classify shipment risk based on check and test results

Usage

rate_shipment(baseline_results, post_results)

Arguments

Value

A list

Examples

baseline <- data.table::data.table(
  severity = character(), message = character(),
  file = character(), line = character()
)
post <- data.table::data.table(
  severity = "ERROR", message = "undefined symbol",
  file = "R/foo.R", line = "10"
)
rate_shipment(baseline, post)

Check if rig is available

Description

Check if rig is available

Usage

rig_available()

Value

Logical

Examples

rig_available()

Install R via rig

Description

Install R via rig

Usage

rig_install(version, wait = TRUE)

Arguments

Value

The result of processx::run().

Examples

if (interactive() && rig_available()) {
  rig_install("4.5.0", wait = FALSE)
}

List rig installations

Description

List rig installations

Usage

rig_list()

Value

data.frame

Examples

  if (rig_available()) rig_list()

Ship packages between R installations

Description

Ship packages between R installations

Usage

ship(
  source_path,
  target_path,
  packages = NULL,
  dry_run = FALSE,
  upgrade = FALSE,
  ...
)

Arguments

Value

A list with shipment results

Safety

ship() installs packages into the target R library via pak::pkg_install() running in a subprocess. Set dry_run = TRUE to preview the migration plan without installing anything. When dry_run = FALSE (the default), pak from the current R session is used to install into the target library, which is the correct design for a migration tool (the source R need not have pak installed). All subprocess calls are confined to the target library path; no files are written outside the target library or the R temporary directory.

Examples

  routes <- find_routes()
  if (nrow(routes) >= 2) {
    result <- ship(
      source_path = routes$rscript_path[1],
      target_path = routes$rscript_path[2],
      dry_run = TRUE
    )
    print(result$plan)
  }

Scan project dependencies

Description

Scan project dependencies

Usage

take_inventory(project_path)

Arguments

Value

A data.table

Examples

  take_inventory(tempdir())

Generate a pak specification for a package

Description

Generate a pak specification for a package

Usage

wrap(package, version = NULL, source_hint = NULL, github_ref = NULL)

Arguments

Value

A character vector of pak specs

Examples

wrap("dplyr")
wrap("dplyr", version = "1.1.4")
wrap("mypackage", source_hint = "Bioconductor")
wrap("r-lib/rlang", source_hint = "GitHub", github_ref = "r-lib/rlang")