% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/RequireOptions.R
\name{RequireOptions}
\alias{RequireOptions}
\alias{getRequireOptions}
\title{\code{Require} options}
\usage{
RequireOptions()

getRequireOptions()
}
\value{
A named list of the package options and their default values.
}
\description{
These provide top-level, powerful settings for a comprehensive reproducible workflow.
See Details below.
}
\details{
\describe{
\item{\code{RequireOptions()}}{prints the default values of package options set at startup,
which may have been changed (e.g., by the user) during the current session.}
\item{\code{getRequireOptions()}}{prints the current values of package options.}
}

Below are options that can be set with \code{options("Require.xxx" = newValue)},
where \code{xxx} is one of the values below, and \code{newValue} is a new value to give
the option. Sometimes these options can be placed in the user's \code{.Rprofile}
file so they persist between sessions.

The following options are likely of interest to most users:
\describe{
\item{\code{install}}{ Default: \code{TRUE}. This is the default argument to \code{Require},
but does not affect \code{Install}. If this is \code{FALSE}, then no installations
will be attempted, and missing packages will result in an error.}
\item{\code{cachePkgDir}}{ Deprecated, and ignored under \code{Require.usePak = TRUE}
(the default): redirect pak's package cache with the \code{R_USER_CACHE_DIR}
environment variable instead. \code{R_REQUIRE_PKG_CACHE} is deprecated for the
same reason. Both are still honoured when \code{Require.usePak = FALSE}.
Default: \code{cacheGetOptionCachePkgDir()}, which must be
either a path or a logical. To turn off package caching, set this to \code{FALSE}.
This can be set using an environment variable e.g.,
\code{Sys.setenv(R_REQUIRE_PKG_CACHE = "somePath")}, or
\code{Sys.setenv(R_REQUIRE_PKG_CACHE = "TRUE")}; if that is not set, then an
either a path or logical option (\code{options(Require.cachePkgDir = "somePath")}
or \code{options(Require.cachePkgDir = TRUE)}).
If \code{TRUE}, the default folder location \code{cachePkgDir()} will be used.
If this is \code{TRUE} or a path is provided, then binary and source packages will be cached here.
Subsequent downloads of same package will use local copy.
Default is to have packages not be cached locally so each install of the same version will
be from the original source, e.g., CRAN, GitHub.}
\item{\code{otherPkgs}}{Default: A character vector of packages that are
generally more successful if installed from Source on Unix-alikes. Since
there are repositories that offer binary packages builds for Linux (e.g.,
RStudio Package Manager), the vector of package names indicated here will
default to a standard CRAN repository, forcing a source install. See also
\code{spatialPkgs} option, which does the same for spatial packages.}
\item{\code{noRemotes}}{ Default: \code{FALSE}. If \code{TRUE}, GitHub-style specs
(\code{account/repo@branch}) passed to \code{Require}/\code{Install} are rewritten to their
bare package name (the version constraint, if any, is preserved). The
packages are then resolved from \code{repos} (e.g., a CRAN-like or r-universe
repository serving prebuilt binaries) instead of being cloned and built
from GitHub source. This avoids the need for git authentication and a
source-build toolchain (e.g., Rtools on Windows), which is useful for
workshops and other binary-only setups. Because version constraints are
kept, \code{repos} must provide a version that satisfies them, otherwise
resolution will fail (rather than silently falling back to GitHub). Ensure
the relevant repository (e.g., \code{predictiveecology.r-universe.dev}) is in
\code{getOption("repos")}.}
\item{\code{purge}}{Default: \code{FALSE}. If set to (almost) all internal caches used
by \code{Require} will be deleted and rebuilt. This should not generally be
necessary as it will automatically be deleted after (by default) 1 hour (set
via \code{R_AVAILABLE_PACKAGES_CACHE_CONTROL_MAX_AGE} environment variable in seconds).}
\item{\code{cloneFrom}}{ Default: \code{NULL}. A path to an existing package library.
When set, any package that is already installed there at the version being
requested is copied or hard-linked into the destination library instead of
being downloaded and installed, which is much faster when populating a new
project library on a machine that already has the packages. Only packages
that need no compilation and were built under a compatible R version are
cloned; the rest go through the normal install machinery, as do \code{pak},
\code{callr}, \code{processx} and \code{cli}, whose native helper executables do not
survive a file-by-file copy. Has no effect under \code{Require.usePak = TRUE}
(the default): cloning lives in the legacy (non-pak) install path, so this
option is consulted only when \code{Require.usePak = FALSE}.}
\item{\code{downloadTimeout}}{Default: \code{300L} (seconds). Used as the floor for
\code{options("timeout")} during GitHub source-archive downloads in the legacy
(non-pak) install path. R's stock 60-second timeout is too short for
slow connections fetching multi-MB zips. Has no effect under
\code{Require.usePak = TRUE}, which delegates downloads to pak's own libcurl
client.}
\item{\code{spatialPkgs}}{ Default: A character vector of packages that are
generally more successful if installed from Source on Unix-alikes. Since
there are repositories that offer binary packages builds for Linux (e.g.,
Posit Package Manager), the vector of package names indicated here will
default to a standard CRAN repository, forcing a source install.
See also \code{otherPkgs} option, which does the same for non-spatial packages.}
\item{\code{useCranCache}}{ Default: \code{FALSE}. A user can optionally use the locally
cached packages that are available due to a user's use of the \code{crancache} package.
}
\item{\code{checkInternet}}{ Default: \code{TRUE}. Whether \code{Require} may run a short
internet probe before work that needs the network. Results are cached for
\code{Require.internetExistsTimeout} seconds (30). Setting this \code{FALSE} skips
the probe at most call sites, but not those that pass \code{force = TRUE},
where failing late costs more than a 2-second check.}
\item{\code{forcePakReinstall}}{ Default: \code{FALSE}. Set \code{TRUE} to force one clean
\code{install.packages("pak")} into the project library. This is the remedy for
a pak whose bundled callr/processx helper executables no longer run --
the state a file-by-file copy of a library leaves pak in. \code{find.package()}
cannot detect that (every file is present, they just do not run), so the
reinstall has to be asked for explicitly.}
\item{\code{installPackagesSys}}{ Default: \code{2L}. Legacy (non-pak) path only.
\code{0} installs in-process with \code{install.packages()}; a non-zero value runs
builds and installs through the \code{sys} package in a subprocess; \code{2}
additionally performs the CRAN downloads itself rather than leaving them
to \code{install.packages()}. Requires the \code{sys} package.}
\item{\code{offlineMode}}{ Default: \code{FALSE}. When \code{TRUE}, \code{Require} attempts no
network access and installs only from local caches. It is also set
automatically -- together with \code{Require.offlineModeSetAutomatically} --
when an install fails and an internet probe finds no connection.}
\item{\code{packageVersionFile}}{ Default: \code{"packageVersions.txt"}. The default
file path used by \code{pkgSnapshot()} when writing a snapshot.}
\item{\code{snapshotInstaller}}{ Default: \code{"pak"}. Which installer to use for a
snapshot install. \code{"install.packages"} selects the pre-pak chain, which is
retained but no longer developed. See \code{?pkgSnapshot} for the rest of the
snapshot-installer options.}
\item{\code{snapshotInstallerUsePPM}}{ Default: \code{TRUE}. Prepend a Posit Package
Manager binary repository when installing a snapshot through the
\code{install.packages} chain. PPM serves macOS binaries by content-negotiating
the \verb{R/<version>} User-Agent.}
\item{\code{standAlone}}{ Default: \code{TRUE}. The default \code{standAlone} argument for
\code{Require}, \code{Install} and \code{setLibPaths()}. \code{TRUE} means the given library
path is used on its own, without the user and site libraries appended;
\code{FALSE} appends them. It controls whether those libraries are added, not
how many library paths may be given -- passing several is always allowed.}
\item{\code{updateRprofile}}{ Default: \code{FALSE}. Whether \code{setLibPaths()} also
writes the library path into the project \code{.Rprofile}, so it persists
across sessions.}
\item{\code{usePak}}{ Default: \code{TRUE}. Use pak to resolve and install packages.
\code{FALSE} selects the pre-pak path. Several options apply only to that path
and do nothing under the default: \code{cachePkgDir}, \code{cloneFrom},
\code{downloadTimeout} and \code{installPackagesSys}.}
\item{\code{verbose}}{ Default: \code{1}. See ?Require. }
}
}
