zzz-pkgdepends-config.R

windows_archs <- function() c("prefer-x64", "both")

default_windows_archs <- function() {
  if (getRversion() < "4.2.0") "both" else "prefer-x64"
}

default_update_after <- function() as.difftime(24, units = "hours")

env_decode_dependencies <- function(x, name, ...) {
  if (tolower(x) %in% c("yes", "true", "1", "on")) {
    return(TRUE)
  }
  if (tolower(x) %in% c("no", "false", "0", "off")) {
    return(FALSE)
  }
  if (tolower(x) == "na") {
    return(NA)
  }
  strsplit(x, ";", fixed = TRUE)[[1]]
}

is_configure_opts <- function(x) {
  is.null(x) ||
    (is.character(x) && !anyNA(x)) ||
    (is.list(x) &&
      all(vapply(
        x,
        function(e) is.character(e) && !anyNA(e),
        logical(1)
      )))
}

env_decode_configure_opts <- function(x, name, ...) {
  if (!nzchar(x)) {
    return(character())
  }
  parts <- strsplit(x, ";", fixed = TRUE)[[1]]
  # Named form: every `;`-separated part looks like `<pkgname>=<value>`.
  named <- regexpr("^[a-zA-Z][a-zA-Z0-9._]*=", parts) == 1L
  if (length(parts) && all(named)) {
    nms <- sub("=.*$", "", parts)
    vals <- sub("^[^=]*=", "", parts)
    stats::setNames(vals, nms)
  } else {
    x
  }
}

configure_flag <- function(val, pkg, flag) {
  if (length(val) == 0) {
    return(character())
  }
  nms <- names(val)
  if (is.null(nms) || all(!nzchar(nms))) {
    # unnamed: applies to every package built from source
    vals <- unlist(val, use.names = FALSE)
  } else if (pkg %in% nms) {
    vals <- val[[pkg]]
  } else {
    return(character())
  }
  vals <- vals[nzchar(vals)]
  if (length(vals) == 0) {
    return(character())
  }
  paste0(flag, "=", shQuote(paste(vals, collapse = " ")))
}

env_decode_difftime <- function(x, name, ...) {
  if (nchar(x) >= 2) {
    unit <- substr(x, nchar(x), nchar(x))
    unit <- c(s = "secs", m = "mins", h = "hours", d = "days")[unit]
    qty <- suppressWarnings(as.numeric(substr(x, 1, nchar(x) - 1)))
    if (!is.na(unit) && !is.na(qty)) {
      return(as.difftime(qty, units = unit))
    }
  }
  throw(pkg_error(
    "Invalid time interval specification in {.envvar {name}} environment
     variable: {.str {x}}",
    i = "It must have the form {.code <number><unit>}.",
    i = "The unit must be a single letter: {.code s} (seconds),
     {.code m} (minutes), {.code h} (hours) or {.code d} (days).",
    i = "Examples: {.emph 60s}, {.emph 2h}, {.emph 1d}."
  ))
}

default_library <- function(config) {
  lp <- .libPaths()
  if (config$get("ignore_dev_library")) {
    lp <- lp[basename(lp) != "__dev_lib__"]
  }
  lp[1L]
}

default_sysreqs_platform <- function() {
  pkgcache::current_r_platform()
}

default_sysreqs <- function(config) {
  plt <- config$get("sysreqs_platform")
  sysreqs_is_supported(plt) &&
    (is_root() || can_sudo_without_pw())
}

default_sysreqs_sudo <- function() {
  if (os_type() != "unix") {
    FALSE
  } else {
    euid <- get_euid()
    is.na(euid) || euid != 0
  }
}

default_sysreqs_update <- function() {
  Sys.getenv("CI") == "true"
}

default_sysreqs_verbose <- function() {
  Sys.getenv("CI") != ""
}

default_sysreqs_rspm_url <- function() {
  Sys.getenv("RSPM_ROOT", "https://packagemanager.posit.co")
}

default_sysreqs_rspm_repo_id <- function() {
  Sys.getenv("RSPM_REPO_ID", "1")
}

pkgdepends_config <- sort_by_name(list(
  # -----------------------------------------------------------------------
  build_vignettes = list(
    type = "flag",
    default = FALSE,
    docs = "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 = list(
    type = "string",
    default = function() detect_download_cache_dir(),
    docs = "Directory to download the packages to. Defaults to a temporary
       directory within the R session temporary directory, see
       [base::tempdir()]."
  ),

  # -----------------------------------------------------------------------
  configure_args = list(
    type = "configure_opts",
    default = function() getOption("configure.args") %||% character(),
    docs = "Extra `--configure-args` to pass to `R CMD INSTALL` when
       building packages from source. It can be a single string, which is
       then used for all packages built from source. It can also be a named
       character vector (or a named list of character vectors) to set
       configure arguments for individual packages: the names are package
       names and the values are the corresponding configure arguments.
       Defaults to the `configure.args` option (see [base::options()]), for
       compatibility with [utils::install.packages()]. The
       `PKG_CONFIGURE_ARGS` environment variable may be either a single
       string (used for all packages), or a semicolon separated list of
       `<package>=<args>` entries to set arguments for individual packages."
  ),

  # -----------------------------------------------------------------------
  configure_vars = list(
    type = "configure_opts",
    default = function() getOption("configure.vars") %||% character(),
    docs = "Extra `--configure-vars` to pass to `R CMD INSTALL` when
       building packages from source. It can be a single string, which is
       then used for all packages built from source. It can also be a named
       character vector (or a named list of character vectors) to set
       configure variables for individual packages: the names are package
       names and the values are the corresponding configure variables.
       Defaults to the `configure.vars` option (see [base::options()]), for
       compatibility with [utils::install.packages()]. The
       `PKG_CONFIGURE_VARS` environment variable may be either a single
       string (used for all packages), or a semicolon separated list of
       `<package>=<vars>` entries to set variables for individual packages."
  ),

  # -----------------------------------------------------------------------
  cran_mirror = list(
    type = "string",
    default = function() default_cran_mirror(),
    docs = "CRAN mirror to use. Defaults to the `repos` option
       (see [base::options()]), if that's not set then
       `https://cran.rstudio.com`.",
    docs_pak = "CRAN mirror to use. Defaults to the `repos` option
       (see [base::options()]), if that's not set then
       `https://cran.rstudio.com`. See also [pak::repo_add()] and
       [pak::repo_get()]"
  ),

  # -----------------------------------------------------------------------
  dependencies = list(
    type = "dependencies",
    default = function() pkg_dep_types_hard(),
    # pak functions take this as an argument, so we do not need it, for now
    pak = FALSE,
    docs = "Dependencies to consider or download or install.
       Defaults to the hard dependencies, see
       [pkgdepends::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 [pkgdepends::as_pkg_dependencies()] for
       details."
  ),

  # -----------------------------------------------------------------------
  git_submodules = list(
    type = "flag",
    default = FALSE,
    docs = "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."
  ),

  # -----------------------------------------------------------------------
  http_retry = list(
    forwarded = TRUE,
    option = "pkg_http_retry",
    envvar = "PKG_HTTP_RETRY",
    docs = "Whether to retry failed HTTP requests. It can be `TRUE` to retry
       with the default settings, or `FALSE` to never retry. Defaults to
       `TRUE`. This entry is handled by pkgcache, which performs all HTTP
       requests."
  ),

  # -----------------------------------------------------------------------
  ignore_dev_library = list(
    type = "flag",
    default = TRUE,
    docs = "Whether to ignore library directories called `__dev_lib__`."
  ),

  # -----------------------------------------------------------------------
  include_linkingto = list(
    type = "flag",
    default = FALSE,
    docs = "Whether to always include `LinkingTo` dependencies in the solution
       of and installation, even if they are not 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.
       It is also needed if a repository (Posit Package Manager typically)
       might serve a source package instead of a binary, so that the source
       package can be built, see
       <https://github.com/r-lib/pak/issues/891>."
  ),

  # -----------------------------------------------------------------------
  library = list(
    type = "character_or_null",
    default = function(config) default_library(config),
    docs = "Package library to install packages to. It is also used for
       already installed packages when considering dependencies in
       [dependency lookup][pkg_deps] or
       [package installation][pkg_installation_proposal]. Defaults to the
       first path in [.libPaths()].",
    docs_pak = "Package library to install packages to. It is also used for
       already installed packages when considering dependencies."
  ),

  # -----------------------------------------------------------------------
  metadata_cache_dir = list(
    type = "string",
    default = function() tempfile(),
    # TODO: do not link to pkgcache docs from pak
    docs = "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 = list(
    type = "difftime",
    default = function() default_update_after(),
    docs = "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.",
    docs_pak = "A time interval as a [difftime] object. pak 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 = list(
    type = "string",
    docs = "Package cache location of [`pkgcache::package_cache`]. The default
       is the pkgcache default.",
    docs_pak = "Location of the package cache on the disk. See
       [pak::cache_summary()]. Default is selected by pkgcache."
  ),

  # -----------------------------------------------------------------------
  platforms = list(
    type = "character",
    default = function() default_platforms(),
    # TODO: do not link to pkgdepends docs from pak
    docs = "Character vector of platforms to _download_ or _install_ packages
       for. See [pkgdepends::default_platforms()] for possible platform
       names. Defaults to the platform of the current R session, plus
       `\"source\"`."
  ),

  # -----------------------------------------------------------------------
  r_versions = list(
    type = "character",
    default = function() current_r_version(),
    check = is_r_version_list,
    docs = "Character vector, R versions to download or install
       packages for. It defaults to the current R version."
  ),

  # -----------------------------------------------------------------------
  sysreqs = list(
    type = "flag",
    default = function(config) default_sysreqs(config),
    docs = "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 = list(
    type = "flag",
    default = TRUE,
    docs = "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 = list(
    type = "difftime",
    default = function() {
      as.difftime(if (Sys.getenv("CI") == "") 5 else 60, units = "secs")
    },
    docs = "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 = list(
    type = "flag",
    default = FALSE,
    docs = "If `TRUE`, then pkgdepends only prints the system commands to
       install system requirements, but does not execute them.",
    docs_pak = "If `TRUE`, then pak only prints the system commands to
       install system requirements, but does not execute them."
  ),

  # -----------------------------------------------------------------------
  sysreqs_platform = list(
    type = "string",
    default = function() default_sysreqs_platform(),
    docs = "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 = list(
    type = "string",
    default = function() default_sysreqs_rspm_repo_id(),
    docs = "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 = list(
    type = "string",
    default = function() default_sysreqs_rspm_url(),
    docs = "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 = list(
    type = "flag",
    default = function() default_sysreqs_sudo(),
    docs = "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 = list(
    type = "flag",
    default = function() default_sysreqs_update(),
    docs = "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 = list(
    type = "flag",
    default = function() default_sysreqs_verbose(),
    docs = "Whether to echo the output of system requirements installation.
       Defaults to `TRUE` if the `CI` environment variable is set."
  ),

  # -----------------------------------------------------------------------
  use_bioconductor = list(
    type = "flag",
    default = TRUE,
    docs = "Whether to automatically use the Bioconductor repositories.
       Defaults to `TRUE`."
  ),

  # -----------------------------------------------------------------------
  windows_archs = list(
    type = "string",
    default = function() default_windows_archs(),
    # we can't indent this "correctly" because markdown will take it as code
    docs = "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."
  ),

  # -----------------------------------------------------------------------
  # Internal
  goal = list(
    type = "string",
    default = "unknown"
  ),
  sysreqs_lookup_system = list(
    type = "flag",
    default = TRUE
  )
))

#' pkgdepends configuration
#' @name pkg_config
#' @aliases pkgdepends-config pkgdepends_config
#'
#' @description
#' Configuration entries for several pkgdepends classes.
#'
#' @export
#' @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
#'
#' `r generate_config_docs()`

current_config <- function() {
  conf <- config$new("pkg")
  conf$add_type("dependencies", is_dependencies, env_decode_dependencies)
  conf$add_type("difftime", is_difftime, env_decode_difftime)
  conf$add_type(
    "configure_opts",
    is_configure_opts,
    env_decode_configure_opts
  )

  map_named(pkgdepends_config, function(name, entry) {
    if (isTRUE(entry$forwarded)) {
      conf$add_forwarded(name, option = entry$option, envvar = entry$envvar)
    } else {
      type <- entry$type %||% "character"
      conf$add(
        name,
        type,
        default = entry$default,
        check = entry$check %||% type,
        env_decode = entry$env_decode %||% type
      )
    }
  })

  conf$lock()
  conf
}