renv/ 0000755 0001762 0000144 00000000000 14606061022 011221 5 ustar ligges users renv/NAMESPACE 0000644 0001762 0000144 00000003356 14464550375 012467 0 ustar ligges users # Generated by roxygen2: do not edit by hand
export(activate)
export(autoload)
export(checkout)
export(clean)
export(config)
export(consent)
export(deactivate)
export(dependencies)
export(diagnostics)
export(embed)
export(equip)
export(history)
export(hydrate)
export(init)
export(install)
export(isolate)
export(load)
export(lockfile_create)
export(lockfile_modify)
export(lockfile_read)
export(lockfile_write)
export(migrate)
export(modify)
export(paths)
export(project)
export(purge)
export(rebuild)
export(record)
export(refresh)
export(rehash)
export(remove)
export(repair)
export(restore)
export(revert)
export(run)
export(sandbox)
export(scaffold)
export(settings)
export(snapshot)
export(status)
export(update)
export(upgrade)
export(use)
export(use_python)
importFrom(tools,file_ext)
importFrom(tools,pskill)
importFrom(tools,psnice)
importFrom(tools,write_PACKAGES)
importFrom(utils,Rprof)
importFrom(utils,URLencode)
importFrom(utils,adist)
importFrom(utils,available.packages)
importFrom(utils,browseURL)
importFrom(utils,citation)
importFrom(utils,contrib.url)
importFrom(utils,download.file)
importFrom(utils,download.packages)
importFrom(utils,file.edit)
importFrom(utils,getCRANmirrors)
importFrom(utils,head)
importFrom(utils,help)
importFrom(utils,install.packages)
importFrom(utils,installed.packages)
importFrom(utils,modifyList)
importFrom(utils,old.packages)
importFrom(utils,packageDescription)
importFrom(utils,packageVersion)
importFrom(utils,read.table)
importFrom(utils,remove.packages)
importFrom(utils,sessionInfo)
importFrom(utils,str)
importFrom(utils,summaryRprof)
importFrom(utils,tail)
importFrom(utils,tar)
importFrom(utils,toBibtex)
importFrom(utils,untar)
importFrom(utils,unzip)
importFrom(utils,update.packages)
importFrom(utils,zip)
renv/LICENSE 0000644 0001762 0000144 00000000061 14606007442 012231 0 ustar ligges users YEAR: 2024
COPYRIGHT HOLDER: Posit Software, PBC
renv/README.md 0000644 0001762 0000144 00000007124 14605660506 012517 0 ustar ligges users
# renv
[](https://lifecycle.r-lib.org/articles/stages.html)
[](https://CRAN.R-project.org/package=renv)
[](https://github.com/rstudio/renv/actions)
## Overview
The renv package[^1] helps you create **r**eproducible **env**ironments
for your R projects. Use renv to make your R projects more isolated,
portable and reproducible.
- **Isolated**: Installing a new or updated package for one project
won’t break your other projects, and vice versa. That’s because renv
gives each project its own private library.
- **Portable**: Easily transport your projects from one computer to
another, even across different platforms. renv makes it easy to
install the packages your project depends on.
- **Reproducible**: renv records the exact package versions you depend
on, and ensures those exact versions are the ones that get installed
wherever you go.
## Installation
Install the latest version of renv from CRAN with:
``` r
install.packages("renv")
```
## Workflow
Use `renv::init()` to initialize renv in a new or existing project. This
will set up a **project library**, containing all the packages you’re
currently using. The packages (and all the metadata needed to reinstall
them) are recorded into a **lockfile**, `renv.lock`, and a `.Rprofile`
ensures that the library is used every time you open that project.
As you continue to work on your project, you will install and upgrade
packages, either using `install.packages()` and `update.packages` or
`renv::install()` and `renv::update()`. After you’ve confirmed your code
works as expected, use `renv::snapshot()` to record the packages and
their sources in the lockfile.
Later, if you need to share your code with someone else or run your code
on new machine, your collaborator (or you) can call `renv::restore()` to
reinstall the specific package versions recorded in the lockfile.
## Learning more
If this is your first time using renv, we strongly recommend starting
with the [Introduction to
renv](https://rstudio.github.io/renv/articles/renv.html) vignette: this
will help you understand the most important verbs and nouns of renv.
If you have a question about renv, please first check the
[FAQ](https://rstudio.github.io/renv/articles/faq.html) to see whether
your question has already been addressed. If it hasn’t, please feel free
to ask on the [Posit Forum](https://forum.posit.co).
If you believe you’ve found a bug in renv, please file a bug (and, if
possible, a [reproducible example](https://reprex.tidyverse.org)) at
.
[^1]: Pronounced “R” “env”
renv/man/ 0000755 0001762 0000144 00000000000 14573145613 012010 5 ustar ligges users renv/man/snapshot.Rd 0000644 0001762 0000144 00000015660 14475733536 014156 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/snapshot.R
\name{snapshot}
\alias{snapshot}
\title{Record current state of the project library in the lockfile}
\usage{
snapshot(
project = NULL,
...,
library = NULL,
lockfile = paths$lockfile(project = project),
type = settings$snapshot.type(project = project),
dev = FALSE,
repos = getOption("repos"),
packages = NULL,
exclude = NULL,
prompt = interactive(),
update = FALSE,
force = FALSE,
reprex = FALSE
)
}
\arguments{
\item{project}{The project directory. If \code{NULL}, then the active project will
be used. If no project is currently active, then the current working
directory is used instead.}
\item{...}{Unused arguments, reserved for future expansion. If any arguments
are matched to \code{...}, renv will signal an error.}
\item{library}{The \R libraries to snapshot. When \code{NULL}, the active \R
libraries (as reported by \code{.libPaths()}) are used.}
\item{lockfile}{The location where the generated lockfile should be written.
By default, the lockfile is written to a file called \code{renv.lock} in the
project directory. When \code{NULL}, the lockfile (as an \R object) is returned
directly instead.}
\item{type}{The type of snapshot to perform:
\itemize{
\item \code{"implict"}, (the default), uses all packages captured by \code{\link[=dependencies]{dependencies()}}.
\item \code{"explicit"} uses packages recorded in \code{DESCRIPTION}.
\item \code{"all"} uses all packages in the project library.
\item \code{"custom"} uses a custom filter.
}
See \strong{Snapshot type} below for more details.}
\item{dev}{Boolean; include development dependencies? These packages are
typically required when developing the project, but not when running it
(i.e. you want them installed when humans are working on the project but
not when computers are deploying it).
Development dependencies include packages listed in the \code{Suggests} field
of a \code{DESCRIPTION} found in the project root, and roxygen2 or devtools if
their use is implied by other project metadata. They also include packages
used in \verb{~/.Rprofile} if \code{config$user.profile()} is \code{TRUE}.}
\item{repos}{The \R repositories to be recorded in the lockfile. Defaults
to the currently active package repositories, as retrieved by
\code{getOption("repos")}.}
\item{packages}{A vector of packages to be included in the lockfile. When
\code{NULL} (the default), all packages relevant for the type of snapshot being
performed will be included. When set, the \code{type} argument is ignored.
Recursive dependencies of the specified packages will be added to the
lockfile as well.}
\item{exclude}{A vector of packages to be explicitly excluded from the lockfile.
Note that transitive package dependencies will always be included, to avoid
potentially creating an incomplete / non-functional lockfile.}
\item{prompt}{Boolean; prompt the user before taking any action? For backwards
compatibility, \code{confirm} is accepted as an alias for \code{prompt}.}
\item{update}{Boolean; if the lockfile already exists, then attempt to update
that lockfile without removing any prior package records.}
\item{force}{Boolean; force generation of a lockfile even when pre-flight
validation checks have failed?}
\item{reprex}{Boolean; generate output appropriate for embedding the lockfile
as part of a \href{https://www.tidyverse.org/help/#reprex}{reprex}?}
}
\value{
The generated lockfile, as an \R object (invisibly). Note that
this function is normally called for its side effects.
}
\description{
Call \code{renv::snapshot()} to update a \link{lockfile} with the current state of
dependencies in the project library. The lockfile can be used to later
\link{restore} these dependencies as required.
It's also possible to call \code{renv::snapshot()} with a non-renv project,
in which case it will record the current state of dependencies in the
current library paths. This makes it possible to \link{restore} the current packages,
providing lightweight portability and reproducibility without isolation.
If you want to automatically snapshot after each change, you can
set \code{config$config$auto.snapshot(TRUE)}, see \code{?config} for more details.
}
\section{Snapshot types}{
Depending on how you prefer to manage dependencies, you might prefer
selecting a different snapshot mode. The modes available are as follows:
\describe{
\item{\code{"implicit"}}{
(The default) Capture only packages which appear to be used in your project,
as determined by \code{renv::dependencies()}. This ensures that only the packages
actually required by your project will enter the lockfile; the downside
if it might be slow if your project contains a large number of files.
If speed becomes an issue, you might consider using \code{.renvignore} files to
limit which files renv uses for dependency discovery, or switching to
explicit mode, as described next.
}
\item{\code{"explicit"}}{
Only capture packages which are explicitly listed in the project
\code{DESCRIPTION} file. This workflow is recommended for users who wish to
manage their project's \R package dependencies directly.
}
\item{\code{"all"}}{
Capture all packages within the active \R libraries in the lockfile.
This is the quickest and simplest method, but may lead to undesired
packages (e.g. development dependencies) entering the lockfile.
}
\item{\code{"custom"}}{
Like \code{"implicit"}, but use a custom user-defined filter instead. The filter
should be specified by the \R option \code{renv.snapshot.filter}, and should
either be a character vector naming a function (e.g. \code{"package::method"}),
or be a function itself. The function should only accept one argument (the
project directory), and should return a vector of package names to include
in the lockfile.
}
}
You can change the snapshot type for the current project with \code{\link[=settings]{settings()}}.
For example, the following code will switch to using \code{"explicit"} snapshots:
\if{html}{\out{
}}
When the \code{packages} argument is set, \code{type} is ignored, and instead only the
requested set of packages, and their recursive dependencies, will be written
to the lockfile.
}
\examples{
\dontrun{
# disable automatic snapshots
auto.snapshot <- getOption("renv.config.auto.snapshot")
options(renv.config.auto.snapshot = FALSE)
# initialize a new project (with an empty R library)
renv::init(bare = TRUE)
# install digest 0.6.19
renv::install("digest@0.6.19")
# save library state to lockfile
renv::snapshot()
# remove digest from library
renv::remove("digest")
# check library status
renv::status()
# restore lockfile, thereby reinstalling digest 0.6.19
renv::restore()
# restore automatic snapshots
options(renv.config.auto.snapshot = auto.snapshot)
}
}
\seealso{
More on handling package \code{\link[=dependencies]{dependencies()}}
Other reproducibility:
\code{\link{lockfiles}},
\code{\link{restore}()}
}
\concept{reproducibility}
renv/man/install.Rd 0000644 0001762 0000144 00000013101 14565235355 013745 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/install.R
\name{install}
\alias{install}
\title{Install packages}
\usage{
install(
packages = NULL,
...,
exclude = NULL,
library = NULL,
type = NULL,
rebuild = FALSE,
repos = NULL,
prompt = interactive(),
dependencies = NULL,
verbose = NULL,
lock = FALSE,
project = NULL
)
}
\arguments{
\item{packages}{Either \code{NULL} (the default) to install all packages required
by the project, or a character vector of packages to install. renv
supports a subset of the remotes syntax used for package installation,
e.g:
\itemize{
\item \code{pkg}: install latest version of \code{pkg} from CRAN.
\item \code{pkg@version}: install specified version of \code{pkg} from CRAN.
\item \code{username/repo}: install package from GitHub
\item \code{bioc::pkg}: install \code{pkg} from Bioconductor.
}
See \url{https://remotes.r-lib.org/articles/dependencies.html} and the examples
below for more details.
renv deviates from the remotes spec in one important way: subdirectories
are separated from the main repository specification with a \code{:}, not \code{/}.
So to install from the \code{subdir} subdirectory of GitHub package
\code{username/repo} you'd use \verb{"username/repo:subdir}.}
\item{...}{Unused arguments, reserved for future expansion. If any arguments
are matched to \code{...}, renv will signal an error.}
\item{exclude}{Packages which should not be installed. \code{exclude} is useful
when using \code{renv::install()} to install all dependencies in a project,
except for a specific set of packages.}
\item{library}{The \R library to be used. When \code{NULL}, the active project
library will be used instead.}
\item{type}{The type of package to install ("source" or "binary"). Defaults
to the value of \code{getOption("pkgType")}.}
\item{rebuild}{Force packages to be rebuilt, thereby bypassing any installed
versions of the package available in the cache? This can either be a
boolean (indicating that all installed packages should be rebuilt), or a
vector of package names indicating which packages should be rebuilt.}
\item{repos}{The repositories to use when restoring packages installed
from CRAN or a CRAN-like repository. By default, the repositories recorded
in the lockfile will be, ensuring that (e.g.) CRAN packages are
re-installed from the same CRAN mirror.
Use \code{repos = getOption("repos")} to override with the repositories set
in the current session, or see the \code{repos.override} option in \link{config} for
an alternate way override.}
\item{prompt}{Boolean; prompt the user before taking any action? For backwards
compatibility, \code{confirm} is accepted as an alias for \code{prompt}.}
\item{dependencies}{A vector of DESCRIPTION field names that should be used
for package dependency resolution. When \code{NULL} (the default), the value
of \code{renv::settings$package.dependency.fields} is used. The aliases
"strong", "most", and "all" are also supported.
See \code{\link[tools:package_dependencies]{tools::package_dependencies()}} for more details.}
\item{verbose}{Boolean; report output from \verb{R CMD build} and \verb{R CMD INSTALL}
during installation? When \code{NULL} (the default), the value of \code{config$install.verbose()}
will be used. When \code{FALSE}, installation output will be emitted only if
a package fails to install.}
\item{lock}{Boolean; update the \code{renv.lock} lockfile after the successful
installation of the requested packages?}
\item{project}{The project directory. If \code{NULL}, then the active project will
be used. If no project is currently active, then the current working
directory is used instead.}
}
\value{
A named list of package records which were installed by renv.
}
\description{
Install one or more \R packages, from a variety of remote sources.
\code{install()} uses the same machinery as \code{\link[=restore]{restore()}} (i.e. it uses cached
packages where possible) but it does not respect the lockfile, instead
installing the latest versions available from CRAN.
See \code{vignette("package-install")} for more details.
}
\section{\code{Remotes}}{
\code{install()} (called without arguments) will respect the \code{Remotes} field
of the \code{DESCRIPTION} file (if present). This allows you to specify places
to install a package other than the latest version from CRAN.
See \url{https://remotes.r-lib.org/articles/dependencies.html} for details.
}
\section{Bioconductor}{
Packages from Bioconductor can be installed by using the \verb{bioc::} prefix.
For example,
\if{html}{\out{
}}
will install the latest-available version of Biobase from Bioconductor.
renv depends on BiocManager (or, for older versions of \R, BiocInstaller)
for the installation of packages from Bioconductor. If these packages are
not available, renv will attempt to automatically install them before
fulfilling the installation request.
}
\examples{
\dontrun{
# install the latest version of 'digest'
renv::install("digest")
# install an old version of 'digest' (using archives)
renv::install("digest@0.6.18")
# install 'digest' from GitHub (latest dev. version)
renv::install("eddelbuettel/digest")
# install a package from GitHub, using specific commit
renv::install("eddelbuettel/digest@df55b00bff33e945246eff2586717452e635032f")
# install a package from Bioconductor
# (note: requires the BiocManager package)
renv::install("bioc::Biobase")
# install a package, specifying path explicitly
renv::install("~/path/to/package")
# install packages as declared in the project DESCRIPTION file
renv::install()
}
}
renv/man/equip.Rd 0000644 0001762 0000144 00000001042 14441721610 013406 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/equip.R
\name{equip}
\alias{equip}
\title{Install required system libraries}
\usage{
equip()
}
\value{
This function is normally called for its side effects.
}
\description{
Equip your system with libraries commonly-used during compilation of
base and recommended \R packages. This was previously useful with older
versions of R on windows, but is no longer terribly helpful.
}
\examples{
\dontrun{
# download useful build tools
renv::equip()
}
}
\keyword{internal}
renv/man/init.Rd 0000644 0001762 0000144 00000007705 14575106076 013255 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/init.R
\name{init}
\alias{init}
\title{Use renv in a project}
\usage{
init(
project = NULL,
...,
profile = NULL,
settings = NULL,
bare = FALSE,
force = FALSE,
repos = NULL,
bioconductor = NULL,
load = TRUE,
restart = interactive()
)
}
\arguments{
\item{project}{The project directory. When \code{NULL} (the default), the current
working directory will be used. The \R working directory will be
changed to match the requested project directory.}
\item{...}{Unused arguments, reserved for future expansion. If any arguments
are matched to \code{...}, renv will signal an error.}
\item{profile}{The profile to be activated. See
\code{vignette("profiles", package = "renv")} for more information.}
\item{settings}{A list of \link{settings} to be used with the newly-initialized
project.}
\item{bare}{Boolean; initialize the project with an empty project library,
without attempting to discover and install \R package dependencies?}
\item{force}{Boolean; force initialization? By default, renv will refuse
to initialize the home directory as a project, to defend against accidental
misusages of \code{init()}.}
\item{repos}{The \R repositories to be used in this project.
See \strong{Repositories} for more details.}
\item{bioconductor}{The version of Bioconductor to be used with this project.
Setting this may be appropriate if renv is unable to determine that your
project depends on a package normally available from Bioconductor. Set this
to \code{TRUE} to use the default version of Bioconductor recommended by the
BiocManager package.}
\item{load}{Boolean; should the project be loaded after it is initialized?}
\item{restart}{Boolean; attempt to restart the \R session after initializing
the project? A session restart will be attempted if the \code{"restart"} \R
option is set by the frontend hosting \R.}
}
\value{
The project directory, invisibly. Note that this function is normally
called for its side effects.
}
\description{
Call \code{renv::init()} to start using renv in the current project. This will:
\enumerate{
\item Set up project infrastructure (as described in \code{\link[=scaffold]{scaffold()}}) including
the project library and the \code{.Rprofile} that ensures renv will be
used in all future sessions,
\item Discover the packages that are currently being used in your project
(via \code{\link[=dependencies]{dependencies()}}), and install them into the project library
(as described in \code{\link[=hydrate]{hydrate()}}),
\item Create a lockfile that records the state of the project library so it
can be restored by others (as described in \code{\link[=snapshot]{snapshot()}}),
\item Restart R (if running inside RStudio).
}
If you call \code{renv::init()} with a project that is already using renv, it will
attempt to do the right thing: it will restore the project library if it's
missing, or otherwise ask you what to do.
}
\section{Repositories}{
If the default \R repositories have not already been set, renv will use
the \href{https://packagemanager.posit.co/}{Posit Public Package Manager} CRAN
mirror for package installation. The primary benefit to using this mirror is
that it can provide pre-built binaries for \R packages on a variety of
commonly-used Linux distributions. This behavior can be configured or
disabled if desired -- see the options in \code{\link[=config]{config()}} for more details.
}
\examples{
\dontrun{
# disable automatic snapshots
auto.snapshot <- getOption("renv.config.auto.snapshot")
options(renv.config.auto.snapshot = FALSE)
# initialize a new project (with an empty R library)
renv::init(bare = TRUE)
# install digest 0.6.19
renv::install("digest@0.6.19")
# save library state to lockfile
renv::snapshot()
# remove digest from library
renv::remove("digest")
# check library status
renv::status()
# restore lockfile, thereby reinstalling digest 0.6.19
renv::restore()
# restore automatic snapshots
options(renv.config.auto.snapshot = auto.snapshot)
}
}
renv/man/update.Rd 0000644 0001762 0000144 00000004564 14574356445 013602 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/update.R
\name{update}
\alias{update}
\title{Update packages}
\usage{
update(
packages = NULL,
...,
exclude = NULL,
library = NULL,
rebuild = FALSE,
check = FALSE,
prompt = interactive(),
lock = FALSE,
project = NULL
)
}
\arguments{
\item{packages}{A character vector of \R packages to update. When \code{NULL}
(the default), all packages (apart from any listed in the \code{ignored.packages}
project setting) will be updated.}
\item{...}{Unused arguments, reserved for future expansion. If any arguments
are matched to \code{...}, renv will signal an error.}
\item{exclude}{A set of packages to explicitly exclude from updating.
Use \verb{renv::update(exclude = <...>)} to update all packages except for
a specific set of excluded packages.}
\item{library}{The \R library to be used. When \code{NULL}, the active project
library will be used instead.}
\item{rebuild}{Force packages to be rebuilt, thereby bypassing any installed
versions of the package available in the cache? This can either be a
boolean (indicating that all installed packages should be rebuilt), or a
vector of package names indicating which packages should be rebuilt.}
\item{check}{Boolean; check for package updates without actually
installing available updates? This is useful when you'd like to determine
what updates are available, without actually installing those updates.}
\item{prompt}{Boolean; prompt the user before taking any action? For backwards
compatibility, \code{confirm} is accepted as an alias for \code{prompt}.}
\item{lock}{Boolean; update the \code{renv.lock} lockfile after the successful
installation of the requested packages?}
\item{project}{The project directory. If \code{NULL}, then the active project will
be used. If no project is currently active, then the current working
directory is used instead.}
}
\value{
A named list of package records which were installed by renv.
}
\description{
Update packages which are currently out-of-date. Currently supports CRAN,
Bioconductor, other CRAN-like repositories, GitHub, GitLab, Git, and
BitBucket.
Updates will only be checked from the same source -- for example,
if a package was installed from GitHub, but a newer version is
available on CRAN, that updated version will not be seen.
}
\examples{
\dontrun{
# update the 'dplyr' package
renv::update("dplyr")
}
}
renv/man/rehash.Rd 0000644 0001762 0000144 00000001742 14441721610 013544 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rehash.R
\name{rehash}
\alias{rehash}
\title{Re-hash packages in the renv cache}
\usage{
rehash(prompt = interactive(), ...)
}
\arguments{
\item{prompt}{Boolean; prompt the user before taking any action? For backwards
compatibility, \code{confirm} is accepted as an alias for \code{prompt}.}
\item{...}{Unused arguments, reserved for future expansion. If any arguments
are matched to \code{...}, renv will signal an error.}
}
\description{
Re-hash packages in the renv cache, ensuring that any previously-cached
packages are copied to a new cache location appropriate for this version of
renv. This can be useful if the cache scheme has changed in a new version
of renv, but you'd like to preserve your previously-cached packages.
}
\details{
Any packages which are re-hashed will retain links to the location of the
newly-hashed package, ensuring that prior installations of renv can still
function as expected.
}
renv/man/vendor.Rd 0000644 0001762 0000144 00000002347 14464550375 013606 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/vendor.R
\name{vendor}
\alias{vendor}
\title{Vendor renv in an R package}
\usage{
vendor(version = "main", project = getwd())
}
\arguments{
\item{version}{The version of renv to vendor. \code{renv} sources will be pulled
from GitHub, and so \code{version} should refer to either a commit hash or a
branch name.}
\item{project}{The project in which renv should be vendored.}
}
\description{
Calling \code{renv:::vendor()} will:
\itemize{
\item Compile a vendored copy of renv to \code{inst/vendor/renv.R},
\item Generate an renv auto-loader at \code{R/renv.R}.
}
Using this, projects can take a dependency on renv, and use renv
internals, in a CRAN-compliant way. After vendoring renv, you can
use renv APIs in your package via the embedded renv environment;
for example, you could call the \code{\link[=dependencies]{dependencies()}} function with:
\if{html}{\out{
}}
Be aware that renv internals might change in future releases, so if you
need to rely on renv internal functions, we strongly recommend testing
your usages of these functions to avoid potential breakage.
}
\keyword{internal}
renv/man/load.Rd 0000644 0001762 0000144 00000005013 14574517042 013215 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/load.R
\name{load}
\alias{load}
\title{Load a project}
\usage{
load(project = NULL, quiet = FALSE, profile = NULL, ...)
}
\arguments{
\item{project}{The project directory. If \code{NULL}, then the active project will
be used. If no project is currently active, then the current working
directory is used instead.}
\item{quiet}{Boolean; be quiet during load?}
\item{profile}{The profile to be activated. See
\code{vignette("profiles", package = "renv")} for more information.}
\item{...}{Unused arguments, reserved for future expansion. If any arguments
are matched to \code{...}, renv will signal an error.}
}
\value{
The project directory, invisibly. Note that this function is normally
called for its side effects.
}
\description{
\code{renv::load()} sets the library paths to use a project-local library,
sets up the system library \link{sandbox}, if needed, and creates shims
for \code{install.packages()}, \code{update.packages()}, and \code{remove.packages()}.
You should not generally need to call \code{renv::load()} yourself, as it's
called automatically by the project auto-loader created by \code{\link[=init]{init()}}/
\code{\link[=activate]{activate()}}. However, if needed, you can use \code{renv::load("")}
to explicitly load an renv project located at a particular path.
}
\section{Shims}{
To help you take advantage of the package cache, renv places a couple of
shims on the search path:
\itemize{
\item \code{install.packages()} instead calls \code{renv::install()}.
\item \code{remove.packages()} instead calls \code{renv::remove()}.
\item \code{update.packages()} instead calls \code{renv::update()}.
}
This allows you to keep using your existing muscle memory for installing,
updating, and remove packages, while taking advantage of renv features
like the package cache.
If you'd like to bypass these shims within an \R session, you can explicitly
call the version of these functions from the utils package, e.g. with
\verb{utils::install.packages(<...>)}.
If you'd prefer not to use the renv shims at all, they can be disabled by
setting the R option \code{options(renv.config.shims.enabled = FALSE)} or by
setting the environment variable \code{RENV_CONFIG_SHIMS_ENABLED = FALSE}. See
\code{?config} for more details.
}
\examples{
\dontrun{
# load a project -- note that this is normally done automatically
# by the project's auto-loader, but calling this explicitly to
# load a particular project may be useful in some circumstances
renv::load()
}
}
renv/man/hydrate.Rd 0000644 0001762 0000144 00000005642 14547051446 013747 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hydrate.R
\name{hydrate}
\alias{hydrate}
\title{Copy packages from user libraries to a project library}
\usage{
hydrate(
packages = NULL,
...,
library = NULL,
repos = getOption("repos"),
update = FALSE,
sources = NULL,
prompt = interactive(),
report = TRUE,
project = NULL
)
}
\arguments{
\item{packages}{The set of \R packages to install. When \code{NULL}, the
packages found by \code{\link[=dependencies]{dependencies()}} are used.}
\item{...}{Unused arguments, reserved for future expansion. If any arguments
are matched to \code{...}, renv will signal an error.}
\item{library}{The \R library to be hydrated. When \code{NULL}, the active
library as reported by \code{.libPaths()} is used.}
\item{repos}{The \R repositories to be used. If the project depends on any
\R packages which cannot be found within the user library paths, then
those packages will be installed from these repositories instead.}
\item{update}{Boolean; should \code{hydrate()} attempt to update already-installed
packages if the requested package is already installed in the project
library? Set this to \code{"all"} if you'd like \emph{all} packages to be refreshed
from the source library if possible.}
\item{sources}{A vector of library paths where renv should look for packages.
When \code{NULL} (the default), \code{hydrate()} will look in the system libraries
(the user library, the site library and the default library) then the
renv cache.
If a package is not found in any of these locations, \code{hydrate()}
will try to install it from the active R repositories.}
\item{prompt}{Boolean; prompt the user before taking any action? Ignored
when \code{report = FALSE}.}
\item{report}{Boolean; display a report of what packages will be installed
by \code{renv::hydrate()}?}
\item{project}{The project directory. If \code{NULL}, then the active project will
be used. If no project is currently active, then the current working
directory is used instead.}
}
\value{
A named \R list, giving the packages that were used for hydration
as well as the set of packages which were not found.
}
\description{
\code{hydrate()} installs missing packages from a user library into the project
library. \code{hydrate()} is called automatically by \code{\link[=init]{init()}}, and it is rare
that you should need it otherwise, as it can easily get your project into
an inconsistent state.
It may very occasionally be useful to call \code{hydrate(update = "all")} if you
want to update project packages to match those installed in your global
library (as opposed to using \code{\link[=update]{update()}} which will get the latest versions
from CRAN). In this case, you should verify that your code continues to work,
then call \code{\link[=snapshot]{snapshot()}} to record updated package versions in the lockfile.
}
\examples{
\dontrun{
# hydrate the active library
renv::hydrate()
}
}
\keyword{internal}
renv/man/graph.Rd 0000644 0001762 0000144 00000003443 14502607107 013375 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/graph.R
\name{graph}
\alias{graph}
\title{Generate a Package Dependency Graph}
\usage{
graph(
root = NULL,
leaf = NULL,
...,
suggests = FALSE,
enhances = FALSE,
resolver = NULL,
renderer = c("DiagrammeR", "visNetwork"),
attributes = list(),
project = NULL
)
}
\arguments{
\item{root}{The top-most package dependencies of interest in the dependency graph.}
\item{leaf}{The bottom-most package dependencies of interest in the dependency graph.}
\item{...}{Unused arguments, reserved for future expansion. If any arguments
are matched to \code{...}, renv will signal an error.}
\item{suggests}{Should suggested packages be included within
the dependency graph?}
\item{enhances}{Should enhanced packages be included within
the dependency graph?}
\item{resolver}{An \R function accepting a package name, and returning the
contents of its \code{DESCRIPTION} file (as an \R \code{data.frame} or \code{list}).
When \code{NULL} (the default), an internal resolver is used.}
\item{renderer}{Which package should be used to render the resulting graph?}
\item{attributes}{An \R list of graphViz attributes, mapping node names to
attribute key-value pairs. For example, to ask graphViz to prefer orienting
the graph from left to right, you can use \code{list(graph = c(rankdir = "LR"))}.}
\item{project}{The project directory. If \code{NULL}, then the active project will
be used. If no project is currently active, then the current working
directory is used instead.}
}
\description{
Generate a package dependency graph.
}
\examples{
\dontrun{
# graph the relationship between devtools and rlang
graph(root = "devtools", leaf = "rlang")
# figure out why a project depends on 'askpass'
graph(leaf = "askpass")
}
}
\keyword{internal}
renv/man/config.Rd 0000644 0001762 0000144 00000041507 14547051446 013554 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/config-defaults.R, R/config.R
\docType{data}
\name{config}
\alias{config}
\title{User-level settings}
\usage{
config
}
\description{
Configure different behaviors of renv.
}
\details{
For a given configuration option:
\enumerate{
\item If an \R option of the form \verb{renv.config.} is available,
then that option's value will be used;
\item If an environment variable of the form \verb{RENV_CONFIG_} is available,
then that option's value will be used;
\item Otherwise, the default for that particular configuration value is used.
}
Any periods (\code{.})s in the option name are transformed into underscores (\verb{_})
in the environment variable name, and vice versa. For example, the
configuration option \code{auto.snapshot} could be configured as:
\itemize{
\item \verb{options(renv.config.auto.snapshot = <...>)}
\item \verb{Sys.setenv(RENV_CONFIG_AUTO_SNAPSHOT = <...>)}
}
Note that if both the \R option and the environment variable are defined, the
\R option will be used instead. Environment variables can be more useful when
you want a particular configuration to be automatically inherited by child
processes; if that behavior is not desired, then the R option may be
preferred.
If you want to set and persist these options across multiple projects, it is
recommended that you set them in a a startup \code{.Renviron} file; e.g. in your
own \verb{~/.Renviron}, or in the R installation's \code{etc/Rprofile.site} file. See
\link{Startup} for more details.
Configuration options can also be set within the project \code{.Rprofile}, but
be aware the options should be set before \code{source("renv/activate.R")} is
called.
}
\section{Configuration}{
The following renv configuration options are available:
\subsection{renv.config.activate.prompt}{Automatically prompt the user to activate the current project, if it does not appear to already be activated? This is mainly useful to help ensure that calls to \code{renv::snapshot()} and \code{renv::restore()} use the project library. See \code{?renv::activate} for more details.
Defaults to \code{TRUE}.}
\subsection{renv.config.autoloader.enabled}{Enable the renv auto-loader? When \code{FALSE}, renv will not automatically load a project containing an renv autoloader within its \code{.Rprofile}. In addition, renv will not write out the project auto-loader in calls to \code{renv::init()}.
Defaults to \code{TRUE}.}
\subsection{renv.config.auto.snapshot}{Automatically snapshot changes to the project library when the project dependencies change?
Defaults to \code{FALSE}.}
\subsection{renv.config.bitbucket.host}{The default Bitbucket host to be used during package retrieval.
Defaults to \code{"api.bitbucket.org/2.0"}.}
\subsection{renv.config.copy.method}{The method to use when attempting to copy directories. See \strong{Copy Methods} for more information.
Defaults to \code{"auto"}.}
\subsection{renv.config.connect.timeout}{The amount of time to spend (in seconds) when attempting to download a file. Only applicable when the \code{curl} downloader is used.
Defaults to \code{20L}.}
\subsection{renv.config.connect.retry}{The number of times to attempt re-downloading a file, when transient download errors occur. Only applicable when the \code{curl} downloader is used.
Defaults to \code{3L}.}
\subsection{renv.config.cache.enabled}{Enable the global renv package cache? When active, renv will install packages into a global cache, and link or copy packages from the cache into your \R library as appropriate. This can greatly save on disk space and install time when \R packages are shared across multiple projects in the same environment.
Defaults to \code{TRUE}.}
\subsection{renv.config.cache.symlinks}{Symlink packages from the global renv package cache into your project library? When \code{TRUE}, renv will use symlinks (or, on Windows, junction points) to reference packages installed in the cache. Set this to \code{FALSE} if you'd prefer to copy packages from the cache into your project library. Enabled by default, except on Windows where this feature is only enabled if the project library and global package cache are on the same volume.
Defaults to \code{NULL}.}
\subsection{renv.config.dependency.errors}{Many renv APIs require the enumeration of your project's \R package dependencies. This option controls how errors that occur during this enumeration are handled. By default, errors are reported but are non-fatal. Set this to \code{"fatal"} to force errors to be fatal, and \code{"ignored"} to ignore errors altogether. See \code{\link[=dependencies]{dependencies()}} for more details.
Defaults to \code{"reported"}.}
\subsection{renv.config.dependencies.limit}{By default, renv reports if it discovers more than this many files when looking for dependencies, as that may indicate you are running \code{dependencies()} in the wrong place. Set to \code{Inf} to disable this warning.
Defaults to \code{1000L}.}
\subsection{renv.config.exported.functions}{When \code{library(renv)} is called, should its exports be placed on the search path? Set this to \code{FALSE} to avoid issues that can arise with, for example, \code{renv::load()} masking \code{base::load()}. In general, we recommend referencing renv functions from its namespace explicitly; e.g. prefer \code{renv::snapshot()} over \code{snapshot()}.
By default, all exported renv functions are attached and placed on the search path, for backwards compatibility with existing scripts using renv.
Defaults to \code{"*"}.}
\subsection{renv.config.external.libraries}{A character vector of external libraries, to be used in tandem with your projects. Be careful when using external libraries: it's possible that things can break within a project if the version(s) of packages used in your project library happen to be incompatible with packages in your external libraries; for example, if your project required \verb{xyz 1.0} but \verb{xyz 1.1} was present and loaded from an external library. Can also be an \R function that provides the paths to external libraries. Library paths will be expanded via \code{\link[=.expand_R_libs_env_var]{.expand_R_libs_env_var()}} as necessary.
Defaults to \code{NULL}.}
\subsection{renv.config.filebacked.cache}{Enable the renv file-backed cache? When enabled, renv will cache the contents of files that are read (e.g. DESCRIPTION files) in memory, thereby avoiding re-reading the file contents from the filesystem if the file has not changed. renv uses the file \code{mtime} to determine if the file has changed; consider disabling this if \code{mtime} is unreliable on your system.
Defaults to \code{TRUE}.}
\subsection{renv.config.github.host}{The default GitHub host to be used during package retrieval.
Defaults to \code{"api.github.com"}.}
\subsection{renv.config.gitlab.host}{The default GitLab host to be used during package retrieval.
Defaults to \code{"gitlab.com"}.}
\subsection{renv.config.hydrate.libpaths}{A character vector of library paths, to be used by \code{\link[=hydrate]{hydrate()}} when attempting to hydrate projects. When empty, the default set of library paths (as documented in \code{?renv::hydrate}) are used instead. See \code{\link[=hydrate]{hydrate()}} for more details.
Defaults to \code{NULL}.}
\subsection{renv.config.install.build}{Should downloaded package archives be built (via \verb{R CMD build}) before installation? When TRUE, package vignettes will also be built as part of package installation. Because building packages before installation may require packages within 'Suggests' to be available, this option is not enabled by default.
Defaults to \code{FALSE}.}
\subsection{renv.config.install.remotes}{Should renv read a package's \verb{Remotes:} field when determining how package dependencies should be installed?
Defaults to \code{TRUE}.}
\subsection{renv.config.install.shortcuts}{Allow for a set of 'shortcuts' when installing packages with renv? When enabled, if renv discovers that a package to be installed is already available within the user or site libraries, then it will install a local copy of that package.
Defaults to \code{TRUE}.}
\subsection{renv.config.install.staged}{DEPRECATED: Please use \code{renv.config.install.transactional} instead.
Defaults to \code{TRUE}.}
\subsection{renv.config.install.transactional}{Perform a transactional install of packages during install and restore? When enabled, renv will first install packages into a temporary library, and later copy or move those packages back into the project library only if all packages were successfully downloaded and installed. This can be useful if you'd like to avoid mutating your project library if installation of one or more packages fails.
Defaults to \code{TRUE}.}
\subsection{renv.config.install.verbose}{Be verbose when installing R packages from sources? When \code{TRUE}, renv will stream any output generated during package build + installation to the console.
Defaults to \code{FALSE}.}
\subsection{renv.config.locking.enabled}{Use interprocess locks when invoking methods which might mutate the project library? Enable this to allow multiple processes to use the same renv project, while minimizing risks relating to concurrent access to the project library. Disable this if you encounter locking issues. Locks are stored as files within the project at \code{renv/lock}; if you need to manually remove a stale lock you can do so via \code{unlink("renv/lock", recursive = TRUE)}.
Defaults to \code{FALSE}.}
\subsection{renv.config.mran.enabled}{DEPRECATED: MRAN is no longer maintained by Microsoft.
Defaults to \code{FALSE}.}
\subsection{renv.config.pak.enabled}{Use the \href{https://pak.r-lib.org/}{pak} package to install packages?
Defaults to \code{FALSE}.}
\subsection{renv.config.ppm.enabled}{Boolean; enable \href{https://packagemanager.posit.co/}{Posit Package Manager} integration in renv projects? When \code{TRUE}, renv will attempt to transform repository URLs used by PPM into binary URLs as appropriate for the current Linux platform. Set this to \code{FALSE} if you'd like to continue using source-only PPM URLs, or if you find that renv is improperly transforming your repository URLs. You can still set and use PPM repositories with this option disabled; it only controls whether renv tries to transform source repository URLs into binary URLs on your behalf.
Defaults to \code{TRUE}.}
\subsection{renv.config.ppm.default}{Boolean; should new projects use the \href{https://packagemanager.posit.co/}{Posit Public Package Manager} instance by default? When \code{TRUE} (the default), projects initialized with \code{renv::init()} will use the P3M instance if the \code{repos} R option has not already been set by some other means (for example, in a startup \code{.Rprofile}).
Defaults to \code{TRUE}.}
\subsection{renv.config.ppm.url}{The default PPM URL to be used for new renv projects. Defaults to the CRAN mirror maintained by Posit at \url{https://packagemanager.posit.co/}. This option can be changed if you'd like renv to use an alternate package manager instance.
Defaults to \code{"https://packagemanager.posit.co/cran/latest"}.}
\subsection{renv.config.repos.override}{Override the R package repositories used during \code{\link[=restore]{restore()}}? Primarily useful for deployment / continuous integration, where you might want to enforce the usage of some set of repositories over what is defined in \code{renv.lock} or otherwise set by the R session.
Defaults to \code{NULL}.}
\subsection{renv.config.rspm.enabled}{DEPRECATED: Please use \code{renv.config.ppm.enabled} instead.
Defaults to \code{TRUE}.}
\subsection{renv.config.sandbox.enabled}{Enable sandboxing for renv projects? When active, renv will attempt to sandbox the system library, preventing non-system packages installed in the system library from becoming available in renv projects. (That is, only packages with priority \code{"base"} or \code{"recommended"}, as reported by \code{installed.packages()}, are made available.)
Sandboxing is done by linking or copying system packages into a separate library path, and then instructing R to use that library path as the system library path. In some environments, this action can take a large amount of time -- in such a case, you may want to disable the renv sandbox.
Defaults to \code{TRUE}.}
\subsection{renv.config.shims.enabled}{Should renv shims be installed on package load? When enabled, renv will install its own shims over the functions \code{install.packages()}, \code{update.packages()} and \code{remove.packages()}, delegating these functions to \code{\link[=install]{install()}}, \code{\link[=update]{update()}} and \code{\link[=remove]{remove()}} as appropriate.
Defaults to \code{TRUE}.}
\subsection{renv.config.snapshot.inference}{For packages which were installed from local sources, should renv try to infer the package's remote from its DESCRIPTION file? When \code{TRUE}, renv will check and prompt you to update the package's DESCRIPTION file if the remote source can be ascertained. Currently, this is only implemented for packages hosted on GitHub. Note that this check is only performed in interactive R sessions.
Defaults to \code{TRUE}.}
\subsection{renv.config.snapshot.validate}{Validate \R package dependencies when calling snapshot? When \code{TRUE}, renv will attempt to diagnose potential issues in the project library before creating \code{renv.lock} -- for example, if a package installed in the project library depends on a package which is not currently installed.
Defaults to \code{TRUE}.}
\subsection{renv.config.startup.quiet}{Be quiet during startup? When set, renv will not display the typical \verb{Project loaded. [renv ]} banner on startup.
Defaults to \code{NULL}.}
\subsection{renv.config.synchronized.check}{Check that the project library is synchronized with the lockfile on load?
Defaults to \code{TRUE}.}
\subsection{renv.config.updates.check}{Check for package updates when the session is initialized? This can be useful if you'd like to ensure that your project lockfile remains up-to-date with packages as they are released on CRAN.
Defaults to \code{FALSE}.}
\subsection{renv.config.updates.parallel}{Check for package updates in parallel? This can be useful when a large number of packages installed from non-CRAN remotes are installed, as these packages can then be checked for updates in parallel.
Defaults to \code{2L}.}
\subsection{renv.config.user.environ}{Load the user R environ (typically located at \verb{~/.Renviron}) when renv is loaded?
Defaults to \code{TRUE}.}
\subsection{renv.config.user.library}{Include the system library on the library paths for your projects? Note that this risks breaking project encapsulation and is not recommended for projects which you intend to share or collaborate on with other users. See also the caveats for the \code{renv.config.external.libraries} option.
Defaults to \code{FALSE}.}
\subsection{renv.config.user.profile}{Load the user R profile (typically located at \verb{~/.Rprofile}) when renv is loaded? This is disabled by default, as running arbitrary code from the the user \verb{~/.Rprofile} could risk breaking project encapsulation. If your goal is to set environment variables that are visible within all renv projects, then placing those in \verb{~/.Renviron} is often a better choice. Defaults to \code{FALSE}.}
}
\section{Copy methods}{
If you find that renv is unable to copy some directories in your
environment, you may want to try setting the \code{copy.method} option. By
default, renv will try to choose a system tool that is likely to succeed in
copying files on your system -- \code{robocopy} on Windows, and \code{cp} on Unix.
renv will also instruct these tools to preserve timestamps and attributes
when copying files. However, you can select a different method as
appropriate.
The following methods are supported:
\tabular{ll}{
\code{auto} \tab Use \code{robocopy} on Windows, and \code{cp} on Unix-alikes. \cr
\code{R} \tab Use \R's built-in \code{file.copy()} function. \cr
\code{cp} \tab Use \code{cp} to copy files. \cr
\code{robocopy} \tab Use \code{robocopy} to copy files. (Only available on Windows.) \cr
\code{rsync} \tab Use \code{rsync} to copy files. \cr
}
You can also provide a custom copy method if required; e.g.
\if{html}{\out{
}}\preformatted{options(renv.config.copy.method = function(src, dst) \{
# copy a file from 'src' to 'dst'
\})
}\if{html}{\out{
}}
Note that renv will always first attempt to copy a directory first to a
temporary path within the target folder, and then rename that temporary path
to the final target destination. This helps avoid issues where a failed
attempt to copy a directory could leave a half-copied directory behind
in the final location.
}
\section{Project-local settings}{
For settings that should persist alongside a particular project, the
various settings available in \link{settings} can be used.
}
\examples{
# disable automatic snapshots
options(renv.config.auto.snapshot = FALSE)
# disable with environment variable
Sys.setenv(RENV_CONFIG_AUTO_SNAPSHOT = FALSE)
}
\keyword{datasets}
renv/man/history.Rd 0000644 0001762 0000144 00000002370 14441721610 013771 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/history.R
\name{history}
\alias{history}
\alias{revert}
\title{View and revert to a historical lockfile}
\usage{
history(project = NULL)
revert(commit = "HEAD", ..., project = NULL)
}
\arguments{
\item{project}{The project directory. If \code{NULL}, then the active project will
be used. If no project is currently active, then the current working
directory is used instead.}
\item{commit}{The commit associated with a prior version of the lockfile.}
\item{...}{Optional arguments; currently unused.}
}
\value{
\code{history()} returns a \code{data.frame} summarizing the commits in which
\code{renv.lock} has been changed. \code{revert()} is usually called for its
side-effect but also invisibly returns the \code{commit} used.
}
\description{
\code{history()} uses your version control system to show prior versions of the
lockfile and \code{revert()} allows you to restore one of them.
These functions are currently only implemented for projects that use git.
}
\examples{
\dontrun{
# get history of previous versions of renv.lock in VCS
db <- renv::history()
# choose an older commit
commit <- db$commit[5]
# revert to that version of the lockfile
renv::revert(commit = commit)
}
}
renv/man/lockfiles.Rd 0000644 0001762 0000144 00000013656 14475733536 014275 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lockfiles.R
\name{lockfiles}
\alias{lockfiles}
\alias{lockfile_create}
\alias{lockfile_read}
\alias{lockfile_write}
\alias{lockfile_modify}
\title{Lockfiles}
\usage{
lockfile_create(
type = settings$snapshot.type(project = project),
libpaths = .libPaths(),
packages = NULL,
exclude = NULL,
prompt = interactive(),
force = FALSE,
...,
project = NULL
)
lockfile_read(file = NULL, ..., project = NULL)
lockfile_write(lockfile, file = NULL, ..., project = NULL)
lockfile_modify(
lockfile = NULL,
...,
remotes = NULL,
repos = NULL,
project = NULL
)
}
\arguments{
\item{type}{The type of snapshot to perform:
\itemize{
\item \code{"implict"}, (the default), uses all packages captured by \code{\link[=dependencies]{dependencies()}}.
\item \code{"explicit"} uses packages recorded in \code{DESCRIPTION}.
\item \code{"all"} uses all packages in the project library.
\item \code{"custom"} uses a custom filter.
}
See \strong{Snapshot type} below for more details.}
\item{libpaths}{The library paths to be used when generating the lockfile.}
\item{packages}{A vector of packages to be included in the lockfile. When
\code{NULL} (the default), all packages relevant for the type of snapshot being
performed will be included. When set, the \code{type} argument is ignored.
Recursive dependencies of the specified packages will be added to the
lockfile as well.}
\item{exclude}{A vector of packages to be explicitly excluded from the lockfile.
Note that transitive package dependencies will always be included, to avoid
potentially creating an incomplete / non-functional lockfile.}
\item{prompt}{Boolean; prompt the user before taking any action? For backwards
compatibility, \code{confirm} is accepted as an alias for \code{prompt}.}
\item{force}{Boolean; force generation of a lockfile even when pre-flight
validation checks have failed?}
\item{...}{Unused arguments, reserved for future expansion. If any arguments
are matched to \code{...}, renv will signal an error.}
\item{project}{The project directory. If \code{NULL}, then the active project will
be used. If no project is currently active, then the current working
directory is used instead.}
\item{file}{A file path, or \R connection.}
\item{lockfile}{An \code{renv} lockfile; typically created by either
\code{lockfile_create()} or \code{lockfile_read()}.}
\item{remotes}{An \R vector of remote specifications.}
\item{repos}{A named vector, mapping \R repository names to their URLs.}
}
\description{
A \strong{lockfile} records the state of a project at some point in time.
}
\details{
A lockfile captures the state of a project's library at some point in time.
In particular, the package names, their versions, and their sources (when
known) are recorded in the lockfile.
Projects can be restored from a lockfile using the \code{\link[=restore]{restore()}} function. This
implies reinstalling packages into the project's private library, as encoded
within the lockfile.
While lockfiles are normally generated and used with \code{\link[=snapshot]{snapshot()}} /
\code{\link[=restore]{restore()}}, they can also be edited by hand if so desired. Lockfiles are
written as \code{.json}, to allow for easy consumption by other tools.
An example lockfile follows:
\if{html}{\out{
}}
The sections used within a lockfile are described next.
\subsection{renv}{
Information about the version of renv used to manage this project.
\tabular{ll}{
\strong{Version} \tab The version of the renv package used with this project. \cr
}
}
\subsection{R}{
Properties related to the version of \R associated with this project.
\tabular{ll}{
\strong{Version} \tab The version of \R used. \cr
\strong{Repositories} \tab The \R repositories used in this project. \cr
}
}
\subsection{Packages}{
\R package records, capturing the packages used or required by a project
at the time when the lockfile was generated.
\tabular{ll}{
\strong{Package} \tab The package name. \cr
\strong{Version} \tab The package version. \cr
\strong{Source} \tab The location from which this package was retrieved. \cr
\strong{Repository} \tab The name of the repository (if any) from which this package was retrieved. \cr
\strong{Hash} \tab (Optional) A unique hash for this package, used for package caching. \cr
}
Additional remote fields, further describing how the package can be
retrieved from its corresponding source, will also be included as
appropriate (e.g. for packages installed from GitHub).
}
\subsection{Python}{
Metadata related to the version of Python used with this project (if any).
\tabular{ll}{
\strong{Version} \tab The version of Python being used. \cr
\strong{Type} \tab The type of Python environment being used ("virtualenv", "conda", "system") \cr
\strong{Name} \tab The (optional) name of the environment being used.
}
Note that the \code{Name} field may be empty. In that case, a project-local Python
environment will be used instead (when not directly using a system copy of Python).
}
}
\section{Caveats}{
These functions are primarily intended for expert users -- in most cases,
\code{\link[=snapshot]{snapshot()}} and \code{\link[=restore]{restore()}} are the primariy tools you will need when
creating and using lockfiles.
}
\seealso{
Other reproducibility:
\code{\link{restore}()},
\code{\link{snapshot}()}
}
\concept{reproducibility}
renv/man/isolate.Rd 0000644 0001762 0000144 00000002636 14441721610 013735 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/isolate.R
\name{isolate}
\alias{isolate}
\title{Isolate a project}
\usage{
isolate(project = NULL)
}
\arguments{
\item{project}{The project directory. If \code{NULL}, then the active project will
be used. If no project is currently active, then the current working
directory is used instead.}
}
\value{
The project directory, invisibly. Note that this function is normally
called for its side effects.
}
\description{
Copy packages from the renv cache directly into the project library, so
that the project can continue to function independently of the renv cache.
}
\details{
After calling \code{isolate()}, renv will still be able to use the cache on
future \code{\link[=install]{install()}}s and \code{\link[=restore]{restore()}}s. If you'd prefer that renv copy
packages from the cache, rather than use symlinks, you can set the renv
configuration option:
\if{html}{\out{
}}
to force renv to copy packages from the cache, as opposed to symlinking
them. If you'd like to disable the cache altogether for a project, you can
use:
\if{html}{\out{
}}
to explicitly disable the cache for the project.
}
\examples{
\dontrun{
# isolate a project
renv::isolate()
}
}
renv/man/record.Rd 0000644 0001762 0000144 00000003343 14464550375 013564 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/record.R
\name{record}
\alias{record}
\title{Update package records in a lockfile}
\usage{
record(records, lockfile = NULL, project = NULL)
}
\arguments{
\item{records}{A list of named records, mapping package names to a definition
of their source. See \strong{Records} for more details.}
\item{lockfile}{Path to a lockfile. When \code{NULL} (the default), the
\code{renv.lock} located in the root of the current project will be used.}
\item{project}{The project directory. If \code{NULL}, then the active project will
be used. If no project is currently active, then the current working
directory is used instead.}
}
\description{
Use \code{record()} to record a new entry within an existing renv lockfile.
}
\details{
This function can be useful when you need to change one or more of the
package records within an renv lockfile -- for example, because a recorded
package cannot be restored in a particular environment, and you know of a
suitable alternative.
}
\section{Records}{
Records can be provided either using the \strong{remotes} short-hand syntax,
or by using an \R list of entries to record within the lockfile. See
\code{?lockfiles} for more information on the structure of a package record.
}
\examples{
\dontrun{
# use digest 0.6.22 from package repositories -- different ways
# of specifying the remote. use whichever is most natural
renv::record("digest@0.6.22")
renv::record(list(digest = "0.6.22"))
renv::record(list(digest = "digest@0.6.22"))
# alternatively, provide a full record as a list
digest_record <- list(
Package = "digest",
Version = "0.6.22",
Source = "Repository",
Repository = "CRAN"
)
renv::record(list(digest = digest_record))
}
}
renv/man/dependencies.Rd 0000644 0001762 0000144 00000017132 14464550375 014735 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dependencies.R
\name{dependencies}
\alias{dependencies}
\title{Find R package dependencies in a project}
\usage{
dependencies(
path = getwd(),
root = NULL,
...,
quiet = NULL,
progress = TRUE,
errors = c("reported", "fatal", "ignored"),
dev = FALSE
)
}
\arguments{
\item{path}{The path to a \code{.R}, \code{.Rmd}, \code{.qmd}, \code{DESCRIPTION}, a directory
containing such files, or an R function. The default uses all files
found within the current working directory and its children.}
\item{root}{The root directory to be used for dependency discovery.
Defaults to the active project directory. You may need to set this
explicitly to ensure that your project's \code{.renvignore}s (if any) are
properly handled.}
\item{...}{Unused arguments, reserved for future expansion. If any arguments
are matched to \code{...}, renv will signal an error.}
\item{quiet}{Boolean; be quiet while checking for dependencies?
Setting \code{quiet = TRUE} is equivalent to setting \code{progress = FALSE}
and \code{errors = "ignored"}, and overrides those options when not \code{NULL}.}
\item{progress}{Boolean; report progress output while enumerating
dependencies?}
\item{errors}{How should errors that occur during dependency enumeration be
handled?
\itemize{
\item \code{"reported"} (the default): errors are reported to the user, but
otherwise ignored.
\item \code{"fatal"}: errors are fatal and stop execution.
\item \code{"ignored"}: errors are ignored and not reported to the user.
}}
\item{dev}{Boolean; include development dependencies? These packages are
typically required when developing the project, but not when running it
(i.e. you want them installed when humans are working on the project but
not when computers are deploying it).
Development dependencies include packages listed in the \code{Suggests} field
of a \code{DESCRIPTION} found in the project root, and roxygen2 or devtools if
their use is implied by other project metadata. They also include packages
used in \verb{~/.Rprofile} if \code{config$user.profile()} is \code{TRUE}.}
}
\value{
An \R \code{data.frame} of discovered dependencies, mapping inferred
package names to the files in which they were discovered. Note that the
\code{Package} field might name a package remote, rather than just a plain
package name.
}
\description{
\code{dependencies()} will crawl files within your project, looking for \R files
and the packages used within those \R files. This is done primarily by
parsing the code and looking for calls of the form \code{library(package)},
\code{require(package)}, \code{requireNamespace("package")}, and \code{package::method()}.
renv also supports package loading with
\href{https://cran.r-project.org/package=box}{box} (\code{box::use(...)}) and
\href{https://cran.r-project.org/package=pacman}{pacman} (\code{pacman::p_load(...)})
.
For \R package projects, dependencies expressed in the \code{DESCRIPTION} file
will also be discovered.
Note that the rmarkdown package is required in order to crawl dependencies
in R Markdown files.
}
\section{Missing dependencies}{
\code{dependencies()} uses static analysis to determine which packages are used
by your project. This means that it inspects, but doesn't run, your
source. Static analysis generally works well, but is not 100\% reliable in
detecting the packages required by your project. For example, renv is
unable to detect this kind of usage:
\if{html}{\out{
}}
It also can't generally tell if one of the packages you use, uses one of
its suggested packages. For example, \code{tidyr::separate_wider_delim()}
uses the stringr package which is only suggested, not required by tidyr.
If you find that renv's dependency discovery misses one or more packages
that you actually use in your project, one escape hatch is to include a file
called \verb{_dependencies.R} that includes straightforward library calls:
\if{html}{\out{
}}
}
\section{Explicit dependencies}{
Alternatively, you can suppress dependency discover and instead rely
on an explicit set of packages recorded by you in a project \code{DESCRIPTION} file.
Call \code{renv::settings$snapshot.type("explicit")} to enable "explicit" mode,
then enumerate your dependencies in a project \code{DESCRIPTION} file.
In that case, your \code{DESCRIPTION} might look something like this:
\if{html}{\out{
}}
}
\section{Ignoring files}{
By default, renv will read your project's \code{.gitignore}s (if present) to
determine whether certain files or folders should be included when traversing
directories. If preferred, you can also create a \code{.renvignore} file (with
entries of the same format as a standard \code{.gitignore} file) to tell renv
which files to ignore within a directory. If both \code{.renvignore} and
\code{.gitignore} exist within a folder, the \code{.renvignore} will be used in lieu of
the \code{.gitignore}.
See \url{https://git-scm.com/docs/gitignore} for documentation on the
\code{.gitignore} format. Some simple examples here:
\if{html}{\out{
}}\preformatted{# ignore all R Markdown files
*.Rmd
# ignore all data folders
data/
# ignore only data folders from the root of the project
/data/
}\if{html}{\out{
}}
Using ignore files is important if your project contains a large number
of files; for example, if you have a \verb{data/} directory containing many
text files.
}
\section{Errors}{
renv's attempts to enumerate package dependencies in your project can fail
-- most commonly, because of failures when attempting to parse your \R code.
You can use the \code{errors} argument to suppress these problems, but a
more robust solution is tell renv not to look at the problematic code.
As well as using \code{.renvignore}, as described above, you can also suppress errors
discovered within individual \code{.Rmd} chunks by including \code{renv.ignore=TRUE}
in the chunk header. For example:
\if{html}{\out{
}}\preformatted{```\{r chunk-label, renv.ignore=TRUE\}
# code in this chunk will be ignored by renv
```
}\if{html}{\out{
}}
Similarly, if you'd like renv to parse a chunk that is otherwise ignored
(e.g. because it has \code{eval=FALSE} as a chunk header), you can set:
\if{html}{\out{
}}\preformatted{```\{r chunk-label, eval=FALSE, renv.ignore=FALSE\}
# code in this chunk will _not_ be ignored
```
}\if{html}{\out{
}}
}
\section{Development dependencies}{
renv has some support for distinguishing between development and run-time
dependencies. For example, your Shiny app might rely on
\href{https://ggplot2.tidyverse.org}{ggplot2} (a run-time dependency) but while
you use \href{https://usethis.r-lib.org}{usethis} during development, your app
doesn't need it to run (i.e. it's only a development dependency).
You can record development dependencies by listing them in the \code{Suggests}
field of your project's \code{DESCRIPTION} file. Development dependencies will be installed by
\code{\link[=install]{install()}} (when called without arguments) but will not be tracked in
the project snapshot. If you need greater control, you can also try project
profiles as discussed in \code{vignette("profiles")}.
}
\examples{
\dontrun{
# find R package dependencies in the current directory
renv::dependencies()
}
}
renv/man/settings.Rd 0000644 0001762 0000144 00000013126 14573145613 014142 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/settings.R
\docType{data}
\name{settings}
\alias{settings}
\title{Project settings}
\usage{
settings
}
\value{
A named list of renv settings.
}
\description{
Define project-local settings that can be used to adjust the behavior of
renv with your particular project.
\itemize{
\item Get the current value of a setting with (e.g.) \code{settings$snapshot.type()}
\item Set current value of a setting with (e.g.)
\code{settings$snapshot.type("explicit")}.
}
Settings are automatically persisted across project sessions by writing to
\code{renv/settings.json}. You can also edit this file by hand, but you'll need
to restart the session for those changes to take effect.
\subsection{\code{bioconductor.version}}{
The Bioconductor version to be used with this project. Use this if you'd
like to lock the version of Bioconductor used on a per-project basis.
When unset, renv will try to infer the appropriate Bioconductor release
using the BiocVersion package if installed; if not, renv uses
\code{BiocManager::version()} to infer the appropriate Bioconductor version.
}
\subsection{\code{external.libraries}}{
A vector of library paths, to be used in addition to the project's own
private library. This can be useful if you have a package available for use
in some system library, but for some reason renv is not able to install
that package (e.g. sources or binaries for that package are not publicly
available, or you have been unable to orchestrate the pre-requisites for
installing some packages from source on your machine).
}
\subsection{\code{ignored.packages}}{
A vector of packages, which should be ignored when attempting to snapshot
the project's private library. Note that if a package has already been
added to the lockfile, that entry in the lockfile will not be ignored.
}
\subsection{\code{package.dependency.fields}}{
When explicitly installing a package with \code{install()}, what fields
should be used to determine that packages dependencies? The default
uses \code{Imports}, \code{Depends} and \code{LinkingTo} fields, but you also want
to install \code{Suggests} dependencies for a package, you can set this to
\code{c("Imports", "Depends", "LinkingTo", "Suggests")}.
}
\subsection{\code{ppm.enabled}}{
Enable \href{https://packagemanager.posit.co/}{Posit Package Manager}
integration in this project? When \code{TRUE}, renv will attempt to transform
repository URLs used by PPM into binary URLs as appropriate for the
current Linux platform. Set this to \code{FALSE} if you'd like to continue using
source-only PPM URLs, or if you find that renv is improperly transforming
your repository URLs. You can still set and use PPM repositories with this
option disabled; it only controls whether renv tries to transform source
repository URLs into binary URLs on your behalf.
}
\subsection{\code{ppm.ignored.urls}}{
When \href{https://packagemanager.posit.co/}{Posit Package Manager} integration
is enabled, \code{renv} will attempt to transform source repository URLs into
binary repository URLs. This setting can be used if you'd like to avoid this
transformation with some subset of repository URLs.
}
\subsection{\code{r.version}}{
The version of \R to encode within the lockfile. This can be set as a
project-specific option if you'd like to allow multiple users to use
the same renv project with different versions of \R. renv will
still warn the user if the major + minor version of \R used in a project
does not match what is encoded in the lockfile.
}
\subsection{\code{snapshot.type}}{
The type of snapshot to perform by default. See \link{snapshot} for more
details.
}
\subsection{\code{use.cache}}{
Enable the renv package cache with this project. When active, renv will
install packages into a global cache, and link packages from the cache into
your renv projects as appropriate. This can greatly save on disk space
and install time when for \R packages which are used across multiple
projects in the same environment.
}
\subsection{\code{vcs.manage.ignores}}{
Should renv attempt to manage the version control system's ignore files
(e.g. \code{.gitignore}) within this project? Set this to \code{FALSE} if you'd
prefer to take control. Note that if this setting is enabled, you will
need to manually ensure internal data in the project's \verb{renv/} folder
is explicitly ignored.
}
\subsection{\code{vcs.ignore.cellar}}{
Set whether packages within a project-local package cellar are excluded
from version control. See \code{vignette("cellar", package = "renv")} for
more information.
}
\subsection{\code{vcs.ignore.library}}{
Set whether the renv project library is excluded from version control.
}
\subsection{\code{vcs.ignore.local}}{
Set whether renv project-specific local sources are excluded from version
control.
}
}
\section{Defaults}{
You can change the default values of these settings for newly-created renv
projects by setting \R options for \code{renv.settings} or \verb{renv.settings.}.
For example:
\if{html}{\out{
}}
If both of the \code{renv.settings} and \verb{renv.settings.} options are set
for a particular key, the option associated with \verb{renv.settings.} is
used instead. We recommend setting these in an appropriate startup profile,
e.g. \verb{~/.Rprofile} or similar.
}
\examples{
\dontrun{
# view currently-ignored packaged
renv::settings$ignored.packages()
# ignore a set of packages
renv::settings$ignored.packages("devtools", persist = FALSE)
}
}
\keyword{datasets}
renv/man/checkout.Rd 0000644 0001762 0000144 00000006141 14464550375 014112 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/checkout.R
\name{checkout}
\alias{checkout}
\title{Checkout a repository}
\usage{
checkout(
repos = NULL,
...,
packages = NULL,
date = NULL,
clean = FALSE,
actions = "restore",
project = NULL
)
}
\arguments{
\item{repos}{The \R package repositories to use.}
\item{...}{Unused arguments, reserved for future expansion. If any arguments
are matched to \code{...}, renv will signal an error.}
\item{packages}{The packages to be installed. When \code{NULL} (the default),
all packages currently used in the project will be installed, as
determined by \code{\link[=dependencies]{dependencies()}}. The recursive dependencies of these
packages will be included as well.}
\item{date}{The snapshot date to use. When set, the associated snapshot as
available from the Posit's public
\href{https://packagemanager.rstudio.com/}{Package Manager} instance will be
used. Ignored if \code{repos} is non-\code{NULL}.}
\item{clean}{Boolean; remove packages not recorded in the lockfile from
the target library? Use \code{clean = TRUE} if you'd like the library state
to exactly reflect the lockfile contents after \code{restore()}.}
\item{actions}{The action(s) to perform with the requested repositories.
This can either be "snapshot", in which \code{renv} will generate a lockfile
based on the latest versions of the packages available from \code{repos}, or
"restore" if you'd like to install those packages. You can use
\code{c("snapshot", "restore")} if you'd like to generate a lockfile and
install those packages in the same step.}
\item{project}{The project directory. If \code{NULL}, then the active project will
be used. If no project is currently active, then the current working
directory is used instead.}
}
\description{
\code{renv::checkout()} can be used to retrieve the latest-availabe packages from
a (set of) package repositories.
}
\details{
\code{renv::checkout()} is most useful with services like the Posit's
\href{https://packagemanager.rstudio.com/}{Package Manager}, as it
can be used to switch between different repository snapshots within an
renv project. In this way, you can upgrade (or downgrade) all of the
packages used in a particular renv project to the package versions
provided by a particular snapshot.
If your library contains packages installed from other remote sources (e.g.
GitHub), but a version of a package of the same name is provided by the
repositories being checked out, then please be aware that the package will be
replaced with the version provided by the requested repositories. This could
be a concern if your project uses \R packages from GitHub whose name matches
that of an existing CRAN package, but is otherwise unrelated to the package
on CRAN.
}
\examples{
\dontrun{
# check out packages from PPM using the date '2023-01-02'
renv::checkout(date = "2023-01-02")
# alternatively, supply the full repository path
renv::checkout(repos = "https://packagemanager.rstudio.com/cran/2023-01-02")
# only check out some subset of packages (and their recursive dependencies)
renv::checkout(packages = "dplyr", date = "2023-01-02")
}
}
renv/man/remove.Rd 0000644 0001762 0000144 00000002753 14441721610 013572 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/remove.R
\name{remove}
\alias{remove}
\title{Remove packages}
\usage{
remove(packages, ..., library = NULL, project = NULL)
}
\arguments{
\item{packages}{A character vector of \R packages to remove.}
\item{...}{Unused arguments, reserved for future expansion. If any arguments
are matched to \code{...}, renv will signal an error.}
\item{library}{The library from which packages should be removed. When
\code{NULL}, the active library (that is, the first entry reported in
\code{.libPaths()}) is used instead.}
\item{project}{The project directory. If \code{NULL}, then the active project will
be used. If no project is currently active, then the current working
directory is used instead.}
}
\value{
A vector of package records, describing the packages (if any) which
were successfully removed.
}
\description{
Remove (uninstall) \R packages.
}
\examples{
\dontrun{
# disable automatic snapshots
auto.snapshot <- getOption("renv.config.auto.snapshot")
options(renv.config.auto.snapshot = FALSE)
# initialize a new project (with an empty R library)
renv::init(bare = TRUE)
# install digest 0.6.19
renv::install("digest@0.6.19")
# save library state to lockfile
renv::snapshot()
# remove digest from library
renv::remove("digest")
# check library status
renv::status()
# restore lockfile, thereby reinstalling digest 0.6.19
renv::restore()
# restore automatic snapshots
options(renv.config.auto.snapshot = auto.snapshot)
}
}
renv/man/run.Rd 0000644 0001762 0000144 00000002263 14441721611 013076 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/run.R
\name{run}
\alias{run}
\title{Run a script}
\usage{
run(script, ..., job = NULL, name = NULL, project = NULL)
}
\arguments{
\item{script}{The path to an \R script.}
\item{...}{Unused arguments, reserved for future expansion. If any arguments
are matched to \code{...}, renv will signal an error.}
\item{job}{Run the requested script as an RStudio job? Requires a recent
version of both RStudio and the rstudioapi packages. When \code{NULL}, the
script will be run as a job if possible, and as a regular \R process
launched by \code{\link[=system2]{system2()}} if not.}
\item{name}{The name to associate with the job, for scripts run as a job.}
\item{project}{The path to the renv project. This project will be loaded
before the requested script is executed. When \code{NULL} (the default), renv
will automatically determine the project root for the associated script
if possible.}
}
\value{
The project directory, invisibly. Note that this function is normally
called for its side effects.
}
\description{
Run an \R script, in the context of a project using renv. The script will
be run within an \R sub-process.
}
renv/man/paths.Rd 0000644 0001762 0000144 00000015256 14570476327 013435 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/paths.R
\docType{data}
\name{paths}
\alias{paths}
\title{Path for storing global state}
\usage{
paths
}
\description{
By default, renv stores global state in the following OS-specific folders:
\tabular{ll}{
\strong{Platform} \tab \strong{Location} \cr
Linux \tab \verb{~/.cache/R/renv} \cr
macOS \tab \verb{~/Library/Caches/org.R-project.R/R/renv} \cr
Windows \tab \verb{\%LOCALAPPDATA\%/R/cache/R/renv} \cr
}
If desired, this path can be customized by setting the \code{RENV_PATHS_ROOT}
environment variable. This can be useful if you'd like, for example, multiple
users to be able to share a single global cache.
}
\section{Customising individual paths}{
The various state sub-directories can also be individually adjusted, if so
desired (e.g. you'd prefer to keep the cache of package installations on a
separate volume). The various environment variables that can be set are
enumerated below:
\tabular{ll}{
\strong{Environment Variable} \tab \strong{Description} \cr
\code{RENV_PATHS_ROOT} \tab The root path used for global state storage. \cr
\code{RENV_PATHS_LIBRARY} \tab The path to the project library. \cr
\code{RENV_PATHS_LIBRARY_ROOT} \tab The parent path for project libraries. \cr
\code{RENV_PATHS_LIBRARY_STAGING} \tab The parent path used for staged package installs. \cr
\code{RENV_PATHS_SANDBOX} \tab The path to the sandboxed \R system library. \cr
\code{RENV_PATHS_LOCKFILE} \tab The path to the \link{lockfile}. \cr
\code{RENV_PATHS_CELLAR} \tab The path to the cellar, containing local package binaries and sources. \cr
\code{RENV_PATHS_SOURCE} \tab The path containing downloaded package sources. \cr
\code{RENV_PATHS_BINARY} \tab The path containing downloaded package binaries. \cr
\code{RENV_PATHS_CACHE} \tab The path containing cached package installations. \cr
\code{RENV_PATHS_PREFIX} \tab An optional prefix to prepend to the constructed library / cache paths. \cr
\code{RENV_PATHS_RENV} \tab The path to the project's renv folder. For advanced users only. \cr
\code{RENV_PATHS_RTOOLS} \tab (Windows only) The path to \href{https://cran.r-project.org/bin/windows/Rtools/}{Rtools}. \cr
\code{RENV_PATHS_EXTSOFT} \tab (Windows only) The path containing external software needed for compilation of Windows source packages. \cr
}
(If you want these settings to persist in your project, it is recommended that
you add these to an appropriate \R startup file. For example, these could be
set in: a project-local \code{.Renviron}, the user-level \code{.Renviron}, or a
site-wide file at \code{file.path(R.home("etc"), "Renviron.site")}. See
\link{Startup} for more details).
Note that renv will append platform-specific and version-specific entries
to the set paths as appropriate. For example, if you have set:
\if{html}{\out{
}}
then the directory used for the cache will still depend on the renv cache
version (e.g. \code{v2}), the \R version (e.g. \code{3.5}) and the platform (e.g.
\code{x86_64-pc-linux-gnu}). For example:
\if{html}{\out{
}}
This ensures that you can set a single \code{RENV_PATHS_CACHE} environment variable
globally without worry that it may cause collisions or errors if multiple
versions of \R needed to interact with the same cache.
If reproducibility of a project is desired on a particular machine, it is
highly recommended that the renv cache of installed packages + binary
packages is backed up and persisted, so that packages can be easily restored
in the future -- installation of packages from source can often be arduous.
}
\section{Sharing state across operating systems}{
If you need to share the same cache with multiple different Linux operating
systems, you may want to set the \code{RENV_PATHS_PREFIX} environment variable
to help disambiguate the paths used on Linux. For example, setting
\code{RENV_PATHS_PREFIX = "ubuntu-bionic"} would instruct renv to construct a
cache path like:
\if{html}{\out{
}}
If this is required, it's strongly recommended that this environment
variable is set in your \R installation's \code{Renviron.site} file, typically
located at \code{file.path(R.home("etc"), "Renviron.site")}, so that it can be
active for any \R sessions launched on that machine.
Starting from \verb{renv 0.13.0}, you can also instruct renv to auto-generate
an OS-specific component to include as part of library and cache paths,
by setting the environment variable:
\if{html}{\out{
}}
The prefix will be constructed based on fields within the system's
\verb{/etc/os-release} file. Note that this is the default behavior with
\verb{renv 1.0.6} when using R 4.4.0 or later.
}
\section{Package cellar}{
If your project depends on one or \R packages that are not available in any
remote location, you can still provide a locally-available tarball for renv
to use during restore. By default, these packages should be made available in
the folder as specified by the \code{RENV_PATHS_CELLAR} environment variable. The
package sources should be placed in a file at one of these locations:
\itemize{
\item \verb{$\{RENV_PATHS_CELLAR\}/_.}
\item \verb{$\{RENV_PATHS_CELLAR\}//_.}
\item \verb{/renv/cellar/_.}
\item \verb{/renv/cellar//_.}
}
where \verb{.} is \code{.tar.gz} for source packages, or \code{.tgz} for binaries on
macOS and \code{.zip} for binaries on Windows. During \code{restore()}, renv will
search the cellar for a compatible package, and prefer installation with
that copy of the package if appropriate.
}
\section{Older versions}{
Older version of renv used a different default cache location.
Those cache locations are:
\tabular{ll}{
\strong{Platform} \tab \strong{Location} \cr
Linux \tab \verb{~/.local/share/renv} \cr
macOS \tab \verb{~/Library/Application Support/renv} \cr
Windows \tab \verb{\%LOCALAPPDATA\%/renv} \cr
}
If an renv root directory has already been created in one of the old
locations, that will still be used. This change was made to comply with the
CRAN policy requirements of \R packages.
}
\examples{
# get the path to the project library
path <- renv::paths$library()
}
\keyword{datasets}
renv/man/status.Rd 0000644 0001762 0000144 00000015320 14547051446 013624 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/status.R
\name{status}
\alias{status}
\title{Report inconsistencies between lockfile, library, and dependencies}
\usage{
status(
project = NULL,
...,
library = NULL,
lockfile = NULL,
sources = TRUE,
cache = FALSE,
dev = FALSE
)
}
\arguments{
\item{project}{The project directory. If \code{NULL}, then the active project will
be used. If no project is currently active, then the current working
directory is used instead.}
\item{...}{Unused arguments, reserved for future expansion. If any arguments
are matched to \code{...}, renv will signal an error.}
\item{library}{The library paths. By default, the library paths associated
with the requested project are used.}
\item{lockfile}{Path to a lockfile. When \code{NULL} (the default), the
\code{renv.lock} located in the root of the current project will be used.}
\item{sources}{Boolean; check that each of the recorded packages have a
known installation source? If a package has an unknown source, renv
may be unable to restore it.}
\item{cache}{Boolean; perform diagnostics on the global package cache?
When \code{TRUE}, renv will validate that the packages installed into the
cache are installed at the expected + proper locations, and validate the
hashes used for those storage locations.}
\item{dev}{Boolean; include development dependencies? These packages are
typically required when developing the project, but not when running it
(i.e. you want them installed when humans are working on the project but
not when computers are deploying it).
Development dependencies include packages listed in the \code{Suggests} field
of a \code{DESCRIPTION} found in the project root, and roxygen2 or devtools if
their use is implied by other project metadata. They also include packages
used in \verb{~/.Rprofile} if \code{config$user.profile()} is \code{TRUE}.}
}
\value{
This function is normally called for its side effects, but
it invisibly returns a list containing the following components:
\itemize{
\item \code{library}: packages in your library.
\item \code{lockfile}: packages in the lockfile.
\item \code{synchronized}: are the library and lockfile in sync?
}
}
\description{
\code{renv::status()} reports issues caused by inconsistencies across the project
lockfile, library, and \code{\link[=dependencies]{dependencies()}}. In general, you should strive to
ensure that \code{status()} reports no issues, as this maximizes your chances of
successfully \code{restore()}ing the project in the future or on another machine.
\code{renv::load()} will report if any issues are detected when starting an
renv project; we recommend resolving these issues before doing any
further work on your project.
See the headings below for specific advice on resolving any issues
revealed by \code{status()}.
}
\section{Missing packages}{
\code{status()} first checks that all packages used by the project are installed.
This must be done first because if any packages are missing we can't tell for
sure that a package isn't used; it might be a dependency that we don't know
about. Once you have resolve any installation issues, you'll need to run
\code{status()} again to reveal the next set of potential problems.
There are four possibilities for an uninstalled package:
\itemize{
\item If it's used and recorded, call \code{renv::restore()} to install the version
specified in the lockfile.
\item If it's used and not recorded, call \code{renv::install()} to install it
from CRAN or elsewhere.
\item If it's not used and recorded, call \code{renv::snapshot()} to
remove it from the lockfile.
\item If it's not used and not recorded, there's nothing to do. This the most
common state because you only use a small fraction of all available
packages in any one project.
}
If you have multiple packages in an inconsistent state, we recommend
\code{renv::restore()}, then \code{renv::install()}, then \code{renv::snapshot()}, but
that also suggests you should be running status more frequently.
}
\section{Lockfile vs \code{dependencies()}}{
Next we need to ensure that packages are recorded in the lockfile if and
only if they are used by the project. Fixing issues of this nature only
requires calling \code{snapshot()} because there are four possibilities for
a package:
\itemize{
\item If it's used and recorded, it's ok.
\item If it's used and not recorded, call \code{renv::snapshot()} to add it to the
lockfile.
\item If it's not used but is recorded, call \code{renv::snapshot()} to remove
it from the lockfile.
\item If it's not used and not recorded, it's also ok, as it may be a
development dependency.
}
}
\section{Out-of-sync sources}{
The final issue to resolve is any inconsistencies between the version of
the package recorded in the lockfile and the version installed in your
library. To fix these issues you'll need to either call \code{renv::restore()}
or \code{renv::snapshot()}:
\itemize{
\item Call \code{renv::snapshot()} if your project code is working. This implies that
the library is correct and you need to update your lockfile.
\item Call \code{renv::restore()} if your project code isn't working. This probably
implies that you have the wrong package versions installed and you need
to restore from known good state in the lockfile.
}
If you're not sure which case applies, it's generally safer to call
\code{renv::snapshot()}. If you want to rollback to an earlier known good
status, see \code{\link[=history]{history()}} and \code{\link[=revert]{revert()}}.
}
\section{Different R Version}{
renv will also notify you if the version of R used when the lockfile was
generated, and the version of R currently in use, do not match. In this
scenario, you'll need to consider:
\itemize{
\item Is the version of R recorded in the lockfile correct? If so, you'll want
to ensure that version of R is installed and used when working in this
project.
\item Otherwise, you can call \code{renv::snapshot()} to update the version of R
recorded in the lockfile, to match the version of R currently in use.
}
If you'd like to set the version of R recorded in a lockfile independently
of the version of R currently in use, you can set the \code{r.version} project
setting -- see \link{settings} for more details.
}
\examples{
\dontrun{
# disable automatic snapshots
auto.snapshot <- getOption("renv.config.auto.snapshot")
options(renv.config.auto.snapshot = FALSE)
# initialize a new project (with an empty R library)
renv::init(bare = TRUE)
# install digest 0.6.19
renv::install("digest@0.6.19")
# save library state to lockfile
renv::snapshot()
# remove digest from library
renv::remove("digest")
# check library status
renv::status()
# restore lockfile, thereby reinstalling digest 0.6.19
renv::restore()
# restore automatic snapshots
options(renv.config.auto.snapshot = auto.snapshot)
}
}
renv/man/clean.Rd 0000644 0001762 0000144 00000004775 14441721610 013365 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/clean.R
\name{clean}
\alias{clean}
\title{Clean a project}
\usage{
clean(project = NULL, ..., actions = NULL, prompt = interactive())
}
\arguments{
\item{project}{The project directory. If \code{NULL}, then the active project will
be used. If no project is currently active, then the current working
directory is used instead.}
\item{...}{Unused arguments, reserved for future expansion. If any arguments
are matched to \code{...}, renv will signal an error.}
\item{actions}{The set of clean actions to take. See the documentation in
\strong{Actions} for a list of available actions, and the default actions
taken when no actions are supplied.}
\item{prompt}{Boolean; prompt the user before taking any action? For backwards
compatibility, \code{confirm} is accepted as an alias for \code{prompt}.}
}
\value{
The project directory, invisibly. Note that this function is normally
called for its side effects.
}
\description{
Clean up a project and its associated \R libraries.
}
\section{Actions}{
The following clean actions are available:
\describe{
\item{\code{package.locks}}{
During package installation, \R will create package locks in the
library path, typically named \verb{00LOCK-}. On occasion, if package
installation fails or \R is terminated while installing a package, these
locks can be left behind and will inhibit future attempts to reinstall
that package. Use this action to remove such left-over package locks.
}
\item{\code{library.tempdirs}}{
During package installation, \R may create temporary directories with
names of the form \verb{file\\w\{12\}}, and on occasion those files can be
left behind even after they are no longer in use. Use this action to
remove such left-over directories.
}
\item{\code{system.library}}{
In general, it is recommended that only packages distributed with \R
are installed into the default library (the library path referred to
by \code{.Library}). Use this action to remove any user-installed packages
that have been installed to the system library.
Because this action is destructive, it is by default never run -- it
must be explicitly requested by the user.
}
\item{\code{unused.packages}}{
Remove packages that are installed in the project library, but no longer
appear to be used in the project sources.
Because this action is destructive, it is by default only run in
interactive sessions when prompting is enabled.
}
}
}
\examples{
\dontrun{
# clean the current project
renv::clean()
}
}
renv/man/migrate.Rd 0000644 0001762 0000144 00000003501 14441721610 013715 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/migrate.R
\name{migrate}
\alias{migrate}
\title{Migrate a project from packrat to renv}
\usage{
migrate(
project = NULL,
packrat = c("lockfile", "sources", "library", "options", "cache")
)
}
\arguments{
\item{project}{The project directory. If \code{NULL}, then the active project will
be used. If no project is currently active, then the current working
directory is used instead.}
\item{packrat}{Components of the Packrat project to migrate. See the default
argument list for components of the Packrat project that can be migrated.
Select a subset of those components for migration as appropriate.}
}
\value{
The project directory, invisibly. Note that this function is normally
called for its side effects.
}
\description{
Migrate a project's infrastructure from packrat to renv.
}
\section{Migration}{
When migrating Packrat projects to renv, the set of components migrated
can be customized using the \code{packrat} argument. The set of components that
can be migrated are as follows:
\tabular{ll}{
\strong{Name} \tab \strong{Description} \cr
\code{lockfile} \tab
Migrate the Packrat lockfile (\code{packrat/packrat.lock}) to the renv lockfile
(\code{renv.lock}). \cr
\code{sources} \tab
Migrate package sources from the \code{packrat/src} folder to the renv
sources folder. Currently, only CRAN packages are migrated to renv --
packages retrieved from other sources (e.g. GitHub) are ignored.
\cr
\code{library} \tab
Migrate installed packages from the Packrat library to the renv project
library.
\cr
\code{options} \tab
Migrate compatible Packrat options to the renv project.
\cr
\code{cache} \tab
Migrate packages from the Packrat cache to the renv cache.
\cr
}
}
\examples{
\dontrun{
# migrate Packrat project infrastructure to renv
renv::migrate()
}
}
renv/man/project.Rd 0000644 0001762 0000144 00000001014 14441721610 013730 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/project.R
\name{project}
\alias{project}
\title{Retrieve the active project}
\usage{
project(default = NULL)
}
\arguments{
\item{default}{The value to return when no project is
currently active. Defaults to \code{NULL}.}
}
\value{
The active project directory, as a length-one character vector.
}
\description{
Retrieve the path to the active project (if any).
}
\examples{
\dontrun{
# get the currently-active renv project
renv::project()
}
}
renv/man/activate.Rd 0000644 0001762 0000144 00000004144 14567447703 014112 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/activate.R, R/deactivate.R
\name{activate}
\alias{activate}
\alias{deactivate}
\title{Activate or deactivate a project}
\usage{
activate(project = NULL, profile = NULL)
deactivate(project = NULL, clean = FALSE)
}
\arguments{
\item{project}{The project directory. If \code{NULL}, then the active project will
be used. If no project is currently active, then the current working
directory is used instead.}
\item{profile}{The profile to be activated. See
\code{vignette("profiles", package = "renv")} for more information.}
\item{clean}{If \code{TRUE}, will also remove the \verb{renv/} directory and the
lockfile.}
}
\value{
The project directory, invisibly. Note that this function is normally
called for its side effects.
}
\description{
\code{activate()} enables renv for a project in both the current session and
in all future sessions. You should not generally need to call \code{activate()}
yourself as it's called automatically by \code{\link[=init]{init()}}, which is the best
way to start using renv in a new project.
\code{activate()} first calls \code{\link[=scaffold]{scaffold()}} to set up the project
infrastructure. Most importantly, this creates a project library and adds a
an auto-loader to \code{.Rprofile} to ensure that the project library is
automatically used for all future instances of the project. It then restarts
the session to use that auto-loader.
\code{deactivate()} removes the infrastructure added by \code{activate()}, and
restarts the session. By default it will remove the auto-loader from the
\code{.Rprofile}; use \code{clean = TRUE} to also delete the lockfile and the project
library.
}
\section{Temporary deactivation}{
If you need to temporarily disable autoload activation you can set
the \code{RENV_CONFIG_AUTOLOADER_ENABLED} envvar, e.g.
\code{Sys.setenv(RENV_CONFIG_AUTOLOADER_ENABLED = "false")}.
}
\examples{
\dontrun{
# activate the current project
renv::activate()
# activate a separate project
renv::activate(project = "~/projects/analysis")
# deactivate the currently-activated project
renv::deactivate()
}
}
renv/man/sandbox.Rd 0000644 0001762 0000144 00000005441 14464550375 013745 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sandbox.R
\docType{data}
\name{sandbox}
\alias{sandbox}
\title{The default library sandbox}
\usage{
sandbox
}
\description{
An \R installation can have up to three types of library paths available
to the user:
\itemize{
\item The \emph{user library}, where \R packages downloaded and installed by the
current user are installed. This library path is only visible to that
specific user.
\item The \emph{site library}, where \R packages maintained by administrators of a
system are installed. This library path, if it exists, is visible to all
users on the system.
\item The \emph{default library}, where \R packages distributed with \R itself are
installed. This library path is visible to all users on the system.
}
Normally, only so-called "base" and "recommended" packages should be installed
in the default library. (You can get a list of these packages with
\code{installed.packages(priority = c("base", "recommended"))}). However, it is
possible for users and administrators to install packages into the default
library, if the filesystem permissions permit them to do so. (This, for
example, is the default behavior on macOS.)
Because the site and default libraries are visible to all users, having those
accessible in renv projects can potentially break isolation -- that is,
if a package were updated in the default library, that update would be visible
to all \R projects on the system.
To help defend against this, renv uses something called the "sandbox" to
isolate renv projects from non-"base" packages that are installed into the
default library. When an renv project is loaded, renv will:
\itemize{
\item Create a new, empty library path (called the "sandbox"),
\item Link only the "base" and "recommended" packages from the default library
into the sandbox,
\item Mark the sandbox as read-only, so that users are unable to install packages
into this library,
\item Instruct the \R session to use the "sandbox" as the default library.
}
This process is mostly transparent to the user. However, because the sandbox
is read-only, if you later need to remove the sandbox, you'll need to reset
file permissions manually; for example, with \code{renv::sandbox$unlock()}.
If you'd prefer to keep the sandbox unlocked, you can also set:
\if{html}{\out{
}}
The sandbox library path can also be configured using the \code{RENV_PATHS_SANDBOX}
environment variable: see \link{paths} for more details.
}
\keyword{datasets}
renv/man/use_python.Rd 0000644 0001762 0000144 00000012067 14441721611 014472 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/use-python.R
\name{use_python}
\alias{use_python}
\title{Use python}
\usage{
use_python(
python = NULL,
...,
type = c("auto", "virtualenv", "conda", "system"),
name = NULL,
project = NULL
)
}
\arguments{
\item{python}{The path to the version of Python to be used with this project. See
\strong{Finding Python} for more details.}
\item{...}{Optional arguments; currently unused.}
\item{type}{The type of Python environment to use. When \code{"auto"} (the default),
virtual environments will be used.}
\item{name}{The name or path that should be used for the associated Python environment.
If \code{NULL} and \code{python} points to a Python executable living within a
pre-existing virtual environment, that environment will be used. Otherwise,
a project-local environment will be created instead, using a name
generated from the associated version of Python.}
\item{project}{The project directory. If \code{NULL}, then the active project will
be used. If no project is currently active, then the current working
directory is used instead.}
}
\value{
\code{TRUE}, indicating that the requested version of Python has been
successfully activated. Note that this function is normally called for its
side effects.
}
\description{
Associate a version of Python with your project.
}
\details{
When Python integration is active, renv will:
\itemize{
\item Save metadata about the requested version of Python in \code{renv.lock} -- in
particular, the Python version, and the Python type ("virtualenv", "conda",
"system"),
\item Capture the set of installed Python packages during \code{renv::snapshot()},
\item Re-install the set of recorded Python packages during \code{renv::restore()}.
}
In addition, when the project is loaded, the following actions will be taken:
\itemize{
\item The \code{RENV_PYTHON} environment variable will be set, indicating the version
of Python currently active for this sessions,
\item The \code{RETICULATE_PYTHON} environment variable will be set, so that the
reticulate package can automatically use the requested copy of Python
as appropriate,
\item The requested version of Python will be placed on the \code{PATH}, so that
attempts to invoke Python will resolve to the expected version of Python.
}
You can override the version of Python used in a particular project by
setting the \code{RENV_PYTHON} environment variable; e.g. as part of the
project's \code{.Renviron} file. This can be useful if you find that renv
is unable to automatically discover a compatible version of Python to
be used in the project.
}
\section{Finding Python}{
In interactive sessions, when \code{python = NULL}, renv will prompt for an
appropriate version of Python. renv will search a pre-defined set of
locations when attempting to find Python installations on the system:
\itemize{
\item \code{getOption("renv.python.root")},
\item \verb{/opt/python},
\item \verb{/opt/local/python},
\item \verb{~/opt/python},
\item \verb{/usr/local/opt} (for macOS Homebrew-installed copies of Python),
\item \verb{/opt/homebrew/opt} (for M1 macOS Homebrew-installed copies of Python),
\item \verb{~/.pyenv/versions},
\item Python instances available on the \code{PATH}.
}
In non-interactive sessions, renv will first check the \code{RETICULATE_PYTHON}
environment variable; if that is unset, renv will look for Python on the
\code{PATH}. It is recommended that the version of Python to be used is explicitly
supplied for non-interactive usages of \code{use_python()}.
}
\section{Warning}{
We strongly recommend using Python virtual environments, for a few reasons:
\enumerate{
\item If something goes wrong with a local virtual environment, you can safely
delete that virtual environment, and then re-initialize it later, without
worry that doing so might impact other software on your system.
\item If you choose to use a "system" installation of Python, then any packages
you install or upgrade will be visible to any other application that
wants to use that same Python installation. Using a virtual environment
ensures that any changes made are isolated to that environment only.
\item Choosing to use Anaconda will likely invite extra frustration in the
future, as you may be required to upgrade and manage your Anaconda
installation as new versions of Anaconda are released. In addition,
Anaconda installations tend to work poorly with software not specifically
installed as part of that same Anaconda installation.
}
In other words, we recommend selecting "system" or "conda" only if you are an
expert Python user who is already accustomed to managing Python / Anaconda
installations on your own.
}
\examples{
\dontrun{
# use python with a project
renv::use_python()
# use python with a project; create the environment
# within the project directory in the '.venv' folder
renv::use_python(name = ".venv")
# use python with a pre-existing virtual environment located elsewhere
renv::use_python(name = "~/.virtualenvs/env")
# use virtualenv python with a project
renv::use_python(type = "virtualenv")
# use conda python with a project
renv::use_python(type = "conda")
}
}
renv/man/embed.Rd 0000644 0001762 0000144 00000007711 14464550375 013365 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/embed.R, R/use.R
\name{embed}
\alias{embed}
\alias{use}
\title{Capture and re-use dependencies within a \code{.R} or \code{.Rmd}}
\usage{
embed(path = NULL, ..., lockfile = NULL, project = NULL)
use(
...,
lockfile = NULL,
library = NULL,
isolate = sandbox,
sandbox = TRUE,
attach = FALSE,
verbose = TRUE
)
}
\arguments{
\item{path}{The path to an \R or R Markdown script. The default will use the current
document, if running within RStudio.}
\item{...}{The \R packages to be used with this script. Ignored if \code{lockfile} is
non-\code{NULL}.}
\item{lockfile}{The lockfile to use. When supplied, renv will use the packages as
declared in the lockfile.}
\item{project}{The project directory. If \code{NULL}, then the active project will
be used. If no project is currently active, then the current working
directory is used instead.}
\item{library}{The library path into which the requested packages should be installed.
When \code{NULL} (the default), a library path within the \R temporary
directory will be generated and used. Note that this same library path
will be re-used on future calls to \code{renv::use()}, allowing \code{renv::use()}
to be used multiple times within a single script.}
\item{isolate}{Boolean; should the active library paths be included in the set of library
paths activated for this script? Set this to \code{TRUE} if you only want the
packages provided to \code{renv::use()} to be visible on the library paths.}
\item{sandbox}{Should the system library be sandboxed? See the sandbox documentation in
\link{config} for more details. You can also provide an explicit sandbox
path if you want to configure where \code{renv::use()} generates its sandbox.
By default, the sandbox is generated within the \R temporary directory.}
\item{attach}{Boolean; should the set of requested packages be automatically attached?
If \code{TRUE}, packages will be loaded and attached via a call
to \code{\link[=library]{library()}} after install. Ignored if \code{lockfile} is non-\code{NULL}.}
\item{verbose}{Boolean; be verbose while installing packages?}
}
\value{
This function is normally called for its side effects.
}
\description{
Together, \code{embed()} and \code{use()} provide a lightweight way to specify and
restore package versions within a file. \code{use()} is a lightweight lockfile
specification that \code{embed()} can automatically generate and insert into a
script or document.
Calling \code{embed()} inspects the dependencies of the specified document then
generates and inserts a call to \code{use()} that looks something like this:
\if{html}{\out{
}}
Then, when you next run your R script or render your \code{.Rmd}, \code{use()} will:
\enumerate{
\item Create a temporary library path.
\item Install the requested packages and their recursive dependencies into that
library.
\item Activate the library, so it's used for the rest of the script.
}
\subsection{Manual usage}{
You can also create calls to \code{use()} yourself, either specifying the
packages needed by hand, or by supplying the path to a lockfile,
\code{renv::use(lockfile = "/path/to/renv.lock")}.
This can be useful in projects where you'd like to associate different
lockfiles with different documents, as in a blog where you want each
post to capture the dependencies at the time of writing. Once you've
finished writing each, the post, you can use
\code{renv::snapshot(lockfile = "/path/to/renv.lock")}
to "save" the state that was active while authoring that bost, and then use
\code{renv::use(lockfile = "/path/to/renv.lock")} in that document to ensure the
blog post always uses those dependencies onfuture renders.
\code{renv::use()} is inspired in part by the \href{https://groundhogr.com/}{groundhog}
package, which also allows one to specify a script's \R package requirements
within that same \R script.
}
}
renv/man/purge.Rd 0000644 0001762 0000144 00000003437 14441721610 013417 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/purge.R
\name{purge}
\alias{purge}
\title{Purge packages from the cache}
\usage{
purge(package, ..., version = NULL, hash = NULL, prompt = interactive())
}
\arguments{
\item{package}{A single package to be removed from the cache.}
\item{...}{Unused arguments, reserved for future expansion. If any arguments
are matched to \code{...}, renv will signal an error.}
\item{version}{The package version to be removed. When \code{NULL}, all versions
of the requested package will be removed.}
\item{hash}{The specific hashes to be removed. When \code{NULL}, all hashes
associated with a particular package's version will be removed.}
\item{prompt}{Boolean; prompt the user before taking any action? For backwards
compatibility, \code{confirm} is accepted as an alias for \code{prompt}.}
}
\value{
The set of packages removed from the renv global cache,
as a character vector of file paths.
}
\description{
Purge packages from the cache. This can be useful if a package which had
previously been installed in the cache has become corrupted or unusable,
and needs to be reinstalled.
}
\details{
\code{purge()} is an inherently destructive option. It removes packages from the
cache, and so any project which had symlinked that package into its own
project library would find that package now unavailable. These projects would
hence need to reinstall any purged packages. Take heed of this in case you're
looking to purge the cache of a package which is difficult to install, or
if the original sources for that package are no longer available!
}
\examples{
\dontrun{
# remove all versions of 'digest' from the cache
renv::purge("digest")
# remove only a particular version of 'digest' from the cache
renv::purge("digest", version = "0.6.19")
}
}
renv/man/figures/ 0000755 0001762 0000144 00000000000 14257631444 013455 5 ustar ligges users renv/man/figures/logo.svg 0000644 0001762 0000144 00000215526 14257631444 015151 0 ustar ligges users renv/man/repair.Rd 0000644 0001762 0000144 00000002272 14464550375 013570 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/repair.R
\name{repair}
\alias{repair}
\title{Repair a project}
\usage{
repair(library = NULL, lockfile = NULL, project = NULL)
}
\arguments{
\item{library}{The \R library to be used. When \code{NULL}, the active project
library will be used instead.}
\item{lockfile}{The path to a lockfile (if any). When available, renv
will use the lockfile when attempting to infer the remote associated
with the inaccessible version of each missing package. When \code{NULL}
(the default), the project lockfile will be used.}
\item{project}{The project directory. If \code{NULL}, then the active project will
be used. If no project is currently active, then the current working
directory is used instead.}
}
\description{
Use \code{repair()} to recover from some common issues that can occur with
a project. Currently, two operations are performed:
}
\details{
\enumerate{
\item Packages with broken symlinks into the cache will be re-installed.
\item Packages that were installed from sources, but appear to be from
an remote source (e.g. GitHub), will have their \code{DESCRIPTION} files
updated to record that remote source explicitly.
}
}
renv/man/scaffold.Rd 0000644 0001762 0000144 00000003067 14464550375 014072 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/scaffold.R
\name{scaffold}
\alias{scaffold}
\title{Generate project infrastructure}
\usage{
scaffold(
project = NULL,
version = NULL,
repos = getOption("repos"),
settings = NULL
)
}
\arguments{
\item{project}{The project directory. If \code{NULL}, then the active project will
be used. If no project is currently active, then the current working
directory is used instead.}
\item{version}{The version of renv to associate with this project. By
default, the version of renv currently installed is used.}
\item{repos}{The \R repositories to associate with this project.}
\item{settings}{A list of renv settings, to be applied to the project
after creation. These should map setting names to the desired values.
See \link{settings} for more details.}
}
\description{
Create the renv project infrastructure. This will:
\itemize{
\item Create a project library, \code{renv/library}.
\item Install renv into the project library.
\item Update the project \code{.Rprofile} to call \code{source("renv/activate.R")} so
that renv is automatically loaded for new \R sessions launched in
this project.
\item Create \code{renv/.gitignore}, which tells git to ignore the project library.
\item Create \code{.Rbuildignore}, if the project is also a package. This tells
\verb{R CMD build} to ignore the renv infrastructure,
\item Write a (bare) \link{lockfile}, \code{renv.lock}.
}
}
\examples{
\dontrun{
# create scaffolding with 'devtools' ignored
renv::scaffold(settings = list(ignored.packages = "devtools"))
}
}
renv/man/rebuild.Rd 0000644 0001762 0000144 00000003341 14441721610 013715 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rebuild.R
\name{rebuild}
\alias{rebuild}
\title{Rebuild the packages in your project library}
\usage{
rebuild(
packages = NULL,
recursive = TRUE,
...,
type = NULL,
prompt = interactive(),
library = NULL,
project = NULL
)
}
\arguments{
\item{packages}{The package(s) to be rebuilt. When \code{NULL}, all packages
in the library will be reinstalled.}
\item{recursive}{Boolean; should dependencies of packages be rebuilt
recursively? Defaults to \code{TRUE}.}
\item{...}{Unused arguments, reserved for future expansion. If any arguments
are matched to \code{...}, renv will signal an error.}
\item{type}{The type of package to install ("source" or "binary"). Defaults
to the value of \code{getOption("pkgType")}.}
\item{prompt}{Boolean; prompt the user before taking any action? For backwards
compatibility, \code{confirm} is accepted as an alias for \code{prompt}.}
\item{library}{The \R library to be used. When \code{NULL}, the active project
library will be used instead.}
\item{project}{The project directory. If \code{NULL}, then the active project will
be used. If no project is currently active, then the current working
directory is used instead.}
}
\value{
A named list of package records which were installed by renv.
}
\description{
Rebuild and reinstall packages in your library. This can be useful as a
diagnostic tool -- for example, if you find that one or more of your
packages fail to load, and you want to ensure that you are starting from a
clean slate.
}
\examples{
\dontrun{
# rebuild the 'dplyr' package + all of its dependencies
renv::rebuild("dplyr", recursive = TRUE)
# rebuild only 'dplyr'
renv::rebuild("dplyr", recursive = FALSE)
}
}
renv/man/renv-package.Rd 0000644 0001762 0000144 00000002100 14464550375 014637 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/renv-package.R
\docType{package}
\name{renv-package}
\alias{renv}
\alias{renv-package}
\title{Project-local Environments for R}
\description{
Project-local environments for \R.
}
\details{
You can use renv to construct isolated, project-local \R libraries.
Each project using renv will share package installations from a global
cache of packages, helping to avoid wasting disk space on multiple
installations of a package that might otherwise be shared across projects.
}
\seealso{
Useful links:
\itemize{
\item \url{https://rstudio.github.io/renv/}
\item \url{https://github.com/rstudio/renv}
\item Report bugs at \url{https://github.com/rstudio/renv/issues}
}
}
\author{
\strong{Maintainer}: Kevin Ushey \email{kevin@rstudio.com} (\href{https://orcid.org/0000-0003-2880-7407}{ORCID})
Authors:
\itemize{
\item Hadley Wickham \email{hadley@rstudio.com} (\href{https://orcid.org/0000-0003-4757-117X}{ORCID})
}
Other contributors:
\itemize{
\item Posit Software, PBC [copyright holder, funder]
}
}
renv/man/upgrade.Rd 0000644 0001762 0000144 00000003376 14464550375 013743 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/upgrade.R
\name{upgrade}
\alias{upgrade}
\title{Upgrade renv}
\usage{
upgrade(project = NULL, version = NULL, reload = NULL, prompt = interactive())
}
\arguments{
\item{project}{The project directory. If \code{NULL}, then the active project will
be used. If no project is currently active, then the current working
directory is used instead.}
\item{version}{The version of renv to be installed.
When \code{NULL} (the default), the latest version of renv will be installed as
available from CRAN (or whatever active package repositories are active)
Alternatively, you can install the latest development version with
\code{"main"}, or a specific commit with a SHA, e.g. \code{"5049cef8a"}.}
\item{reload}{Boolean; reload renv after install? When \code{NULL} (the
default), renv will be re-loaded only if updating renv for the
active project. Since it's not possible to guarantee a clean reload
in the current session, this will attempt to restart your R session.}
\item{prompt}{Boolean; prompt upgrade before proceeding?}
}
\value{
A boolean value, indicating whether the requested version of
renv was successfully installed. Note that this function is normally
called for its side effects.
}
\description{
Upgrade the version of renv associated with a project, including using
a development version from GitHub. Automatically snapshots the update
renv, updates the activate script, and restarts R.
If you want to update all packages (including renv) to their latest CRAN
versions, use \code{\link[=update]{update()}}.
}
\examples{
\dontrun{
# upgrade to the latest version of renv
renv::upgrade()
# upgrade to the latest version of renv on GitHub (development version)
renv::upgrade(version = "main")
}
}
renv/man/imbue.Rd 0000644 0001762 0000144 00000002167 14441721610 013375 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/imbue.R
\name{imbue}
\alias{imbue}
\title{Imbue an renv Installation}
\usage{
imbue(project = NULL, version = NULL, quiet = FALSE)
}
\arguments{
\item{project}{The project directory. If \code{NULL}, then the active project will
be used. If no project is currently active, then the current working
directory is used instead.}
\item{version}{The version of renv to install. If \code{NULL}, the version
of renv currently installed will be used. The requested version of
renv will be retrieved from the renv public GitHub repository,
at \url{https://github.com/rstudio/renv}.}
\item{quiet}{Boolean; avoid printing output during install of renv?}
}
\value{
The project directory, invisibly. Note that this function is normally
called for its side effects.
}
\description{
Imbue an renv installation into a project, thereby making the requested
version of renv available within.
}
\details{
Normally, this function does not need to be called directly by the user; it
will be invoked as required by \code{\link[=init]{init()}} and \code{\link[=activate]{activate()}}.
}
renv/man/autoload.Rd 0000644 0001762 0000144 00000002372 14441721610 014102 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/autoload.R
\name{autoload}
\alias{autoload}
\title{Auto-load the active project}
\usage{
autoload()
}
\description{
Automatically load the renv project associated with a particular directory.
renv will search parent directories for the renv project root; if found,
that project will be loaded via \code{\link[=load]{load()}}.
}
\details{
To enable the renv auto-loader, you can place:
\if{html}{\out{
}}\preformatted{renv::autoload()
}\if{html}{\out{
}}
into your site-wide or user \code{.Rprofile} to ensure that renv projects are
automatically loaded for any newly-launched \R sessions, even if those \R
sessions are launched within the sub-directory of an renv project.
If you'd like to launch \R within the sub-directory of an renv project
without auto-loading renv, you can set the environment variable:
\if{html}{\out{
}}
before starting \R.
Note that \code{renv::autoload()} is only compatible with projects using
\verb{renv 0.15.3} or newer, as it relies on features within the \code{renv/activate.R}
script that are only generated with newer versions of renv.
}
renv/man/renv_lockfile_from_manifest.Rd 0000644 0001762 0000144 00000003222 14441721610 020020 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/manifest-convert.R
\name{renv_lockfile_from_manifest}
\alias{renv_lockfile_from_manifest}
\title{Generate \code{renv.lock} from an RStudio Connect \code{manifest.json}}
\usage{
renv_lockfile_from_manifest(manifest, lockfile = NA, project = NULL)
}
\arguments{
\item{manifest}{The path to a \code{manifest.json} file.}
\item{lockfile}{The path to the lockfile to be generated and / or updated.
When \code{NA} (the default), the generated lockfile is returned as an \R
object; otherwise, the lockfile will be written to the path specified by
\code{lockfile}.}
}
\value{
An renv lockfile.
}
\description{
Use \code{renv_lockfile_from_manifest()} to convert a \code{manifest.json} file from
an RStudio Connect content bundle into an \code{renv.lock} lockfile.
}
\details{
This function can be useful when you need to recreate the package environment
of a piece of content that is deployed to RStudio Connect. The content bundle
contains a \code{manifest.json} file that is used to recreate the package
environment. This function will let you convert that manifest file to an
\code{renv.lock} file. Run \code{renv::restore()} after you've converted the file to
restore the package environment.
By default the \code{lockfile} argument is set to \code{NA}. This will not create a new
\code{renv.lock} file. Rather, it will return a lockfile object (see \code{?lockfile})
that can be used to create a new \code{renv.lock} file. If \code{lockfile} is set to a
character string, a new file will be created with that path -- e.g.
\code{renv.lock} -- and the lockfile object will be returned.
}
\keyword{internal}
renv/man/consent.Rd 0000644 0001762 0000144 00000002334 14441721610 013741 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/consent.R
\name{consent}
\alias{consent}
\title{Consent to usage of renv}
\usage{
consent(provided = FALSE)
}
\arguments{
\item{provided}{The default provided response. If you need to provide
consent from a non-interactive \R session, you can invoke
\code{renv::consent(provided = TRUE)} explicitly.}
}
\value{
\code{TRUE} if consent is provided, or an \R error otherwise.
}
\description{
Provide consent to renv, allowing it to write and update certain files
on your filesystem.
}
\details{
As part of its normal operation, renv will write and update some files
in your project directory, as well as an application-specific cache
directory. These paths are documented within \link{paths}.
In accordance with the
\href{https://cran.r-project.org/web/packages/policies.html}{CRAN Repository Policy},
renv must first obtain consent from you, the user, before these actions
can be taken. Please call \code{renv::consent()} first to provide this consent.
You can also set the \R option:
\if{html}{\out{
", contents, fixed = TRUE)
list(
nexus = nexus
)
}
renv/R/release.R 0000644 0001762 0000144 00000000634 14413621502 013171 0 ustar ligges users
renv_release_preflight <- function() {
ok <- all(
renv_release_preflight_urlcheck()
)
if (!ok)
stop("one or more pre-flight release checks failed")
ok
}
renv_release_preflight_urlcheck <- function() {
# check for bad URLs
urlchecker <- renv_namespace_load("urlchecker")
result <- urlchecker$url_check()
# report to user
print(result)
# return success
nrow(result) == 0L
}
renv/R/pyenv.R 0000644 0001762 0000144 00000000371 14257631444 012724 0 ustar ligges users
renv_pyenv_root <- function() {
root <- Sys.getenv("PYENV_ROOT", unset = renv_pyenv_root_default())
path.expand(root)
}
renv_pyenv_root_default <- function() {
if (renv_platform_windows())
"~/.pyenv/pyenv-win"
else
"~/.pyenv"
}
renv/R/template.R 0000644 0001762 0000144 00000000463 14402014263 013362 0 ustar ligges users
renv_template_create <- function(template) {
gsub("^\\n+|\\n+$", "", template)
}
renv_template_replace <- function(text, replacements, format = "${%s}") {
enumerate(replacements, function(key, value) {
key <- sprintf(format, key)
text <<- gsub(key, value, text, fixed = TRUE)
})
text
}
renv/R/utils.R 0000644 0001762 0000144 00000027136 14606007150 012720 0 ustar ligges users
`%>%` <- function(...) {
dots <- eval(substitute(alist(...)))
if (length(dots) != 2L)
stopf("`%>%` called with invalid number of arguments")
lhs <- dots[[1L]]; rhs <- dots[[2L]]
if (!is.call(rhs))
stopf("right-hand side of rhs is not a call")
data <- c(rhs[[1L]], lhs, as.list(rhs[-1L]))
call <- as.call(data)
nm <- names(rhs)
if (length(nm))
names(call) <- c("", "", nm[-1L])
eval(call, envir = parent.frame())
}
`%NA%` <- function(x, y) {
if (length(x) && is.na(x)) y else x
}
`%&&%` <- function(x, y) {
if (length(x)) y
}
lines <- function(...) {
paste(..., sep = "\n")
}
is_named <- function(x) {
nm <- names(x)
!is.null(nm) && all(nzchar(nm))
}
named <- function(object, names = object) {
names(object) <- names
object
}
empty <- function(x) {
length(x) == 0L
}
zlength <- function(x) {
length(x) != 0L
}
trim <- function(x) {
gsub("^\\s+|\\s+$", "", x, perl = TRUE)
}
trimws <- function(x) {
gsub("^\\s+|\\s+$", "", x, perl = TRUE)
}
case <- function(...) {
dots <- eval(substitute(alist(...)))
for (i in seq_along(dots)) {
if (identical(dots[[i]], quote(expr = )))
next
dot <- eval(dots[[i]], envir = parent.frame())
if (!inherits(dot, "formula"))
return(dot)
# Silence R CMD check note
expr <- NULL
cond <- NULL
# use delayed assignments below so we can allow return statements to
# be handled in the lexical scope where they were defined
if (length(dot) == 2L) {
do.call(delayedAssign, list("expr", dot[[2L]], eval.env = environment(dot)))
return(expr)
}
do.call(delayedAssign, list("cond", dot[[2L]], eval.env = environment(dot)))
do.call(delayedAssign, list("expr", dot[[3L]], eval.env = environment(dot)))
if (cond) return(expr)
}
}
compose <- function(wrapper, callback) {
function(...) wrapper(callback(...))
}
catch <- function(expr) {
tryCatch(
withCallingHandlers(expr, error = renv_error_capture),
error = renv_error_tag
)
}
catchall <- function(expr) {
tryCatch(
withCallingHandlers(
expr = expr,
error = renv_error_capture,
warning = renv_error_capture
),
error = renv_error_tag,
warning = renv_error_tag
)
}
# nocov start
ask <- function(question, default = FALSE) {
if (renv_tests_running())
return(TRUE)
enabled <- getOption("renv.prompt.enabled", default = TRUE)
if (!enabled)
return(default)
if (!interactive())
return(default)
# be verbose in this scope, as we're asking the user for input
renv_scope_options(renv.verbose = TRUE)
repeat {
# solicit user's answer
selection <- if (default) "[Y/n]" else "[y/N]"
prompt <- sprintf("%s %s: ", question, selection)
response <- tryCatch(
tolower(trimws(readline(prompt))),
interrupt = identity
)
# check for interrupts; treat as abort request
cancel_if(inherits(response, "interrupt"))
# use default when no response
if (!nzchar(response))
return(default)
# check for 'yes' responses
if (response %in% c("y", "yes")) {
writef("")
return(TRUE)
}
# check for 'no' responses
if (response %in% c("n", "no")) {
writef("")
return(FALSE)
}
# ask the user again
writef("- Unrecognized response: please enter 'y' or 'n', or type Ctrl + C to cancel.")
}
}
proceed <- function(default = TRUE) {
ask("Do you want to proceed?", default = default)
}
menu <- function(choices, title, default = 1L) {
testing <- getOption("renv.menu.choice", integer())
if (length(testing)) {
selected <- testing[[1]]
options(renv.menu.choice = testing[-1])
} else if (testing()) {
selected <- default
} else {
selected <- NULL
}
if (!is.null(selected)) {
title <- paste(title, collapse = "\n")
body <- paste(sprintf("%i: %s", seq_along(choices), choices), collapse = "\n")
footer <- sprintf("Selection: %s\n", selected)
writef(paste(c(title, body, footer), collapse = "\n\n"))
return(names(choices)[selected])
}
if (!interactive()) {
value <- if (is.numeric(default)) names(choices)[default] else default
return(value)
}
idx <- tryCatch(
utils::menu(choices, paste(title, collapse = "\n"), graphics = FALSE),
interrupt = function(cnd) 0L
)
if (idx == 0L)
return("cancel")
names(choices)[idx]
}
# nocov end
insert <- function(contents,
pattern,
replacement,
anchor = NULL,
fixed = FALSE)
{
# first, check to see if the pattern matches a line
index <- grep(pattern, contents, perl = !fixed, fixed = fixed)
if (length(index)) {
contents[index] <- replacement
return(contents)
}
# otherwise, check for the anchor, and insert after
index <- if (!is.null(anchor))
grep(anchor, contents, perl = !fixed, fixed = fixed)
if (!length(index))
return(c(contents, replacement))
c(
head(contents, n = index),
replacement,
tail(contents, n = -index)
)
}
deparsed <- function(value, width = 60L) {
paste(deparse(value, width.cutoff = width), collapse = "\n")
}
read <- function(file) {
renv_scope_options(warn = -1L)
contents <- readLines(file, warn = FALSE)
paste(contents, collapse = "\n")
}
plural <- function(word, n) {
suffixes <- c("", "s")
indices <- as.integer(n != 1L) + 1L
paste0(word, suffixes[indices])
}
nplural <- function(word, n) {
paste(n, plural(word, n))
}
trunc <- function(text, n = 78) {
long <- nchar(text) > n
text[long] <- sprintf("%s <...>", substring(text[long], 1, n - 6))
text
}
endswith <- function(string, suffix) {
substring(string, nchar(string) - nchar(suffix) + 1) == suffix
}
# like tools::file_ext, but includes leading '.', and preserves
# '.tar.gz', '.tar.bz' and so on
fileext <- function(path, default = "") {
indices <- regexpr("[.]((?:tar[.])?[[:alnum:]]+)$", path, perl = TRUE)
ifelse(indices > -1L, substring(path, indices), default)
}
visited <- function(name, envir) {
value <- envir[[name]] %||% FALSE
envir[[name]] <- TRUE
value
}
rowapply <- function(X, FUN, ...) {
lapply(seq_len(NROW(X)), function(I) {
FUN(X[I, , drop = FALSE], ...)
})
}
comspec <- function() {
Sys.getenv("COMSPEC", unset = Sys.which("cmd.exe"))
}
nullfile <- function() {
if (renv_platform_windows()) "NUL" else "/dev/null"
}
quietly <- function(expr, sink = TRUE) {
if (sink) {
sink(file = nullfile())
defer(sink(NULL))
}
withCallingHandlers(
expr,
warning = function(c) invokeRestart("muffleWarning"),
message = function(c) invokeRestart("muffleMessage"),
packageStartupMessage = function(c) invokeRestart("muffleMessage")
)
}
# NOTE: This function can be used in preference to `as.*()` if you'd like
# to preserve attributes on the incoming object 'x'.
convert <- function(x, type) {
storage.mode(x) <- type
x
}
remap <- function(x, map) {
# TODO: use match?
remapped <- x
enumerate(map, function(key, val) {
remapped[remapped == key] <<- val
})
remapped
}
keep <- function(x, keys) {
x[intersect(keys, names(x))]
}
keep_if <- function(x, f) {
x[f(x)]
}
omit <- function(x, keys) {
x[setdiff(names(x), keys)]
}
omit_if <- function(x, f) {
x[!f(x)]
}
invoke <- function(callback, ...) {
callback(...)
}
resolve <- function(object) {
while (is.function(object))
object <- object()
object
}
dequote <- function(strings) {
for (quote in c("'", '"')) {
# find strings matching pattern
pattern <- paste0(quote, "(.*)", quote)
matches <- grep(pattern, strings, perl = TRUE)
if (empty(matches))
next
# remove outer quotes
strings[matches] <- gsub(pattern, "\\1", strings[matches], perl = TRUE)
# un-escape inner quotes
pattern <- paste0("\\", quote)
strings[matches] <- gsub(pattern, quote, strings[matches], fixed = TRUE)
}
strings
}
nth <- function(x, i) {
x[[i]]
}
find <- function(x, f, ...) {
for (i in seq_along(x))
if (!is.null(value <- f(x[[i]], ...)))
return(value)
}
recursing <- function() {
nf <- sys.nframe()
if (nf < 2L)
return(FALSE)
np <- sys.parent()
fn <- sys.function(np)
for (i in seq_len(np - 1L))
if (identical(fn, sys.function(i)))
return(TRUE)
FALSE
}
csort <- function(x, decreasing = FALSE, ...) {
renv_scope_locale("LC_COLLATE", "C")
sort(x, decreasing, ...)
}
fsub <- function(pattern, replacement, x, ignore.case = FALSE, useBytes = FALSE) {
sub(pattern, replacement, x, ignore.case = ignore.case, useBytes = useBytes, fixed = TRUE)
}
rows <- function(data, indices) {
# convert logical values
if (is.logical(indices)) {
if (length(indices) < nrow(data))
indices <- rep(indices, length.out = nrow(data))
indices <- which(indices, useNames = FALSE)
}
# build output list
output <- vector("list", length(data))
for (i in seq_along(data))
output[[i]] <- .subset2(data, i)[indices]
# copy relevant attributes
attrs <- attributes(data)
attrs[["row.names"]] <- .set_row_names(length(indices))
attributes(output) <- attrs
# return new data.frame
output
}
cols <- function(data, indices) {
# perform subset
output <- .subset(data, indices)
# copy relevant attributes
attrs <- attributes(data)
attrs[["names"]] <- attr(output, "names", exact = TRUE)
attributes(output) <- attrs
# return output
output
}
stringify <- function(object, collapse = " ") {
if (is.symbol(object))
return(as.character(object))
paste(
deparse(object, width.cutoff = 500L),
collapse = collapse
)
}
env <- function(...) {
list2env(list(...), envir = new.env(parent = emptyenv()))
}
env2list <- function(env) {
as.list.environment(env, all.names = TRUE)
}
chop <- function(x, split = "\n", fixed = TRUE, perl = FALSE, useBytes = FALSE) {
strsplit(x, split, !perl, perl, useBytes)[[1L]]
}
prof <- function(expr, ...) {
profile <- tempfile("renv-profile-", fileext = ".Rprof")
Rprof(profile, ...)
result <- expr
Rprof(NULL)
print(summaryRprof(profile))
invisible(result)
}
recycle <- function(data) {
# compute number of columns
n <- lengths(data, use.names = FALSE)
nrow <- max(n)
# start recycling
for (i in seq_along(data)) {
if (n[[i]] == 0L) {
length(data[[i]]) <- nrow
} else if (n[[i]] != nrow) {
data[[i]] <- rep.int(data[[i]], nrow / n[[i]])
}
}
data
}
take <- function(data, index = NULL) {
if (is.null(index)) data else .subset2(data, index)
}
cancel <- function() {
renv_snapshot_auto_suppress_next()
if (testing())
stop("Operation canceled", call. = FALSE)
message("- Operation canceled.")
invokeRestart("abort")
}
cancel_if <- function(cnd) {
if (cnd) cancel()
}
rep_named <- function(names, x) {
values <- rep_len(x, length(names))
names(values) <- names
values
}
wait_until <- function(callback, ...) {
repeat if (callback(...)) return(TRUE)
}
timer <- function(units = "secs") {
.time <- Sys.time()
.units <- units
list(
now = function() {
Sys.time()
},
elapsed = function() {
difftime(Sys.time(), .time, units = .units)
}
)
}
summon <- function() {
envir <- do.call(attach, list(what = NULL, name = "renv"))
renv <- renv_envir_self()
list2env(as.list(renv), envir = envir)
}
assert <- function(...) stopifnot(...)
overlay <- function(lhs, rhs) {
modifyList(as.list(lhs), as.list(rhs))
}
# the 'top' renv function in the call stack
topfun <- function() {
self <- renv_envir_self()
frames <- sys.frames()
for (i in seq_along(frames))
if (identical(self, parent.env(frames[[i]])))
return(sys.function(i))
}
warnify <- function(cnd) {
class(cnd) <- c("warning", "condition")
warning(cnd)
}
renv/R/actions.R 0000644 0001762 0000144 00000006446 14407411110 013213 0 ustar ligges users
actions <- function(action = c("snapshot", "restore"),
...,
project = NULL,
library = NULL,
lockfile = NULL,
type = settings$snapshot.type(project = project),
clean = FALSE)
{
action <- match.arg(action)
project <- renv_project_resolve(project)
lockfile <- lockfile %||% renv_lockfile_path(project = project)
renv_project_lock(project = project)
switch(
action,
snapshot = renv_actions_snapshot(project, library, lockfile, type),
restore = renv_actions_restore(project, library, lockfile, clean)
)
}
renv_actions_merge <- function(snap, lock, diff) {
fields <- c("Package", "Version", "Source")
defaults <- data.frame(
"Package" = character(),
"Library Version" = character(),
"Library Source" = character(),
"Lockfile Version" = character(),
"Lockfile Source" = character(),
check.names = FALSE,
stringsAsFactors = FALSE
)
lhs <- bapply(unname(renv_lockfile_records(snap)), `[`, fields)
if (length(lhs))
names(lhs) <- c("Package", paste("Library", names(lhs)[-1L]))
rhs <- bapply(unname(renv_lockfile_records(lock)), `[`, fields)
if (length(rhs))
names(rhs) <- c("Package", paste("Lockfile", names(rhs)[-1L]))
merged <- if (length(lhs) && length(rhs))
merge(lhs, rhs, by = "Package", all = TRUE)
else if (length(lhs))
lhs
else if (length(rhs))
rhs
else
defaults
actions <- data.frame(Package = names(diff),
Action = as.character(diff),
check.names = FALSE,
stringsAsFactors = FALSE)
all <- merge(merged, actions, by = "Package")
missing <- setdiff(names(defaults), names(all))
all[missing] <- NA_character_
all
}
renv_actions_snapshot <- function(project, library, lockfile, type) {
lock <- renv_lockfile_load(project = project)
snap <- snapshot(project = project,
library = library,
lockfile = NULL,
type = type)
diff <- renv_lockfile_diff_packages(lock, snap)
renv_actions_merge(snap, lock, diff)
}
renv_actions_restore <- function(project, library, lockfile, clean) {
# NOTE: we use a simple snapshot here as we just want to know the
# difference in library state before and after applying the lockfile;
# that is, we want to know what the library looks like without any
# filtering of what records would be reported from the library
lock <- renv_lockfile_load(project = project)
snap <- snapshot(project = project,
library = library,
lockfile = NULL,
type = "all")
diff <- renv_lockfile_diff_packages(snap, lock)
actions <- renv_actions_merge(snap, lock, diff)
renv_actions_restore_clean(actions, clean, project)
}
renv_actions_restore_clean <- function(actions, clean, project) {
# if not cleaning, then we don't do any removals
if (!clean) {
filtered <- actions[actions$Action != "remove", ]
return(filtered)
}
# otherwise, only process removals in the project library
projlib <- renv_paths_library(project = project)
locations <- renv_package_find(actions$Package)
keep <- actions$Action != "remove" | dirname(locations) == projlib
actions[keep, ]
}
renv/R/parse.R 0000644 0001762 0000144 00000002740 14432032552 012665 0 ustar ligges users
renv_parse_file <- function(file = "", ...) {
if (nzchar(file)) {
renv_scope_options(warn = -1L)
text <- readLines(file, warn = FALSE, encoding = "UTF-8")
renv_parse_impl(text, srcfile = file, ...)
}
}
renv_parse_text <- function(text = NULL, ...) {
if (is.character(text)) {
renv_parse_impl(text, ...)
}
}
renv_parse_impl <- function(text, ...) {
# save default encoding
enc <- Encoding(text)
# disable warnings + encoding conversions
renv_scope_options(
warn = 1L,
encoding = "native.enc"
)
# attempt multiple parse methods
methods <- list(
renv_parse_impl_asis,
renv_parse_impl_native,
renv_parse_impl_utf8
)
# attempt with different guessed encodings
encodings <- c("UTF-8", "unknown")
for (encoding in encodings) {
Encoding(text) <- encoding
for (method in methods) {
parsed <- catch(method(text, ...))
if (!inherits(parsed, "error"))
return(parsed)
}
}
# if these all fail, then just try the default
# parse and let the error propagate
defer(Sys.setlocale())
Encoding(text) <- enc
parse(text = text, ...)
}
renv_parse_impl_asis <- function(text, ...) {
defer(Sys.setlocale())
parse(text = text, ...)
}
renv_parse_impl_native <- function(text, ...) {
defer(Sys.setlocale())
parse(text = enc2native(text), encoding = "unknown", ...)
}
renv_parse_impl_utf8 <- function(text, ...) {
defer(Sys.setlocale())
parse(text = enc2utf8(text), encoding = "UTF-8", ...)
}
renv/R/zzz.R 0000644 0001762 0000144 00000014656 14600720433 012420 0 ustar ligges users
.onLoad <- function(libname, pkgname) {
renv_zzz_load()
}
.onAttach <- function(libname, pkgname) {
renv_zzz_attach()
}
.onUnload <- function(libpath) {
renv_lock_unload()
renv_task_unload()
renv_watchdog_unload()
# do some extra cleanup when running R CMD check
if (renv_platform_unix() && checking() && !ci())
cleanse()
# flush the help db to avoid errors on reload
# https://github.com/rstudio/renv/issues/1294
helpdb <- system.file(package = "renv", "help/renv.rdb")
.Internal <- .Internal
lazyLoadDBflush <- function(...) {}
tryCatch(
.Internal(lazyLoadDBflush(helpdb)),
error = function(e) NULL
)
}
# NOTE: required for devtools::load_all()
.onDetach <- function(libpath) {
package <- Sys.getenv("DEVTOOLS_LOAD", unset = NA)
if (identical(package, .packageName))
.onUnload(libpath)
}
renv_zzz_load <- function() {
# NOTE: needs to be visible to embedded instances of renv as well
the$envir_self <<- renv_envir_self()
# make sure renv (and packages using renv!!!) use tempdir for storage
# when running tests, or R CMD check
if (checking() || testing()) {
# set root directory
root <- Sys.getenv("RENV_PATHS_ROOT", unset = tempfile("renv-root-"))
Sys.setenv(RENV_PATHS_ROOT = root)
# set up sandbox -- only done on non-Windows due to strange intermittent
# test failures that seemed to occur there?
if (renv_platform_unix()) {
sandbox <- Sys.getenv("RENV_PATHS_SANDBOX", unset = tempfile("renv-sandbox-"))
Sys.setenv(RENV_PATHS_SANDBOX = sandbox)
}
# don't lock sandbox while testing / checking
options(renv.sandbox.locking_enabled = FALSE)
}
renv_defer_init()
renv_metadata_init()
renv_platform_init()
renv_virtualization_init()
renv_envvars_init()
renv_log_init()
renv_methods_init()
renv_cache_init()
renv_libpaths_init()
renv_patch_init()
renv_sandbox_init()
renv_sdkroot_init()
renv_watchdog_init()
if (!renv_metadata_embedded()) {
# TODO: It's not clear if these callbacks are safe to use when renv is
# embedded, but it's unlikely that clients would want them anyhow.
renv_task_create(renv_sandbox_task)
renv_task_create(renv_snapshot_task)
}
# if an renv project already appears to be loaded, then re-activate
# the sandbox now -- this is primarily done to support suspend and
# resume with RStudio where the user profile might not be run
if (renv_rstudio_available()) {
project <- getOption("renv.project.path")
if (!is.null(project))
renv_sandbox_activate(project = project)
}
# make sure renv is unloaded on exit, so locks etc. are released
# we previously tried to orchestrate this via unloadNamespace(),
# but this fails when a package importing renv is already loaded
# https://github.com/rstudio/renv/issues/1621
reg.finalizer(renv_envir_self(), renv_unload_finalizer, onexit = TRUE)
}
renv_zzz_attach <- function() {
renv_rstudio_fixup()
}
renv_zzz_run <- function() {
# check if we're in pkgload::load_all()
# if so, then create some files
if (renv_envvar_exists("DEVTOOLS_LOAD")) {
renv_zzz_bootstrap_activate()
renv_zzz_bootstrap_config()
}
# check if we're running as part of R CMD build
# if so, build our local repository with a copy of ourselves
if (building())
renv_zzz_repos()
}
renv_zzz_bootstrap_activate <- function() {
source <- "templates/template-activate.R"
target <- "inst/resources/activate.R"
scripts <- c("R/bootstrap.R", "R/json-read.R")
# Do we need an update
source_mtime <- max(renv_file_info(c(source, scripts))$mtime)
target_mtime <- renv_file_info(target)$mtime
if (!is.na(target_mtime) && target_mtime > source_mtime)
return()
# read the necessary bootstrap scripts
contents <- map(scripts, readLines)
bootstrap <- unlist(contents)
# format nicely for insertion
bootstrap <- paste(" ", bootstrap)
bootstrap <- paste(bootstrap, collapse = "\n")
# replace template with bootstrap code
template <- renv_file_read(source)
replaced <- renv_template_replace(template, list(BOOTSTRAP = bootstrap))
# write to resources
printf("- Generating 'inst/resources/activate.R' ... ")
writeLines(replaced, con = target)
writef("Done!")
}
renv_zzz_bootstrap_config <- function() {
source <- "inst/config.yml"
target <- "R/config-defaults.R"
source_mtime <- renv_file_info(source)$mtime
target_mtime <- renv_file_info(target)$mtime
if (target_mtime > source_mtime)
return()
template <- renv_template_create(heredoc(leave = 2, '
${NAME} = function(..., default = ${DEFAULT}) {
renv_config_get(
name = "${NAME}",
type = "${TYPE}",
default = default,
args = list(...)
)
}
'))
template <- gsub("^\\n+|\\n+$", "", template)
generate <- function(entry) {
name <- entry$name
type <- entry$type
default <- entry$default
code <- entry$code
default <- if (length(code)) trimws(code) else deparse(default)
replacements <- list(
NAME = name,
TYPE = type,
DEFAULT = default
)
renv_template_replace(template, replacements)
}
config <- yaml::read_yaml("inst/config.yml")
code <- map_chr(config, generate)
all <- c(
"",
"# Auto-generated by renv_zzz_bootstrap_config()",
"",
"#' @rdname config",
"#' @export",
"#' @format NULL",
"config <- list(",
"",
paste(code, collapse = ",\n\n"),
"",
")"
)
printf("- Generating 'R/config-defaults.R' ... ")
writeLines(all, con = target)
writef("Done!")
}
renv_zzz_repos <- function() {
# don't run if we're running tests
if (checking())
return()
# prevent recursion
installing <- Sys.getenv("RENV_INSTALLING_REPOS", unset = NA)
if (!is.na(installing))
return()
renv_scope_envvars(RENV_INSTALLING_REPOS = "TRUE")
writeLines("** installing renv to package-local repository")
# get package directory
pkgdir <- getwd()
# move to build directory
tdir <- tempfile("renv-build-")
ensure_directory(tdir)
renv_scope_wd(tdir)
# build renv again
r_cmd_build("renv", path = pkgdir, "--no-build-vignettes")
# copy built tarball to inst folder
src <- list.files(tdir, full.names = TRUE)
tgt <- file.path(pkgdir, "inst/repos/src/contrib")
ensure_directory(tgt)
file.copy(src, tgt)
# write PACKAGES
renv_scope_envvars(R_DEFAULT_SERIALIZE_VERSION = "2")
write_PACKAGES(tgt, type = "source")
}
if (identical(.packageName, "renv")) {
renv_zzz_run()
}
renv/R/watchdog-server.R 0000644 0001762 0000144 00000006126 14547051446 014673 0 ustar ligges users
renv_watchdog_server_start <- function(client) {
# silence warnings
renv_scope_options(warn = -1L)
# initialize logging
renv_log_init()
# create socket server
server <- renv_socket_server()
dlog("watchdog-server", "Listening on port %i.", server$port)
# communicate information back to client
dlog("watchdog-server", "Waiting for client...")
metadata <- list(port = server$port, pid = server$pid)
conn <- renv_socket_connect(port = client$port, open = "wb")
defer(close(conn))
serialize(metadata, connection = conn)
dlog("watchdog-server", "Synchronized with client.")
# initialize locks
lockenv <- new.env(parent = emptyenv())
# start listening for connections
repeat tryCatch(
renv_watchdog_server_run(server, client, lockenv),
error = function(e) {
dlog("watchdog-server", "Error: %s", conditionMessage(e))
}
)
}
renv_watchdog_server_run <- function(server, client, lockenv) {
# check for parent exit
if (!renv_process_exists(client$pid)) {
dlog("watchdog-server", "Client process has exited; shutting down.")
renv_watchdog_server_exit(server, client, lockenv)
}
# set file time on owned locks, so we can see they're not orphaned
dlog("watchdog-server", "Refreshing lock times.")
locks <- ls(envir = lockenv, all.names = TRUE)
renv_lock_refresh(locks)
# wait for connection
dlog("watchdog-server", "Waiting for connection...")
conn <- renv_socket_accept(server$socket, open = "rb", timeout = 1)
defer(close(conn))
# read the request
dlog("watchdog-server", "Received connection; reading data.")
request <- unserialize(conn)
dlog("watchdog-server", "Received request.")
str(request)
# handle the request
renv_watchdog_server_run_impl(server, client, lockenv, request)
}
renv_watchdog_server_run_impl <- function(server, client, lockenv, request) {
switch(
request$method %||% "",
ListLocks = {
dlog("watchdog-server", "Executing 'ListLocks' request.")
conn <- renv_socket_connect(port = request$port, open = "wb")
defer(close(conn))
locks <- ls(envir = lockenv, all.names = TRUE)
serialize(locks, connection = conn)
},
LockAcquired = {
dlog("watchdog-server", "Acquired lock on path '%s'.", request$data$path)
assign(request$data$path, TRUE, envir = lockenv)
},
LockReleased = {
dlog("watchdog-server", "Released lock on path '%s'.", request$data$path)
rm(list = request$data$path, envir = lockenv)
},
Shutdown = {
dlog("watchdog-server", "Received shutdown request; shutting down.")
renv_watchdog_server_exit(server, client, lockenv)
},
"" = {
dlog("watchdog-server", "Received request with no method field available.")
},
{
dlog("watchdog-server", "Unknown method '%s'", request$method)
}
)
}
renv_watchdog_server_exit <- function(server, client, lockenv) {
# remove any existing locks
locks <- ls(envir = lockenv, all.names = TRUE)
unlink(locks, recursive = TRUE, force = TRUE)
# shut down the socket server
close(server$socket)
# quit
quit(status = 0)
}
renv/R/vector.R 0000644 0001762 0000144 00000000406 14464550375 013067 0 ustar ligges users
# these functions are like the base R equivalents, but preserve names
renv_vector_diff <- function(x, y) {
x[match(x, y, 0L) == 0L]
}
renv_vector_intersect <- function(x, y) {
y[match(x, y, 0L)]
}
renv_vector_unique <- function(x) {
x[!duplicated(x)]
}
renv/R/install.R 0000644 0001762 0000144 00000063127 14573636546 013252 0 ustar ligges users
# an explicitly-requested package type in a call to 'install()'
the$install_pkg_type <- NULL
# an explicitly-requested dependencies field in a call to 'install()'
the$install_dependency_fields <- NULL
# the formatted width of installation steps printed to the console
the$install_step_width <- 48L
#' Install packages
#'
#' @description
#' Install one or more \R packages, from a variety of remote sources.
#' `install()` uses the same machinery as [restore()] (i.e. it uses cached
#' packages where possible) but it does not respect the lockfile, instead
#' installing the latest versions available from CRAN.
#'
#' See `vignette("package-install")` for more details.
#'
#' # `Remotes`
#'
#' `install()` (called without arguments) will respect the `Remotes` field
#' of the `DESCRIPTION` file (if present). This allows you to specify places
#' to install a package other than the latest version from CRAN.
#' See for details.
#'
#' # Bioconductor
#'
#' Packages from Bioconductor can be installed by using the `bioc::` prefix.
#' For example,
#'
#' ```
#' renv::install("bioc::Biobase")
#' ```
#'
#' will install the latest-available version of Biobase from Bioconductor.
#'
#' renv depends on BiocManager (or, for older versions of \R, BiocInstaller)
#' for the installation of packages from Bioconductor. If these packages are
#' not available, renv will attempt to automatically install them before
#' fulfilling the installation request.
#'
#' @inherit renv-params
#'
#' @param packages Either `NULL` (the default) to install all packages required
#' by the project, or a character vector of packages to install. renv
#' supports a subset of the remotes syntax used for package installation,
#' e.g:
#'
#' * `pkg`: install latest version of `pkg` from CRAN.
#' * `pkg@version`: install specified version of `pkg` from CRAN.
#' * `username/repo`: install package from GitHub
#' * `bioc::pkg`: install `pkg` from Bioconductor.
#'
#' See and the examples
#' below for more details.
#'
#' renv deviates from the remotes spec in one important way: subdirectories
#' are separated from the main repository specification with a `:`, not `/`.
#' So to install from the `subdir` subdirectory of GitHub package
#' `username/repo` you'd use `"username/repo:subdir`.
#'
#' @param exclude Packages which should not be installed. `exclude` is useful
#' when using `renv::install()` to install all dependencies in a project,
#' except for a specific set of packages.
#'
#' @param verbose Boolean; report output from `R CMD build` and `R CMD INSTALL`
#' during installation? When `NULL` (the default), the value of `config$install.verbose()`
#' will be used. When `FALSE`, installation output will be emitted only if
#' a package fails to install.
#'
#' @param lock Boolean; update the `renv.lock` lockfile after the successful
#' installation of the requested packages?
#'
#' @return A named list of package records which were installed by renv.
#'
#' @export
#'
#' @examples
#' \dontrun{
#'
#' # install the latest version of 'digest'
#' renv::install("digest")
#'
#' # install an old version of 'digest' (using archives)
#' renv::install("digest@@0.6.18")
#'
#' # install 'digest' from GitHub (latest dev. version)
#' renv::install("eddelbuettel/digest")
#'
#' # install a package from GitHub, using specific commit
#' renv::install("eddelbuettel/digest@@df55b00bff33e945246eff2586717452e635032f")
#'
#' # install a package from Bioconductor
#' # (note: requires the BiocManager package)
#' renv::install("bioc::Biobase")
#'
#' # install a package, specifying path explicitly
#' renv::install("~/path/to/package")
#'
#' # install packages as declared in the project DESCRIPTION file
#' renv::install()
#'
#' }
install <- function(packages = NULL,
...,
exclude = NULL,
library = NULL,
type = NULL,
rebuild = FALSE,
repos = NULL,
prompt = interactive(),
dependencies = NULL,
verbose = NULL,
lock = FALSE,
project = NULL)
{
renv_consent_check()
renv_scope_error_handler()
# allow user to provide additional package names as part of '...'
if (!missing(...)) {
dots <- list(...)
names(dots) <- names(dots) %||% rep.int("", length(dots))
packages <- c(packages, dots[!nzchar(names(dots))])
}
project <- renv_project_resolve(project)
renv_project_lock(project = project)
renv_scope_verbose_if(prompt)
# handle 'dependencies'
if (!is.null(dependencies)) {
fields <- renv_description_dependency_fields(dependencies, project = project)
renv_scope_binding(the, "install_dependency_fields", fields)
}
# handle 'verbose'
verbose <- verbose %||% config$install.verbose()
renv_scope_options(renv.config.install.verbose = verbose)
# set up library paths
libpaths <- renv_libpaths_resolve(library)
renv_scope_libpaths(libpaths)
# check for explicitly-provided type -- we handle this specially for PPM
if (!is.null(type)) {
renv_scope_binding(the, "install_pkg_type", type)
renv_scope_options(pkgType = type)
}
# override repositories if requested
repos <- repos %||% config$repos.override()
if (length(repos))
renv_scope_options(repos = repos)
# if users have requested the use of pak, delegate there
if (config$pak.enabled() && !recursing()) {
renv_pak_init()
return(renv_pak_install(packages, libpaths, project))
}
# resolve remotes from explicitly-requested packages
remotes <- if (length(packages)) {
remotes <- map(packages, renv_remotes_resolve)
names(remotes) <- map_chr(remotes, `[[`, "Package")
remotes
}
# figure out which packages we should install
packages <- names(remotes) %||% renv_snapshot_dependencies(project, dev = TRUE)
# apply exclude parameter
if (length(exclude))
packages <- setdiff(packages, exclude)
if (empty(packages)) {
writef("- There are no packages to install.")
return(invisible(list()))
}
# add bioconductor packages if necessary
if (renv_bioconductor_required(remotes)) {
bioc <- c(renv_bioconductor_manager(), "BiocVersion")
packages <- unique(c(packages, bioc))
}
# don't update renv unless it was explicitly requested
if (!"renv" %in% names(remotes))
packages <- setdiff(packages, "renv")
# start building a list of records; they should be resolved this priority:
#
# 1. explicit requests from the user
# 2. remotes declarations from the DESCRIPTION file
# 3. existing version in library, if any
# 4. fallback to package repositories
#
# we overlay 1 and 2 here, and then do 3 and 4 dynamically if required
# during the retrieve + install stages
records <- overlay(renv_project_remotes(project), remotes)
# run install preflight checks
if (!renv_install_preflight(project, libpaths, records))
cancel_if(prompt && !proceed())
# we're now ready to start installation
renv_scope_restore(
project = project,
library = renv_libpaths_active(),
packages = names(remotes),
records = records,
rebuild = rebuild
)
# retrieve packages
records <- retrieve(packages)
if (empty(records)) {
writef("- There are no packages to install.")
return(invisible(list()))
}
if (prompt || renv_verbose()) {
renv_install_report(records, library = renv_libpaths_active())
cancel_if(prompt && !proceed())
}
# install retrieved records
before <- Sys.time()
renv_install_impl(records)
after <- Sys.time()
time <- renv_difftime_format(difftime(after, before))
n <- length(records)
writef("Successfully installed %s in %s.", nplural("package", n), time)
# check loaded packages and inform user if out-of-sync
renv_install_postamble(names(records))
# update lockfile if requested
if (lock && length(records)) {
# avoid next automatic snapshot
renv_snapshot_auto_suppress_next()
# re-compute the records, to ensure they're normalized in the same
# way as they might be in snapshot()
# https://github.com/rstudio/renv/issues/1828
updates <- renv_lockfile_create(
project = project,
libpaths = libpaths,
packages = names(records),
exclude = exclude,
prompt = FALSE,
force = TRUE
)
# overlay these records onto the existing lockfile
lockfile <- renv_lockfile_load(project = project)
lockfile <- renv_lockfile_modify(lockfile, renv_lockfile_records(updates))
renv_lockfile_save(lockfile, project = project)
}
invisible(records)
}
renv_install_impl <- function(records) {
staged <- renv_config_install_staged()
writef(header("Installing packages"))
if (staged)
renv_install_staged(records)
else
renv_install_default(records)
invisible(TRUE)
}
renv_install_staged <- function(records) {
# get current libpaths
libpaths <- renv_libpaths_all()
# set up a dummy library path for installation
templib <- renv_install_staged_library_path()
defer(unlink(templib, recursive = TRUE))
renv_scope_libpaths(c(templib, libpaths))
# perform the install
renv_install_default(records)
# migrate packages into true library
library <- nth(libpaths, 1L)
sources <- list.files(templib, full.names = TRUE)
targets <- file.path(library, basename(sources))
names(targets) <- sources
enumerate(targets, renv_file_move, overwrite = TRUE)
# clear filebacked cache entries
descpaths <- file.path(targets, "DESCRIPTION")
renv_filebacked_clear("renv_description_read", descpaths)
renv_filebacked_clear("renv_hash_description", descpaths)
invisible(targets)
}
renv_install_staged_library_path_impl <- function() {
# get current library path
libpath <- renv_libpaths_active()
# retrieve current project, library path
stagedlib <- local({
# allow user configuration of staged library location
override <- Sys.getenv("RENV_PATHS_LIBRARY_STAGING", unset = NA)
if (!is.na(override))
return(override)
# if we have an active project, use that path
project <- renv_project_get(default = NULL)
if (!is.null(project))
return(renv_paths_renv("staging", project = project))
# otherwise, stage within library path
file.path(libpath, ".renv")
})
# attempt to create it
ok <- catch(ensure_directory(stagedlib))
if (inherits(ok, "error"))
return(tempfile("renv-staging-"))
# resolve a unique staging directory in this path
# we want to keep paths short just in case; it's easy to blow up the
# path length limit (hence we don't use tempfile below)
for (i in 1:100) {
path <- file.path(stagedlib, i)
if (dir.create(path, showWarnings = FALSE))
return(path)
}
# all else fails, use tempfile
tempfile("renv-staging-")
}
# NOTE: on Windows, installing packages into very long paths
# can fail, as R's internal unzip utility does not handle
# long Windows paths well. in addition, an renv project's
# library path tends to be long, exasperating the issue.
# for that reason, we try to use a shorter staging directory
#
# part of the challenge here is that the R temporary directory
# and R library path might reside on different mounts, and so
# we may want to try and avoid installing on one mount and then
# copying to another mount (as that could be slow).
#
# note that using the renv folder might be counter-productive,
# since users will want to use renv in projects sync'ed via
# OneDrive and friends, and we don't want those to lock files
# in the staging directory
renv_install_staged_library_path <- function() {
# compute path
path <- renv_install_staged_library_path_impl()
# create library directory
ensure_directory(path)
# try to make sure it has the same permissions as the library itself
if (!renv_platform_windows()) {
libpath <- renv_libpaths_active()
umask <- Sys.umask("0")
defer(Sys.umask(umask))
info <- renv_file_info(libpath)
Sys.chmod(path, info$mode)
}
# return the created path
return(path)
}
renv_install_default <- function(records) {
state <- renv_restore_state()
handler <- state$handler
for (record in records) {
package <- record$Package
handler(package, renv_install_package(record))
}
}
renv_install_package <- function(record) {
# get active project (if any)
state <- renv_restore_state()
project <- state$project
# figure out whether we can use the cache during install
# use library path recorded in restore state as staged installs will have
# mutated the library path, placing a staging library at the front
library <- renv_restore_state("library")
linkable <- renv_cache_linkable(project = project, library = library)
linker <- if (linkable) renv_file_link else renv_file_copy
cacheable <-
renv_cache_config_enabled(project = project) &&
renv_record_cacheable(record) &&
!renv_restore_rebuild_required(record)
if (cacheable) {
# check for cache entry and install if there
path <- renv_cache_find(record)
if (renv_cache_package_validate(path))
return(renv_install_package_cache(record, path, linker))
}
# install the package
before <- Sys.time()
withCallingHandlers(
renv_install_package_impl(record),
error = function(e) writef("FAILED")
)
after <- Sys.time()
path <- record$Path
type <- renv_package_type(path, quiet = TRUE)
feedback <- renv_install_package_feedback(path, type)
# link into cache
if (renv_cache_config_enabled(project = project)) {
renv_cache_synchronize(record, linkable = linkable)
feedback <- paste0(feedback, " and cached")
}
verbose <- config$install.verbose()
elapsed <- difftime(after, before, units = "auto")
renv_install_step_ok(feedback, elapsed = elapsed, verbose = verbose)
invisible()
}
renv_install_package_feedback <- function(path, type) {
if (identical(type, "source"))
return("built from source")
if (renv_file_type(path, symlinks = FALSE) == "directory")
return("copied local binary")
"installed binary"
}
renv_install_package_cache <- function(record, cache, linker) {
if (renv_install_package_cache_skip(record, cache))
return(TRUE)
library <- renv_libpaths_active()
target <- file.path(library, record$Package)
# back up the previous installation if needed
callback <- renv_file_backup(target)
defer(callback())
# report successful link to user
renv_install_step_start("Installing", record$Package, verbose = FALSE)
before <- Sys.time()
linker(cache, target)
after <- Sys.time()
type <- case(
identical(linker, renv_file_copy) ~ "copied from cache",
identical(linker, renv_file_link) ~ "linked from cache"
)
elapsed <- difftime(after, before, units = "auto")
renv_install_step_ok(type, elapsed = elapsed)
return(TRUE)
}
renv_install_package_cache_skip <- function(record, cache) {
# don't skip if installation was explicitly requested
if (record$Package %in% renv_restore_state("packages"))
return(FALSE)
# check for matching cache + target paths
library <- renv_restore_state("library") %||% renv_libpaths_active()
target <- file.path(library, record$Package)
renv_file_same(cache, target)
}
renv_install_package_impl_prebuild <- function(record, path, quiet) {
# check whether user wants us to build before install
if (!identical(config$install.build(), TRUE))
return(path)
# if this package already appears to be built, nothing to do
if (renv_package_built(path))
return(path)
# if this is an archive, we'll need to unpack it first
info <- renv_file_info(path)
if (identical(info$isdir, FALSE)) {
# find the package directory
files <- renv_archive_list(path)
descpath <- grep("(?:^|/)DESCRIPTION$", files, value = TRUE)
pkgpath <- dirname(descpath)[nchar(descpath) == min(nchar(descpath))]
# extract to temporary directory
exdir <- tempfile("renv-build-")
ensure_directory(exdir)
renv_archive_decompress(path, exdir = exdir)
# update path to package
path <- file.path(exdir, pkgpath)
# and ensure we build in this directory
renv_scope_wd(path)
}
# if this package depends on a VignetteBuilder that is not installed,
# then we can't proceed
descpath <- file.path(path, "DESCRIPTION")
desc <- renv_description_read(descpath)
builder <- desc[["VignetteBuilder"]]
if (!is.null(builder) && !renv_package_installed(builder)) {
fmt <- "Skipping package build: vignette builder '%s' is not installed"
writef(fmt, builder)
return(path)
}
verbose <- config$install.verbose()
renv_install_step_start("Building", record$Package, verbose = verbose)
before <- Sys.time()
package <- record$Package
newpath <- r_cmd_build(package, path)
after <- Sys.time()
elapsed <- difftime(after, before, units = "auto")
renv_install_step_ok("from source", elapsed = elapsed)
newpath
}
renv_install_package_impl <- function(record, quiet = TRUE) {
package <- record$Package
# get path for package
path <- record$Path
# check if it's an archive (versus an unpacked directory)
info <- renv_file_info(path)
isarchive <- identical(info$isdir, FALSE)
subdir <- record$RemoteSubdir %||% ""
if (isarchive) {
# re-pack archives if they appear to have their package
# sources contained as part of a sub-directory
path <- renv_package_unpack(package, path, subdir = subdir)
} else if (nzchar(subdir)) {
# for directories, we may need to use subdir to find the package path
components <- c(path, subdir)
path <- paste(components, collapse = "/")
}
# check whether we should build before install
path <- renv_install_package_impl_prebuild(record, path, quiet)
# report start of installation to user
verbose <- config$install.verbose()
renv_install_step_start("Installing", record$Package, verbose = verbose)
# run user-defined hooks before, after install
options <- renv_install_package_options(package)
before <- options$before.install %||% identity
after <- options$after.install %||% identity
before(package)
defer(after(package))
# backup an existing installation of the package if it exists
library <- renv_libpaths_active()
destination <- file.path(library, package)
callback <- renv_file_backup(destination)
defer(callback())
# normalize paths
path <- renv_path_normalize(path, mustWork = TRUE)
# get library path
library <- renv_libpaths_active()
# if a package already exists at that path, back it up first
# this avoids problems with older versions of R attempting to
# overwrite a pre-existing symlink
#
# https://github.com/rstudio/renv/issues/611
installpath <- file.path(library, package)
callback <- renv_file_backup(installpath)
defer(callback())
# if this failed for some reason, just remove it
if (renv_file_broken(installpath))
renv_file_remove(installpath)
# if this is the path to an unpacked binary archive,
# we can just copy the folder over
isdir <- renv_file_type(path, symlinks = FALSE) == "directory"
isbin <- renv_package_type(path, quiet = TRUE) == "binary"
copyable <- isdir && isbin
# shortcut via copying a binary directory if possible,
# otherwise, install the package
if (copyable)
renv_file_copy(path, installpath, overwrite = TRUE)
else
r_cmd_install(package, path)
# if we just installed a binary package, check that it can be loaded
# (source packages are checked by default on install)
withCallingHandlers(
if (isbin) renv_install_test(package),
error = function(err) unlink(installpath, recursive = TRUE)
)
# augment package metadata after install
renv_package_augment(installpath, record)
# return the path to the package
invisible(installpath)
}
renv_install_test <- function(package) {
# add escape hatch, just in case
# (test binaries by default on Linux, but not Windows or macOS)
enabled <- Sys.getenv("RENV_INSTALL_TEST_LOAD", unset = renv_platform_linux())
if (!truthy(enabled))
return(TRUE)
# check whether we should skip installation testing
opts <- r_cmd_install_option(package, c("install.opts", "INSTALL_opts"), FALSE)
if (is.character(opts)) {
flags <- unlist(strsplit(opts, "\\s+", perl = TRUE))
if ("--no-test-load" %in% flags)
return(TRUE)
}
# make sure we use the current library paths in the launched process
rlibs <- paste(renv_libpaths_all(), collapse = .Platform$path.sep)
renv_scope_envvars(R_LIBS = rlibs, R_LIBS_USER = "NULL", R_LIBS_SITE = "NULL")
# also hide from user .Renviron files
# https://github.com/wch/r-source/blob/1c0a2dc8ce6c05f68e1959ffbe6318a309277df3/src/library/tools/R/check.R#L273-L276
renv_scope_envvars(R_ENVIRON_USER = "NULL")
# make sure R_TESTS is unset here, just in case
# https://github.com/wch/r-source/blob/1c0a2dc8ce6c05f68e1959ffbe6318a309277df3/src/library/tools/R/install.R#L76-L79
renv_scope_envvars(R_TESTS = NULL)
# the actual code we'll run in the other process
# we use 'loadNamespace()' rather than 'library()' because some packages might
# intentionally throw an error in their .onAttach() hooks
# https://github.com/rstudio/renv/issues/1611
code <- expr({
options(warn = 1L)
loadNamespace(!!package)
})
# write it to a tempfile
script <- renv_scope_tempfile("renv-install-", fileext = ".R")
writeLines(deparse(code), con = script)
# check that the package can be loaded in a separate process
renv_system_exec(
command = R(),
args = c("--vanilla", "-s", "-f", renv_shell_path(script)),
action = sprintf("testing if '%s' can be loaded", package)
)
# return TRUE to indicate successful validation
TRUE
}
renv_install_package_options <- function(package) {
options <- getOption("renv.install.package.options")
options[[package]]
}
# nocov start
renv_install_preflight_requirements <- function(records) {
deps <- bapply(records, function(record) {
renv_dependencies_discover_description(record$Path)
}, index = "ParentPackage")
splat <- split(deps, deps$Package)
bad <- enumerate(splat, function(package, requirements) {
# skip NULL records (should be handled above)
record <- records[[package]]
if (is.null(record))
return(NULL)
version <- record$Version
# drop packages without explicit version requirement
requirements <- requirements[nzchar(requirements$Require), ]
if (nrow(requirements) == 0)
return(NULL)
# add in requested version
requirements$RequestedVersion <- version
# generate expressions to evaluate
fmt <- "package_version('%s') %s package_version('%s')"
code <- with(requirements, sprintf(fmt, RequestedVersion, Require, Version))
parsed <- parse(text = code)
ok <- map_lgl(parsed, eval, envir = baseenv())
# return requirements that weren't satisfied
requirements[!ok, ]
})
bad <- bind(unname(bad))
if (empty(bad))
return(TRUE)
package <- bad$ParentPackage
requires <- sprintf("%s (%s %s)", bad$Package, bad$Require, bad$Version)
actual <- sprintf("%s %s", bad$Package, bad$RequestedVersion)
fmt <- "Package '%s' requires '%s', but '%s' will be installed"
text <- sprintf(fmt, format(package), format(requires), format(actual))
if (renv_verbose()) {
caution_bullets(
"The following issues were discovered while preparing for installation:",
text,
"Installation of these packages may not succeed."
)
}
if (interactive() && !proceed())
return(FALSE)
TRUE
}
# nocov end
renv_install_postamble <- function(packages) {
# only diagnose packages currently loaded
packages <- renv_vector_intersect(packages, loadedNamespaces())
installed <- map_chr(packages, renv_package_version)
loaded <- map_chr(packages, renv_namespace_version)
caution_bullets(
c("", "The following loaded package(s) have been updated:"),
packages[installed != loaded],
"Restart your R session to use the new versions."
)
TRUE
}
renv_install_preflight_unknown_source <- function(records) {
renv_check_unknown_source(records)
}
renv_install_preflight_permissions <- function(library) {
# try creating and deleting a directory in the library folder
file <- renv_scope_tempfile(".renv-write-test-", tmpdir = library)
dir.create(file, recursive = TRUE, showWarnings = FALSE)
# check if we created the directory successfully
info <- renv_file_info(file)
if (identical(info$isdir, TRUE))
return(TRUE)
# nocov start
if (renv_verbose()) {
# construct header for message
preamble <- "renv appears to be unable to access the requested library path:"
# construct footer for message
info <- as.list(Sys.info())
fmt <- "Check that the '%s' user has read / write access to this directory."
postamble <- sprintf(fmt, info$effective_user %||% info$user)
# print it
caution_bullets(
preamble = preamble,
values = library,
postamble = postamble
)
}
# nocov end
FALSE
}
renv_install_preflight <- function(project, libpaths, records) {
library <- nth(libpaths, 1L)
records <- filter(records, Negate(is.function))
all(
renv_install_preflight_unknown_source(records),
renv_install_preflight_permissions(library)
)
}
renv_install_report <- function(records, library) {
renv_pretty_print_records(
"The following package(s) will be installed:",
records,
sprintf("These packages will be installed into %s.", renv_path_pretty(library))
)
}
renv_install_step_start <- function(action, package, verbose = FALSE) {
if (verbose)
return(writef("- %s %s ...", action, package))
message <- sprintf("- %s %s ... ", action, package)
printf(format(message, width = the$install_step_width))
}
renv_install_step_ok <- function(..., elapsed = NULL, verbose = FALSE) {
renv_report_ok(
message = paste(..., collapse = ""),
elapsed = elapsed,
verbose = verbose
)
}
renv/R/envvar.R 0000644 0001762 0000144 00000000650 14442343010 013045 0 ustar ligges users
renv_envvar_path_add <- function(envvar, value, prepend = TRUE) {
old <- Sys.getenv(envvar, unset = "")
old <- strsplit(old, .Platform$path.sep)[[1]]
parts <- if (prepend) union(value, old) else union(old, value)
new <- paste(parts, collapse = .Platform$path.sep)
names(new) <- envvar
do.call(Sys.setenv, as.list(new))
new
}
renv_envvar_exists <- function(key) {
!is.na(Sys.getenv(key, unset = NA))
}
renv/R/lock.R 0000644 0001762 0000144 00000005043 14547051446 012514 0 ustar ligges users
the$lock_registry <- new.env(parent = emptyenv())
renv_lock_acquire <- function(path) {
# normalize path
path <- renv_lock_path(path)
dlog("lock", "%s [acquiring lock]", renv_path_pretty(path))
# if we already have this lock, increment our counter
count <- the$lock_registry[[path]] %||% 0L
if (count > 0L) {
the$lock_registry[[path]] <- count + 1L
return(TRUE)
}
# make sure parent directory exists
ensure_parent_directory(path)
# suppress warnings in this scope
renv_scope_options(warn = -1L)
# loop until we acquire the lock
repeat tryCatch(
renv_lock_acquire_impl(path) && break,
error = function(cnd) Sys.sleep(0.2)
)
# mark this path as locked by us
the$lock_registry[[path]] <- 1L
# notify the watchdog
renv_watchdog_notify("LockAcquired", list(path = path))
# TRUE to mark successful lock
dlog("lock", "%s [lock acquired]", renv_path_pretty(path))
TRUE
}
# https://rcrowley.org/2010/01/06/things-unix-can-do-atomically.html
renv_lock_acquire_impl <- function(path) {
# check for orphaned locks
if (renv_lock_orphaned(path)) {
dlog("lock", "%s: removing orphaned lock", path)
unlink(path, recursive = TRUE, force = TRUE)
}
# attempt to create the lock
dir.create(path, mode = "0755", showWarnings = FALSE)
}
renv_lock_release <- function(path) {
# normalize path
path <- renv_lock_path(path)
# decrement our lock count
count <- the$lock_registry[[path]] <- the$lock_registry[[path]] - 1L
# remove the lock if we have no more locks
if (count == 0L) {
dlog("lock", "%s [lock released]", renv_path_pretty(path))
renv_lock_release_impl(path)
}
}
renv_lock_release_impl <- function(path) {
unlink(path, recursive = TRUE, force = TRUE)
remaining <- intersect(path, ls(envir = the$lock_registry, all.names = TRUE))
rm(list = remaining, envir = the$lock_registry)
renv_watchdog_notify("LockReleased", list(path = path))
}
renv_lock_orphaned <- function(path) {
timeout <- getOption("renv.lock.timeout", default = 60L)
if (timeout <= 0L)
return(TRUE)
info <- renv_file_info(path)
if (is.na(info$isdir))
return(FALSE)
diff <- difftime(Sys.time(), info$mtime, units = "secs")
diff >= timeout
}
renv_lock_refresh <- function(lock) {
Sys.setFileTime(lock, Sys.time())
}
renv_lock_unload <- function() {
locks <- ls(envir = the$lock_registry, all.names = TRUE)
unlink(locks, recursive = TRUE, force = TRUE)
}
renv_lock_path <- function(path) {
file.path(
renv_path_normalize(dirname(path), mustWork = TRUE),
basename(path)
)
}
renv/R/remotes.R 0000644 0001762 0000144 00000064365 14600646106 013247 0 ustar ligges users
#' Resolve a Remote
#'
#' Given a remote specification, resolve it into an renv package record that
#' can be used for download and installation (e.g. with [install]).
#'
#' @param spec A remote specification. This should be a string, conforming
#' to the Remotes specification as defined in
#' .
#'
remote <- function(spec) {
renv_scope_error_handler()
renv_remotes_resolve(spec)
}
# take a short-form remotes spec, parse that into a remote,
# and generate a corresponding package record
renv_remotes_resolve <- function(spec, latest = FALSE) {
# check for already-resolved specs
if (is.null(spec) || is.list(spec))
return(spec)
# remove a trailing slash
# https://github.com/rstudio/renv/issues/1135
spec <- gsub("/+$", "", spec, perl = TRUE)
# check for archive URLs -- this is a bit hacky
if (grepl("^(?:file|https?)://", spec)) {
for (suffix in c(".zip", ".tar.gz", ".tgz", "/tarball"))
if (endswith(spec, suffix))
return(renv_remotes_resolve_url(spec, quiet = TRUE))
}
# remove github prefix
spec <- gsub("^https?://(?:www\\.)?github\\.com/", "", spec)
# check for paths to existing local files
first <- substring(spec, 1L, 1L)
local <- first %in% c("~", "/", ".") || renv_path_absolute(spec)
if (local) {
record <- catch(renv_remotes_resolve_path(spec))
if (!inherits(record, "error"))
return(record)
}
# define error handler (tag error with extra context when possible)
error <- function(e) {
# build error message
fmt <- "failed to resolve remote '%s'"
prefix <- sprintf(fmt, spec)
message <- paste(prefix, e$message, sep = " -- ")
# otherwise, propagate the error
stop(simpleError(message = message, call = e$call))
}
# attempt the parse
withCallingHandlers(
renv_remotes_resolve_impl(spec, latest),
error = error
)
}
renv_remotes_resolve_impl <- function(spec, latest = FALSE) {
remote <- renv_remotes_parse(spec)
# fixup for bioconductor
isbioc <-
identical(remote$type, "repository") &&
identical(remote$repository, "bioc")
if (isbioc)
remote$type <- "bioc"
resolved <- switch(
remote$type,
bioc = renv_remotes_resolve_bioc(remote),
bitbucket = renv_remotes_resolve_bitbucket(remote),
gitlab = renv_remotes_resolve_gitlab(remote),
github = renv_remotes_resolve_github(remote),
repository = renv_remotes_resolve_repository(remote, latest),
git = renv_remotes_resolve_git(remote),
url = renv_remotes_resolve_url(remote$url, quiet = TRUE),
stopf("unknown remote type '%s'", remote$type %||% "")
)
# ensure that attributes on the record are preserved, but drop NULL entries
for (key in names(resolved))
if (is.null(resolved[[key]]))
resolved[[key]] <- NULL
resolved
}
renv_remotes_parse_impl <- function(spec, pattern, fields, perl = FALSE) {
matches <- regexec(pattern, spec, perl = perl)
strings <- regmatches(spec, matches)[[1]]
if (empty(strings))
stopf("'%s' is not a valid remote", spec)
if (length(fields) != length(strings))
stop("internal error: field length mismatch in renv_remotes_parse_impl")
names(strings) <- fields
remote <- as.list(strings)
lapply(remote, function(item) if (nzchar(item)) item)
}
renv_remotes_parse_repos <- function(spec) {
pattern <- paste0(
"^", # start
"(?:([^:]+)::)?", # optional repository name
"([[:alnum:].]+)", # package name
"(?:@([[:digit:]_.-]+))?", # optional package version
"$"
)
fields <- c("spec", "repository", "package", "version")
renv_remotes_parse_impl(spec, pattern, fields)
}
renv_remotes_parse_remote <- function(spec) {
pattern <- paste0(
"^",
"(?:([[:alpha:]][[:alnum:].]*[[:alnum:]])=)?", # optional package name
"(?:([^@:]+)(?:@([^:]+))?::)?", # optional prefix, providing type + host
"([^/#@:]+)", # a username
"(?:/([^@#:]+))?", # a repository (allow sub-repositories)
"(?::([^@#:]+))?", # optional subdirectory
"(?:#([^@#:]+))?", # optional hash (e.g. pull request)
"(?:@([^@#:]+))?", # optional ref (e.g. branch or commit)
"$"
)
fields <- c(
"spec", "package", "type",
"host", "user", "repo",
"subdir", "pull", "ref"
)
remote <- renv_remotes_parse_impl(spec, pattern, fields)
if (!nzchar(remote$repo))
stopf("'%s' is not a valid remote", spec)
renv_remotes_parse_finalize(remote)
}
renv_remotes_parse_gitssh <- function(spec) {
pattern <- paste0(
"^",
"(?:([[:alpha:]][[:alnum:].]*[[:alnum:]])=)?", # optional package name
"(?:(git)::)?", # optional git prefix
"(", # url start
"([^@]+)@", # user (typically, 'git')
"([^:]+):", # host
"([^:#@]+)", # the rest of the repo url
")", # url end
"(?::([^@#:]+))?", # optional sub-directory
"(?:#([^@#:]+))?", # optional hash (e.g. pull request)
"(?:@([^@#:]+))?", # optional ref (e.g. branch or commit)
"$"
)
fields <- c(
"spec", "package", "type", "url",
"user", "host", "repo",
"subdir", "pull", "ref"
)
remote <- renv_remotes_parse_impl(spec, pattern, fields, perl = TRUE)
if (!nzchar(remote$repo))
stopf("'%s' is not a valid remote", spec)
remote$type <- remote$type %||% "git"
renv_remotes_parse_finalize(remote)
}
renv_remotes_parse_git <- function(spec) {
hostpattern <- paste0(
"(",
"(?:(?:(?!-))(?:xn--|_{1,1})?[a-z0-9-]{0,61}[a-z0-9]{1,1}\\.)*",
"(?:xn--)?",
"(?:[a-z0-9][a-z0-9\\-]{0,60}|[a-z0-9-]{1,30}\\.[a-z]{2,})",
")"
)
pattern <- paste0(
"^",
"(?:([[:alpha:]][[:alnum:].]*[[:alnum:]])=)?", # optional package name
"(?:(git)::)?", # optional git prefix
"(", # URL start
"(?:(https?|git|ssh)://)?", # protocol
"(?:([^@]+)@)?", # login (probably git)
hostpattern, # host
"[/:]([\\w_.-]+)", # a username
"(?:/([^@#:]+?))?", # a repository (allow sub-repositories)
"(?:\\.(git))?", # optional .git extension
")", # URL end
"(?::([^@#:]+))?", # optional sub-directory
"(?:#([^@#:]+))?", # optional hash (e.g. pull request)
"(?:@([^@#:]+))?", # optional ref (e.g. branch or commit)
"$"
)
fields <- c(
"spec", "package", "type",
"url", "protocol", "login", "host", "user", "repo", "ext",
"subdir", "pull", "ref"
)
remote <- renv_remotes_parse_impl(spec, pattern, fields, perl = TRUE)
if (!nzchar(remote$repo))
stopf("'%s' is not a valid remote", spec)
# If type has not been found & repo looks like a git repo, set it as git
# (note that this parser also accepts entries which are not truly git
# references, so we try to "fix up" after the fact)
if ("git" %in% c(remote$login, remote$type, remote$ext, remote$protocol))
remote$type <- tolower(remote$type %||% "git")
renv_remotes_parse_finalize(remote)
}
# NOTE: to avoid ambiguity with git remote specs, we require URL
# remotes to begin with a 'url::' prefix
renv_remotes_parse_url <- function(spec) {
pattern <- paste0(
"^",
"(?:([[:alpha:]][[:alnum:].]*[[:alnum:]])=)?", # optional package name
"(url)::", # type (required for URL remotes)
"((https?)://([^:]+))", # url, protocol, path
"(?::([^@#:]+))?", # optional subdir
"$"
)
fields <- c("spec", "package", "type", "url", "protocol", "path", "subdir")
remote <- renv_remotes_parse_impl(spec, pattern, fields, perl = TRUE)
if (!nzchar(remote$url))
stopf("'%s' is not a valid remote", spec)
renv_remotes_parse_finalize(remote)
}
renv_remotes_parse_finalize <- function(remote) {
# default remote type is github
remote$type <- tolower(remote$type %||% "github")
# custom finalization for different remote types
case(
remote$type == "github" ~ renv_remotes_parse_finalize_github(remote),
TRUE ~ remote
)
}
renv_remotes_parse_finalize_github <- function(remote) {
# split repo spec into pieces
repo <- remote$repo %||% ""
parts <- strsplit(repo, "/", fixed = TRUE)[[1]]
if (length(parts) < 2)
return(remote)
# form subdir from tail of repo
remote$repo <- paste(head(parts, n = 1L), collapse = "/")
remote$subdir <- paste(tail(parts, n = -1L), collapse = "/")
# return modified remote
remote
}
renv_remotes_parse <- function(spec) {
remote <- catch(renv_remotes_parse_repos(spec))
if (!inherits(remote, "error")) {
remote$type <- "repository"
return(remote)
}
remote <- catch(renv_remotes_parse_remote(spec))
if (!inherits(remote, "error")) {
remote$type <- remote$type %||% "github"
return(remote)
}
remote <- catch(renv_remotes_parse_gitssh(spec))
if (!inherits(remote, "error")) {
remote$type <- remote$type %||% "git"
return(remote)
}
remote <- catch(renv_remotes_parse_url(spec))
if (!inherits(remote, "error")) {
remote$type <- remote$type %||% "url"
return(remote)
}
remote <- catch(renv_remotes_parse_git(spec))
if (!inherits(remote, "error")) {
remote$type <- remote$type %||% "git"
return(remote)
}
stopf("failed to parse remote spec '%s'", spec)
}
renv_remotes_resolve_bioc_version <- function(version) {
# initialize Bioconductor
renv_bioconductor_init()
BiocManager <- renv_scope_biocmanager()
# handle versions like 'release' and 'devel'
versions <- BiocManager$.version_map()
row <- versions[versions$BiocStatus == version, ]
if (nrow(row))
return(row$Bioc)
# otherwise, use the default version
BiocManager$version()
}
renv_remotes_resolve_bioc_plain <- function(remote) {
list(
Package = remote$package,
Version = remote$version,
Source = "Bioconductor"
)
}
renv_remotes_resolve_bioc <- function(remote) {
# if we parsed this as a repository remote, use that directly
if (!is.null(remote$package))
return(renv_remotes_resolve_bioc_plain(remote))
# otherwise, this was parsed as a regular remote, declaring the package
# should be obtained from a particular Bioconductor release
package <- remote$repo
biocversion <- renv_remotes_resolve_bioc_version(remote$user)
biocrepos <- renv_bioconductor_repos(version = biocversion)
record <- renv_available_packages_latest(package, repos = biocrepos)
# update fields
record$Source <- "Bioconductor"
record$Repository <- NULL
# return the resolved record
record
}
renv_remotes_resolve_bitbucket <- function(remote) {
user <- remote$user
repo <- remote$repo
subdir <- remote$subdir
ref <- remote$ref %||% getOption("renv.bitbucket.default_branch", "master")
host <- remote$host %||% config$bitbucket.host()
# scope authentication
renv_scope_auth(repo)
# get commit sha for ref
fmt <- "%s/repositories/%s/%s/commit/%s"
origin <- renv_retrieve_origin(host)
url <- sprintf(fmt, origin, user, repo, ref)
destfile <- renv_scope_tempfile("renv-bitbucket-")
download(url, destfile = destfile, type = "bitbucket", quiet = TRUE)
json <- renv_json_read(file = destfile)
sha <- json$hash
# get DESCRIPTION file
fmt <- "%s/repositories/%s/%s/src/%s/DESCRIPTION"
origin <- renv_retrieve_origin(host)
url <- sprintf(fmt, origin, user, repo, ref)
destfile <- renv_scope_tempfile("renv-description-")
download(url, destfile = destfile, type = "bitbucket", quiet = TRUE)
desc <- renv_dcf_read(destfile)
list(
Package = desc$Package,
Version = desc$Version,
Source = "Bitbucket",
RemoteType = "bitbucket",
RemoteHost = host,
RemoteUsername = user,
RemoteRepo = repo,
RemoteSubdir = subdir,
RemoteRef = ref,
RemoteSha = sha
)
}
renv_remotes_resolve_repository <- function(remote, latest) {
package <- remote$package
if (package %in% renv_packages_base())
return(renv_remotes_resolve_base(package))
version <- remote$version
repository <- remote$repository
if (latest && is.null(version)) {
remote <- renv_available_packages_latest(package)
version <- remote$Version
}
list(
Package = package,
Version = version,
Source = "Repository",
Repository = repository
)
}
renv_remotes_resolve_base <- function(package) {
list(
Package = package,
Version = renv_package_version(package),
Source = "R"
)
}
renv_remotes_resolve_github_sha_pull <- function(host, user, repo, pull) {
# scope authentication
renv_scope_auth(repo)
# make request
fmt <- "%s/repos/%s/%s/pulls/%s"
origin <- renv_retrieve_origin(host)
url <- sprintf(fmt, origin, user, repo, pull)
jsonfile <- renv_scope_tempfile("renv-json-")
download(url, destfile = jsonfile, type = "github", quiet = TRUE)
# read resulting JSON
json <- renv_json_read(jsonfile)
json$head$sha
}
renv_remotes_resolve_github_sha_ref <- function(host, user, repo, ref) {
# scope authentication
renv_scope_auth(repo)
# build url for github commits endpoint
fmt <- "%s/repos/%s/%s/commits/%s"
origin <- renv_retrieve_origin(host)
ref <- ref %||% getOption("renv.github.default_branch", default = "master")
url <- sprintf(fmt, origin, user, repo, ref %||% "master")
# prepare headers
headers <- c(Accept = "application/vnd.github.sha")
# make request to endpoint
shafile <- renv_scope_tempfile("renv-sha-")
download(
url,
destfile = shafile,
type = "github",
quiet = TRUE,
headers = headers
)
# read downloaded content
sha <- renv_file_read(shafile)
# check for JSON response (in case our headers weren't sent)
if (nchar(sha) > 40L) {
json <- renv_json_read(text = sha)
sha <- json$sha
}
sha
}
renv_remotes_resolve_github_modules <- function(host, user, repo, subdir, sha) {
# form path to .gitmodules file
subdir <- subdir %||% ""
parts <- c(
if (nzchar(subdir)) URLencode(subdir),
".gitmodules"
)
path <- paste(parts, collapse = "/")
# scope authentication
renv_scope_auth(repo)
# add headers
headers <- c(Accept = "application/vnd.github.raw")
# get the file contents
fmt <- "%s/repos/%s/%s/contents/%s?ref=%s"
origin <- renv_retrieve_origin(host)
url <- sprintf(fmt, origin, user, repo, path, sha)
jsonfile <- renv_scope_tempfile("renv-json-")
status <- suppressWarnings(
catch(
download(url, destfile = jsonfile, type = "github", quiet = TRUE, headers = headers)
)
)
# just return a status code whether or not submodules are included
!inherits(status, "error")
}
renv_remotes_resolve_github_description <- function(url, host, user, repo, subdir, sha) {
# form DESCRIPTION path
subdir <- subdir %||% ""
parts <- c(
if (nzchar(subdir)) URLencode(subdir),
"DESCRIPTION"
)
descpath <- paste(parts, collapse = "/")
# scope authentication
renv_scope_auth(repo)
# add headers
headers <- c(
Accept = "application/vnd.github.raw",
renv_download_auth_github(url)
)
# get the DESCRIPTION contents
fmt <- "%s/repos/%s/%s/contents/%s?ref=%s"
origin <- renv_retrieve_origin(host)
url <- sprintf(fmt, origin, user, repo, descpath, sha)
destfile <- renv_scope_tempfile("renv-json-")
download(url, destfile = destfile, type = "github", quiet = TRUE, headers = headers)
# try to read the file; detect JSON versus raw content in case
# headers were not sent for some reason
contents <- renv_file_read(destfile)
if (substring(contents, 1L, 1L) == "{") {
json <- renv_json_read(text = contents)
contents <- renv_base64_decode(json$content)
}
# normalize newlines
contents <- gsub("\r\n", "\n", contents, fixed = TRUE)
# read as DCF
renv_dcf_read(text = contents)
}
renv_remotes_resolve_github_ref <- function(host, user, repo) {
tryCatch(
renv_remotes_resolve_github_ref_impl(host, user, repo),
error = function(e) {
warning(e)
getOption("renv.github.default_branch", default = "master")
}
)
}
renv_remotes_resolve_github_ref_impl <- function(host, user, repo) {
# scope authentication
renv_scope_auth(repo)
# build url to repos endpoint
fmt <- "%s/repos/%s/%s"
origin <- renv_retrieve_origin(host)
url <- sprintf(fmt, origin, user, repo)
# download JSON data at endpoint
jsonfile <- renv_scope_tempfile("renv-github-ref-", fileext = ".json")
download(url, destfile = jsonfile, type = "github", quiet = TRUE)
json <- renv_json_read(jsonfile)
# read default branch
json$default_branch %||% getOption("renv.github.default_branch", default = "master")
}
renv_remotes_resolve_github <- function(remote) {
# resolve the reference associated with this repository
host <- remote$host %||% config$github.host()
user <- remote$user
repo <- remote$repo
spec <- remote$spec
subdir <- remote$subdir
# resolve ref
ref <- remote$ref %||% renv_remotes_resolve_github_ref(host, user, repo)
# handle '*release' refs
if (identical(ref, "*release"))
ref <- renv_remotes_resolve_github_release(host, user, repo, spec)
# resolve the sha associated with the ref / pull
pull <- remote$pull %||% ""
sha <- case(
nzchar(pull) ~ renv_remotes_resolve_github_sha_pull(host, user, repo, pull),
nzchar(ref) ~ renv_remotes_resolve_github_sha_ref(host, user, repo, ref)
)
# if an abbreviated sha was provided as the ref, expand it here
if (nzchar(ref) && startswith(sha, ref))
ref <- sha
# check whether the repository has a .gitmodules file; if so, then we'll have
# to use a plain 'git' client to retrieve the package
modules <- renv_remotes_resolve_github_modules(host, user, repo, subdir, sha)
# construct full url
origin <- fsub("api.github.com", "github.com", renv_retrieve_origin(host))
parts <- c(origin, user, repo)
url <- paste(parts, collapse = "/")
# read DESCRIPTION
desc <- renv_remotes_resolve_github_description(url, host, user, repo, subdir, sha)
list(
Package = desc$Package,
Version = desc$Version,
Source = if (modules) "git" else "GitHub",
RemoteType = if (modules) "git" else "github",
RemoteUrl = if (modules) url,
RemoteHost = host,
RemoteUsername = user,
RemoteRepo = repo,
RemoteSubdir = subdir,
RemoteRef = ref,
RemoteSha = sha
)
}
renv_remotes_resolve_github_release <- function(host, user, repo, spec) {
# scope authentication
renv_scope_auth(repo)
# build url for github releases endpoint
fmt <- "%s/repos/%s/%s/releases?per_page=1"
origin <- renv_retrieve_origin(host)
url <- sprintf(fmt, origin, user, repo)
# prepare headers
headers <- c(Accept = "application/vnd.github.raw+json")
# make request to endpoint
releases <- renv_scope_tempfile("renv-releases-")
download(
url = url,
destfile = releases,
type = "github",
quiet = TRUE,
headers = headers
)
# get reference associated with this tag
json <- renv_json_read(releases)
if (empty(json)) {
fmt <- "could not find any releases associated with remote '%s'"
stopf(fmt, sub("[*]release$", "", spec))
}
json[[1L]][["tag_name"]]
}
renv_remotes_resolve_git <- function(remote) {
package <- remote$package %||% basename(remote$repo)
url <- remote$url
subdir <- remote$subdir
# handle git ref
pull <- remote$pull %||% ""
ref <- remote$ref %||% ""
# resolve ref from pull if set
if (nzchar(pull))
ref <- renv_remotes_resolve_git_pull(ref)
record <- list(
Package = package,
Version = "",
Source = "git",
RemoteType = "git",
RemoteUrl = url,
RemoteSubdir = subdir,
RemoteRef = ref
)
desc <- renv_remotes_resolve_git_description(record)
record$Package <- desc$Package
record$Version <- desc$Version
record
}
renv_remotes_resolve_git_sha_ref <- function(record) {
renv_git_preflight()
origin <- record$RemoteUrl
ref <- record$RemoteRef %||% record$RemoteSha
args <- c("ls-remote", origin, ref)
output <- local({
renv_scope_auth(record)
renv_scope_git_auth()
renv_system_exec("git", args, "checking git remote")
})
if (empty(output))
return("")
# format of output is, for example:
#
# $ git ls-remote https://github.com/rstudio/renv refs/tags/0.14.0
# 20ca74bdcc3c87848e5665effa2fc8ee8b039c69 refs/tags/0.14.0
#
# take first line of output, split on tab character, and take leftmost entry
strsplit(output[[1L]], "\t", fixed = TRUE)[[1L]][[1L]]
}
renv_remotes_resolve_git_description <- function(record) {
path <- renv_scope_tempfile("renv-git-")
ensure_directory(path)
# TODO: is there a cheaper way for us to accomplish this?
# it'd be nice if we could retrieve the contents of a single
# file, without needing to pull an entire repository branch
local({
renv_scope_options(renv.verbose = FALSE)
renv_retrieve_git_impl(record, path)
})
# subdir may be NULL
subdir <- record$RemoteSubdir
desc <- renv_description_read(path, subdir = subdir)
desc
}
renv_remotes_resolve_git_pull <- function(pr) {
# to be able to checkout PR 760:
# git fetch origin pull/760/head:pr-760
# or:
# git fetch origin pull/760/head:pull/760
# so format for ref is:
# pull/{ref_number}/head:pr-{ref_number}
fmt <- "pull/%s/head:pull/%s"
remote_ref <- sprintf(fmt, pr, pr)
remote_ref
}
renv_remotes_resolve_gitlab_ref <- function(host, user, repo) {
tryCatch(
renv_remotes_resolve_gitlab_ref_impl(host, user, repo),
error = function(e) {
warning(e)
getOption("renv.gitlab.default_branch", default = "master")
}
)
}
renv_remotes_resolve_gitlab_ref_impl <- function(host, user, repo) {
# scope authentication
renv_scope_auth(repo)
# get list of available branches
fmt <- "%s/api/v4/projects/%s/repository/branches"
origin <- renv_retrieve_origin(host)
id <- URLencode(paste(user, repo, sep = "/"), reserved = TRUE)
url <- sprintf(fmt, origin, id)
destfile <- renv_scope_tempfile("renv-gitlab-commits-")
download(url, destfile = destfile, type = "gitlab", quiet = TRUE)
json <- renv_json_read(file = destfile)
# iterate through and find the default
for (info in json)
if (identical(info$default, TRUE))
return(info$name)
# if no default was found, use master branch
# (for backwards compatibility with existing projects)
getOption("renv.gitlab.default_branch", default = "master")
}
renv_remotes_resolve_gitlab <- function(remote) {
host <- remote$host %||% config$gitlab.host()
user <- remote$user
repo <- remote$repo
subdir <- remote$subdir %||% ""
ref <- remote$ref %||% renv_remotes_resolve_gitlab_ref(host, user, repo)
parts <- c(if (nzchar(subdir)) subdir, "DESCRIPTION")
descpath <- URLencode(paste(parts, collapse = "/"), reserved = TRUE)
# scope authentication
renv_scope_auth(repo)
# retrieve sha associated with this ref
fmt <- "%s/api/v4/projects/%s/repository/commits/%s"
origin <- renv_retrieve_origin(host)
id <- URLencode(paste(user, repo, sep = "/"), reserved = TRUE)
ref <- URLencode(ref, reserved = TRUE)
url <- sprintf(fmt, origin, id, ref)
destfile <- renv_scope_tempfile("renv-gitlab-commits-")
download(url, destfile = destfile, type = "gitlab", quiet = TRUE)
json <- renv_json_read(file = destfile)
sha <- json$id
# retrieve DESCRIPTION file
fmt <- "%s/api/v4/projects/%s/repository/files/%s/raw?ref=%s"
origin <- renv_retrieve_origin(host)
id <- URLencode(paste(user, repo, sep = "/"), reserved = TRUE)
url <- sprintf(fmt, origin, id, descpath, ref)
destfile <- renv_scope_tempfile("renv-description-")
download(url, destfile = destfile, type = "gitlab", quiet = TRUE)
desc <- renv_dcf_read(destfile)
list(
Package = desc$Package,
Version = desc$Version,
Source = "GitLab",
RemoteType = "gitlab",
RemoteHost = host,
RemoteUsername = user,
RemoteRepo = repo,
RemoteSubdir = subdir,
RemoteRef = ref,
RemoteSha = sha
)
}
renv_remotes_resolve_url <- function(url, quiet = FALSE) {
tempfile <- renv_scope_tempfile("renv-url-")
writeLines(url, con = tempfile)
hash <- tools::md5sum(tempfile)
ext <- fileext(url, default = ".tar.gz")
name <- paste(hash, ext, sep = "")
path <- renv_paths_source("url", name)
ensure_parent_directory(path)
download(url, path, quiet = quiet)
desc <- renv_description_read(path)
list(
Package = desc$Package,
Version = desc$Version,
Source = "URL",
RemoteType = "url",
RemoteUrl = url,
Path = path
)
}
renv_remotes_resolve_path <- function(path) {
# if this package lives within one of the cellar paths,
# then treat it as a cellar source
roots <- renv_cellar_roots()
for (root in roots)
if (renv_path_within(path, root))
return(renv_remotes_resolve_path_cellar(path))
# first, check for a common extension
if (renv_archive_type(path) %in% c("tar", "zip"))
return(renv_remotes_resolve_path_impl(path))
# otherwise, if this is the path to a package project, use the sources as-is
if (renv_project_type(path) == "package")
return(renv_remotes_resolve_path_impl(path))
stopf("there is no package at path '%s'", path)
}
renv_remotes_resolve_path_cellar <- function(path) {
desc <- renv_description_read(path)
list(
Package = desc$Package,
Version = desc$Version,
Source = "Cellar",
Cacheable = FALSE
)
}
renv_remotes_resolve_path_impl <- function(path) {
desc <- renv_description_read(path)
list(
Package = desc$Package,
Version = desc$Version,
Source = "Local",
RemoteType = "local",
RemoteUrl = path,
Cacheable = FALSE
)
}
renv/R/clean.R 0000644 0001762 0000144 00000021366 14500176536 012651 0 ustar ligges users
#' Clean a project
#'
#' Clean up a project and its associated \R libraries.
#'
#' # Actions
#'
#' The following clean actions are available:
#'
#' \describe{
#'
#' \item{`package.locks`}{
#'
#' During package installation, \R will create package locks in the
#' library path, typically named `00LOCK-`. On occasion, if package
#' installation fails or \R is terminated while installing a package, these
#' locks can be left behind and will inhibit future attempts to reinstall
#' that package. Use this action to remove such left-over package locks.
#'
#' }
#'
#' \item{`library.tempdirs`}{
#'
#' During package installation, \R may create temporary directories with
#' names of the form `file\w{12}`, and on occasion those files can be
#' left behind even after they are no longer in use. Use this action to
#' remove such left-over directories.
#' }
#'
#' \item{`system.library`}{
#'
#' In general, it is recommended that only packages distributed with \R
#' are installed into the default library (the library path referred to
#' by `.Library`). Use this action to remove any user-installed packages
#' that have been installed to the system library.
#'
#' Because this action is destructive, it is by default never run -- it
#' must be explicitly requested by the user.
#'
#' }
#'
#' \item{`unused.packages`}{
#'
#' Remove packages that are installed in the project library, but no longer
#' appear to be used in the project sources.
#'
#' Because this action is destructive, it is by default only run in
#' interactive sessions when prompting is enabled.
#'
#' }
#'
#' }
#'
#'
#' @inherit renv-params
#'
#' @param actions The set of clean actions to take. See the documentation in
#' **Actions** for a list of available actions, and the default actions
#' taken when no actions are supplied.
#'
#' @export
#'
#' @examples
#' \dontrun{
#'
#' # clean the current project
#' renv::clean()
#'
#' }
clean <- function(project = NULL,
...,
actions = NULL,
prompt = interactive())
{
renv_scope_error_handler()
renv_dots_check(...)
project <- renv_project_resolve(project)
renv_project_lock(project = project)
renv_scope_verbose_if(prompt)
renv_activate_prompt("clean", NULL, prompt, project)
actions <- actions %||% renv_clean_actions(prompt)
all <- list(
package.locks = renv_clean_package_locks,
library.tempdirs = renv_clean_library_tempdirs,
system.library = renv_clean_system_library,
unused.packages = renv_clean_unused_packages
)
methods <- all[actions]
for (method in methods)
tryCatch(method(project, prompt), error = warnify)
writef("- The project has been cleaned.")
invisible(project)
}
renv_clean_actions <- function(prompt) {
default <- c(
"package.locks",
"library.tempdirs"
)
unsafe <- c(
# "system.library",
"unused.packages"
)
c(default, if (prompt) unsafe)
}
renv_clean_library_tempdirs <- function(project, prompt) {
ntd <- function() {
writef("- No temporary directories were found in the project library.")
FALSE
}
library <- renv_paths_library(project = project)
children <- list.files(library, full.names = TRUE)
bad <- grep("/file\\w{12}$", children, value = TRUE)
if (empty(bad))
return(ntd())
# nocov start
if (prompt || renv_verbose()) {
caution_bullets("The following directories will be removed:", bad)
if (prompt && !proceed())
cancel()
}
# nocov end
unlink(bad, recursive = TRUE)
TRUE
}
# remove user packages in system library
renv_clean_system_library <- function(project, prompt) {
ntd <- function() {
writef("- No non-system packages were discovered in the system library.")
FALSE
}
# explicitly query for packages
syslib <- renv_path_normalize(renv_libpaths_system())
db <- installed_packages(lib.loc = syslib, priority = "NA")
packages <- setdiff(db$Package, "translations")
# also look for leftover package folders
# (primarily for Windows, where .dlls from old packages can be left behind)
# nocov start
if (renv_platform_windows()) {
folders <- list.files(syslib, full.names = TRUE)
descpaths <- file.path(folders, "DESCRIPTION")
missing <- !file.exists(descpaths)
packages <- union(packages, basename(folders)[missing])
}
# nocov end
# check for any packages needing removal
if (empty(packages))
return(ntd())
# nocov start
if (prompt || renv_verbose()) {
caution_bullets(
"The following non-system packages are installed in the system library:",
packages,
c(
"Normally, only packages distributed with R should be installed in the system library.",
"These packages will be removed.",
"If necessary, consider reinstalling these packages in your site library."
)
)
if (prompt && !proceed())
cancel()
}
# nocov end
remove(packages, library = syslib)
TRUE
}
renv_clean_unused_packages <- function(project, prompt) {
ntd <- function() {
writef("- No unused packages were found in the project library.")
FALSE
}
# find packages installed in the project library
library <- renv_paths_library(project = project)
installed <- list.files(library)
if (empty(installed))
return(ntd())
# find packages used in the project and their recursive dependencies
packages <- renv_snapshot_dependencies(project, dev = TRUE)
paths <- renv_package_dependencies(packages, project = project)
packages <- names(paths)
# figure out which packages aren't needed
removable <- renv_vector_diff(installed, packages)
if (empty(removable))
return(ntd())
# nocov start
if (prompt || renv_verbose()) {
caution_bullets(
c(
"The following packages are installed in the project library,",
"but appear to be no longer used in your project."
),
removable,
"These packages will be removed."
)
if (prompt && !proceed())
cancel()
}
# nocov end
remove(removable, library = library)
return(TRUE)
}
renv_clean_package_locks <- function(project, prompt) {
ntd <- function() {
writef("- No stale package locks were found.")
FALSE
}
# find 00LOCK directories in library
library <- renv_paths_library(project = project)
lock <- list.files(path = library, pattern = "^00LOCK", full.names = TRUE)
if (empty(lock))
return(ntd())
# check to see which are old
now <- Sys.time()
mtime <- file.mtime(lock)
mtime[is.na(mtime)] <- now
diff <- difftime(now, mtime, units = "secs")
old <- lock[diff > 120]
if (empty(old))
return(ntd())
# nocov start
if (prompt || renv_verbose()) {
caution_bullets(
"The following stale package locks were discovered in your library:",
basename(old),
"These locks will be removed."
)
if (prompt && !proceed())
cancel()
}
# nocov end
unlink(old, recursive = TRUE)
TRUE
}
# nocov start
renv_clean_cache <- function(project, prompt) {
ntd <- function() {
writef("- No unused packages were found in the renv cache.")
FALSE
}
# find projects monitored by renv
projects <- renv_paths_root("projects")
projlist <- character()
if (file.exists(projects))
projlist <- readLines(projects, warn = FALSE, encoding = "UTF-8")
# inform user if any projects are missing
missing <- !file.exists(projlist)
if (any(missing)) {
caution_bullets(
"The following projects are monitored by renv, but no longer exist:",
projlist[missing],
"These projects will be removed from renv's project list."
)
if (prompt && !proceed())
cancel()
writeLines(projlist[!missing], con = projects, useBytes = TRUE)
}
action <- function(project) {
library <- renv_paths_library(project = project)
packages <- list.files(library, full.names = TRUE)
descs <- file.path(packages, "DESCRIPTION")
existing <- file.exists(descs)
map_chr(descs[existing], renv_cache_path, USE.NAMES = FALSE)
}
# for each project, find packages used in their renv private library,
# and look for entries in the cache
projlist <- projlist[!missing]
callback <- renv_progress_callback(action, length(projlist))
used <- uapply(projlist, callback)
# check what packages are actually available in the cache
available <- renv_cache_list()
diff <- renv_vector_diff(available, used)
if (empty(diff))
return(ntd())
if (prompt || renv_verbose()) {
caution_bullets(
"The following packages are installed in the cache but no longer used:",
renv_cache_format_path(diff),
"These packages will be removed."
)
if (prompt && !proceed())
cancel()
}
# remove the directories
unlink(diff, recursive = TRUE)
renv_cache_clean_empty()
writef("- %i package(s) have been removed.", length(diff))
TRUE
}
# nocov end
renv/R/scaffold.R 0000644 0001762 0000144 00000004255 14464550375 013354 0 ustar ligges users #' Generate project infrastructure
#'
#' @description
#' Create the renv project infrastructure. This will:
#'
#' - Create a project library, `renv/library`.
#'
#' - Install renv into the project library.
#'
#' - Update the project `.Rprofile` to call `source("renv/activate.R")` so
#' that renv is automatically loaded for new \R sessions launched in
#' this project.
#'
#' - Create `renv/.gitignore`, which tells git to ignore the project library.
#'
#' - Create `.Rbuildignore`, if the project is also a package. This tells
#' `R CMD build` to ignore the renv infrastructure,
#'
#' - Write a (bare) [lockfile], `renv.lock`.
#'
#' @inheritParams renv-params
#'
#' @param version The version of renv to associate with this project. By
#' default, the version of renv currently installed is used.
#'
#' @param repos The \R repositories to associate with this project.
#'
#' @param settings A list of renv settings, to be applied to the project
#' after creation. These should map setting names to the desired values.
#' See [settings] for more details.
#'
#' @examples
#'
#' \dontrun{
#' # create scaffolding with 'devtools' ignored
#' renv::scaffold(settings = list(ignored.packages = "devtools"))
#' }
#'
#' @export
scaffold <- function(project = NULL,
version = NULL,
repos = getOption("repos"),
settings = NULL)
{
renv_scope_error_handler()
renv_scope_options(repos = repos)
project <- renv_project_resolve(project)
renv_project_lock(project = project)
# install renv into project library
renv_imbue_impl(project, version)
# write out project infrastructure
renv_infrastructure_write(project, version)
# update project settings
if (is.list(settings))
renv_settings_persist(project, settings)
# generate a lockfile
lockfile <- renv_lockfile_create(
project = project,
libpaths = renv_paths_library(project = project),
type = "implicit"
)
renv_lockfile_write(lockfile, file = renv_lockfile_path(project))
# notify user
fmt <- "- renv infrastructure has been generated for project %s."
writef(fmt, renv_path_pretty(project))
# return project invisibly
invisible(project)
}
renv/R/restart.R 0000644 0001762 0000144 00000004555 14464550375 013262 0 ustar ligges users
# whether or not we're already trying to restart the session
the$restarting <- FALSE
renv_restart_request <- function(project = NULL, reason = "", ...) {
project <- renv_project_resolve(project)
# if we're running in RStudio, explicitly open the project
# if it differs from the current project
if (renv_rstudio_available()) {
status <- renv_restart_request_rstudio(project, reason, ...)
return(invisible(status))
}
renv_restart_request_default(project, reason, ...)
}
renv_restart_request_default <- function(project, reason, ...) {
# use 'restart' helper defined by front-end (if any)
restart <- getOption("restart")
if (is.function(restart))
return(renv_restart_invoke(restart))
# otherwise, ask the user to restart
if (interactive()) {
fmt <- "- %s -- please restart the R session."
writef(fmt, sprintf(reason, ...))
}
}
renv_restart_request_rstudio <- function(project, reason, ...) {
# if we're running tests, don't restart
if (renv_tests_running())
return(renv_restart_request_default(project, reason, ...))
# if we don't have a tools env, bail
tools <- catch(as.environment("tools:rstudio"))
if (inherits(tools, "error"))
return(renv_restart_request_default(project, reason, ...))
# if RStudio is too old, use default restart impl
old <-
is.null(tools$.rs.getProjectDirectory) ||
is.null(tools$.rs.api.openProject)
if (old)
return(renv_restart_request_default(project, reason, ...))
# if the requested project matches the current project, just
# restart the R session -- but note that we cannot respect
# the 'restart' option here as the version RStudio uses
# tries to preserve session state that we need to change.
#
# https://github.com/rstudio/renv/issues/1530
projdir <- tools$.rs.getProjectDirectory() %||% ""
if (renv_file_same(projdir, project)) {
restart <- getOption("renv.restart.function", default = function() {
tools$.rs.api.executeCommand("restartR", quiet = TRUE)
})
return(renv_restart_invoke(restart))
}
# otherwise, explicitly open the new project
renv_restart_invoke(function() {
invisible(tools$.rs.api.openProject(project, newSession = FALSE))
})
}
renv_restart_invoke <- function(callback) {
# avoid multiple attempts to restart in a single call, just in case
if (!the$restarting) {
the$restarting <- TRUE
callback()
}
}
renv/R/system.R 0000644 0001762 0000144 00000004122 14464550375 013110 0 ustar ligges users
renv_system_exec <- function(command,
args = NULL,
action = "executing command",
success = 0L,
stream = FALSE,
quiet = NULL)
{
# be quiet when running tests by default
quiet <- quiet %||% renv_tests_running()
# handle 'stream' specially
if (stream) {
# form stdout, stderr
stdout <- stderr <- if (quiet) FALSE else ""
# execute command
status <- suppressWarnings(
if (is.null(args))
system(command, ignore.stdout = quiet, ignore.stderr = quiet)
else
system2(command, args, stdout = stdout, stderr = stderr)
)
# check for error
status <- status %||% 0L
if (!is.null(success) && !status %in% success) {
fmt <- "error %s [error code %i]"
stopf(fmt, action, status)
}
# return status code
return(status)
}
# suppress warnings as some successful commands may return a non-zero exit
# code, whereas R will always warn on such error codes
output <- suppressWarnings(
if (is.null(args))
system(command, intern = TRUE)
else
system2(command, args, stdout = TRUE, stderr = TRUE)
)
# extract status code from result
status <- attr(output, "status") %||% 0L
# if this status matches an expected 'success' code, return output
if (is.null(success) || status %in% success)
return(output)
# otherwise, notify the user that things went wrong
abort(
sprintf("error %s [error code %i]", action, status),
body = renv_system_exec_details(command, args, output)
)
}
renv_system_exec_details <- function(command, args, output) {
# get header, giving the command that was run
cmdline <- paste(command, paste(args, collapse = " "))
underline <- paste(rep.int("=", min(80L, nchar(cmdline))), collapse = "")
header <- c(cmdline, underline)
# truncate output (avoid overwhelming console)
body <- if (length(output) > 200L)
c(head(output, n = 100L), "< ... >", tail(output, n = 100L))
else
output
c(header, "", body)
}
renv/R/unload.R 0000644 0001762 0000144 00000001751 14464550375 013053 0 ustar ligges users
unload <- function(project = NULL, quiet = FALSE) {
project <- renv_project_resolve(project)
renv_scope_error_handler()
if (renv_tests_running())
return()
if (quiet)
renv_scope_options(renv.verbose = FALSE)
renv_envvars_restore()
renv_unload_shims(project)
renv_unload_project(project)
renv_unload_profile(project)
renv_unload_envvars(project)
renv_unload_sandbox(project)
renv_unload_libpaths(project)
}
renv_unload_shims <- function(project) {
renv_shims_deactivate()
}
renv_unload_project <- function(project) {
renv_project_clear()
}
renv_unload_profile <- function(project) {
Sys.unsetenv("RENV_PROFILE")
}
renv_unload_envvars <- function(project) {
renv_envvars_restore()
}
renv_unload_sandbox <- function(project) {
renv_sandbox_deactivate()
}
renv_unload_libpaths <- function(project) {
renv_libpaths_restore()
}
renv_unload_finalizer <- function(libpath) {
libpath <- dirname(renv_namespace_path(.packageName))
.onUnload(libpath)
}
renv/R/url.R 0000644 0001762 0000144 00000001357 14464550375 012375 0 ustar ligges users
renv_url_parse <- function(url) {
pattern <- paste0(
"^",
"([^:]+://)?", # protocol
"([^/?#]+)", # domain
"(?:(/[^?#]*))?", # path
"(?:[?]([^#]+))?", # parameters
"(?:#(.*))?", # fragment
""
)
matches <- regmatches(url, regexec(pattern, url, perl = TRUE))[[1L]]
if (length(matches) != 6L)
stopf("couldn't parse url '%s'", url)
matches <- as.list(matches)
names(matches) <- c("url", "protocol", "domain", "path", "parameters", "fragment")
# parse parameters into named list
matches$parameters <- renv_properties_read(
text = chartr("&", "\n", matches$parameters),
delimiter = "=",
dequote = FALSE,
trim = FALSE
)
# return parsed URL
matches
}
renv/R/snapshot-auto.R 0000644 0001762 0000144 00000011147 14547051446 014373 0 ustar ligges users
# information about the project library; used to detect whether
# the library appears to have been modified or updated
the$library_info <- NULL
# are we forcing automatic snapshots?
the$auto_snapshot_forced <- FALSE
# did the last attempt at an automatic snapshot fail?
the$auto_snapshot_failed <- FALSE
# are we currently running an automatic snapshot?
the$auto_snapshot_running <- FALSE
# is the next automatic snapshot suppressed?
the$auto_snapshot_suppressed <- FALSE
# nocov start
renv_snapshot_auto <- function(project) {
# set some state so we know we're running
the$auto_snapshot_running <- TRUE
defer(the$auto_snapshot_running <- FALSE)
# passed pre-flight checks; snapshot the library
updated <- withCallingHandlers(
tryCatch(
renv_snapshot_auto_impl(project),
error = function(err) FALSE
),
cancel = function() FALSE
)
if (updated) {
lockfile <- renv_path_aliased(renv_lockfile_path(project))
writef("- Automatic snapshot has updated '%s'.", lockfile)
}
invisible(updated)
}
renv_snapshot_auto_impl <- function(project) {
# validation messages can be noisy; turn off for auto snapshot
renv_scope_options(
renv.config.snapshot.validate = FALSE,
renv.verbose = FALSE
)
# file.info() can warn in some cases; silence those
renv_scope_options(warn = -1L)
# get current lockfile state
lockfile <- renv_paths_lockfile(project)
old <- file.info(lockfile, extra_cols = FALSE)$mtime
# perform snapshot without prompting
snapshot(project = project, prompt = FALSE)
# check for change in lockfile
new <- file.info(lockfile, extra_cols = FALSE)$mtime
!identical(old, new)
}
renv_snapshot_auto_enabled <- function(project = renv_project_get()) {
# respect override
if (the$auto_snapshot_forced)
return(TRUE)
# respect config setting
enabled <- config$auto.snapshot(project = project)
if (!enabled)
return(FALSE)
# only snapshot interactively
if (!interactive())
return(FALSE)
# only automatically snapshot the current project
if (!renv_project_loaded(project))
return(FALSE)
# don't auto-snapshot if the project hasn't been initialized
if (!renv_project_initialized(project = project))
return(FALSE)
# don't auto-snapshot if we don't have a library
library <- renv_paths_library(project = project)
if (!file.exists(library))
return(FALSE)
# don't auto-snapshot unless the active library is the project library
if (!renv_file_same(renv_libpaths_active(), library))
return(FALSE)
TRUE
}
renv_snapshot_auto_update <- function(project = renv_project_get() ) {
# check for enabled
if (!renv_snapshot_auto_enabled(project = project))
return(FALSE)
# get path to project library
libpath <- renv_paths_library(project = project)
if (!file.exists(libpath))
return(FALSE)
# list files + get file info for files in project library
info <- renv_file_info(libpath)
# only keep relevant fields
fields <- c("size", "mtime", "ctime")
new <- c(info[fields])
# update our cached info
old <- the$library_info
the$library_info <- new
# if we've suppressed the next automatic snapshot, bail here
if (the$auto_snapshot_suppressed) {
the$auto_snapshot_suppressed <- FALSE
return(FALSE)
}
# report if things have changed
!is.null(old) && !identical(old, new)
}
renv_snapshot_task <- function() {
# if the previous snapshot attempt failed, do nothing
if (the$auto_snapshot_failed)
return(FALSE)
# silence warnings in this scope
renv_scope_options(warn = -1L)
# attempt automatic snapshot, but disable on failure
tryCatch(
renv_snapshot_task_impl(),
error = function(cnd) {
caution("Error generating automatic snapshot: %s", conditionMessage(cnd))
caution("Automatic snapshots will be disabled. Use `renv::snapshot()` to manually update the lockfile.")
the$auto_snapshot_failed <- TRUE
}
)
}
renv_snapshot_task_impl <- function() {
# check for active renv project
project <- renv_project_get()
if (is.null(project))
return(invisible(FALSE))
# see if library state has updated
updated <- renv_snapshot_auto_update(project = project)
if (!updated)
return(invisible(FALSE))
# library has updated; perform auto snapshot
status <- renv_snapshot_auto(project = project)
ok <- identical(status, TRUE)
# return invisibly for snapshot tests
invisible(ok)
}
renv_snapshot_auto_suppress_next <- function() {
# if we're currently running an automatic snapshot, then nothing to do
if (the$auto_snapshot_running)
return()
# otherwise, set the suppressed flag
the$auto_snapshot_suppressed <- TRUE
}
# nocov end
renv/R/sandbox.R 0000644 0001762 0000144 00000022146 14500373211 013207 0 ustar ligges users
renv_sandbox_init <- function() {
# check for envvar override
enabled <- Sys.getenv("RENV_SANDBOX_LOCKING_ENABLED", unset = NA)
if (!is.na(enabled)) {
enabled <- truthy(enabled, default = FALSE)
options(renv.sandbox.locking_enabled = enabled)
}
# don't use sandbox in watchdog process
type <- Sys.getenv("RENV_PROCESS_TYPE")
if (type == "watchdog-server")
return()
# if renv was launched with a sandbox path on the library paths,
# then immediately try to activate the sandbox
# https://github.com/rstudio/renv/issues/1565
for (libpath in .libPaths()) {
if (file.exists(file.path(libpath, ".renv-sandbox"))) {
renv_sandbox_activate_impl(sandbox = libpath)
break
}
}
}
renv_sandbox_activate <- function(project = NULL) {
# record start time
before <- Sys.time()
# attempt the activation
status <- catch(renv_sandbox_activate_impl(project))
if (inherits(status, "error"))
warnify(status)
# record end time
after <- Sys.time()
# check for long elapsed time
elapsed <- difftime(after, before, units = "secs")
# if it took too long to activate the sandbox, warn the user
if (elapsed > 10) {
fmt <- heredoc("
renv took longer than expected (%s) to activate the sandbox.
The sandbox can be disabled by setting:
RENV_CONFIG_SANDBOX_ENABLED = FALSE
within an appropriate start-up .Renviron file.
See `?renv::config` for more details.
")
warningf(fmt, renv_difftime_format(elapsed))
}
# return status
status
}
renv_sandbox_activate_impl <- function(project = NULL, sandbox = NULL) {
# lock access to the sandbox
if (config$sandbox.enabled()) {
sandbox <- sandbox %||% renv_sandbox_path(project = project)
lockfile <- paste(sandbox, "lock", sep = ".")
ensure_parent_directory(lockfile)
renv_scope_lock(lockfile)
ensure_directory(sandbox)
}
# get current library paths
oldlibs <- .libPaths()
syslibs <- c(renv_libpaths_site(), renv_libpaths_system())
syslibs <- renv_path_normalize(syslibs)
# override .Library.site
base <- .BaseNamespaceEnv
renv_binding_replace(base, ".Library.site", NULL)
# generate sandbox
if (config$sandbox.enabled()) {
renv_sandbox_generate(sandbox)
renv_binding_replace(base, ".Library", sandbox)
}
# update library paths
newlibs <- renv_vector_diff(oldlibs, syslibs)
renv_libpaths_set(newlibs)
# protect against user profiles that might update library paths
if (config$sandbox.enabled())
renv_sandbox_activate_check(newlibs)
# return new library paths
renv_libpaths_all()
}
renv_sandbox_activated <- function() {
!identical(.Library, renv_libpaths_system())
}
renv_sandbox_activate_check <- function(libs) {
envir <- globalenv()
danger <-
exists(".First", envir = envir, inherits = FALSE) &&
identical(getOption("renv.autoloader.running"), TRUE)
if (!danger)
return(FALSE)
.First <- get(".First", envir = envir, inherits = FALSE)
wrapper <- function() {
# scope the library paths as currently defined
renv_scope_libpaths()
# call the user-defined .First function
status <- tryCatch(.First(), error = warnify)
# double-check if we should restore .First (this is extra
# paranoid but in theory .First could remove itself)
if (identical(wrapper, get(".First", envir = envir)))
assign(".First", .First, envir = envir)
# return result of .First
invisible(status)
}
assign(".First", wrapper, envir = envir)
return(TRUE)
}
renv_sandbox_generate <- function(sandbox) {
# make the library temporarily writable
lock <- getOption("renv.sandbox.locking_enabled", default = TRUE)
if (lock) {
dlog("sandbox", "unlocking sandbox")
renv_sandbox_unlock(sandbox)
}
# find system packages in the system library
priority <- getOption("renv.sandbox.priority", default = c("base", "recommended"))
syspkgs <- installed_packages(
lib.loc = renv_libpaths_system(),
priority = priority
)
# link into sandbox
sources <- with(syspkgs, file.path(LibPath, Package))
targets <- with(syspkgs, file.path(sandbox, Package))
names(targets) <- sources
enumerate(targets, function(source, target) {
if (!renv_file_same(source, target))
renv_file_link(source, target, overwrite = TRUE)
})
# create marker indicating this is a sandbox
# (or, if it already exists, re-create it and update its ctime / mtime)
marker <- file.path(sandbox, ".renv-sandbox")
file.create(marker)
# update mtime on the sandbox itself as well
Sys.setFileTime(sandbox, time = Sys.time())
# make the library unwritable again
if (lock) {
dlog("sandbox", "locking sandbox")
renv_sandbox_lock(sandbox)
}
# return sandbox path
sandbox
}
renv_sandbox_deactivate <- function() {
# get library paths sans .Library, .Library.site
old <- renv_libpaths_all()
syslibs <- renv_path_normalize(c(.Library, .Library.site))
# restore old bindings
base <- .BaseNamespaceEnv
renv_binding_replace(base, ".Library", renv_libpaths_system())
renv_binding_replace(base, ".Library.site", renv_libpaths_site())
# update library paths
new <- renv_vector_diff(old, syslibs)
renv_libpaths_set(new)
renv_libpaths_all()
}
renv_sandbox_task <- function(...) {
# check if we're enabled
if (!renv_sandbox_activated())
return()
# allow opt-out if necessary
enabled <- getOption("renv.sandbox.task", default = TRUE)
if (!enabled)
return()
# get sandbox path
sandbox <- tail(.libPaths(), n = 1L)
# make sure it exists
if (!file.exists(sandbox)) {
warning("the renv sandbox was deleted; it will be re-generated", call. = FALSE)
ensure_directory(sandbox)
renv_sandbox_generate(sandbox)
}
# update the sandbox write time / mtime
Sys.setFileTime(sandbox, time = Sys.time())
}
renv_sandbox_path <- function(project = NULL) {
renv_paths_sandbox(project = project)
}
renv_sandbox_lock <- function(sandbox = NULL, project = NULL) {
sandbox <- sandbox %||% renv_sandbox_path(project = project)
Sys.chmod(sandbox, mode = "0555")
}
renv_sandbox_locked <- function(sandbox = NULL, project = NULL) {
sandbox <- sandbox %||% renv_sandbox_path(project = project)
mode <- suppressWarnings(file.mode(sandbox))
mode == 365L # as.integer(as.octmode("0555"))
}
renv_sandbox_unlock <- function(sandbox = NULL, project = NULL) {
sandbox <- sandbox %||% renv_sandbox_path(project = project)
Sys.chmod(sandbox, mode = "0755")
}
#' The default library sandbox
#'
#' @description
#' An \R installation can have up to three types of library paths available
#' to the user:
#'
#' - The _user library_, where \R packages downloaded and installed by the
#' current user are installed. This library path is only visible to that
#' specific user.
#'
#' - The _site library_, where \R packages maintained by administrators of a
#' system are installed. This library path, if it exists, is visible to all
#' users on the system.
#'
#' - The _default library_, where \R packages distributed with \R itself are
#' installed. This library path is visible to all users on the system.
#'
#' Normally, only so-called "base" and "recommended" packages should be installed
#' in the default library. (You can get a list of these packages with
#' `installed.packages(priority = c("base", "recommended"))`). However, it is
#' possible for users and administrators to install packages into the default
#' library, if the filesystem permissions permit them to do so. (This, for
#' example, is the default behavior on macOS.)
#'
#' Because the site and default libraries are visible to all users, having those
#' accessible in renv projects can potentially break isolation -- that is,
#' if a package were updated in the default library, that update would be visible
#' to all \R projects on the system.
#'
#' To help defend against this, renv uses something called the "sandbox" to
#' isolate renv projects from non-"base" packages that are installed into the
#' default library. When an renv project is loaded, renv will:
#'
#' - Create a new, empty library path (called the "sandbox"),
#'
#' - Link only the "base" and "recommended" packages from the default library
#' into the sandbox,
#'
#' - Mark the sandbox as read-only, so that users are unable to install packages
#' into this library,
#'
#' - Instruct the \R session to use the "sandbox" as the default library.
#'
#' This process is mostly transparent to the user. However, because the sandbox
#' is read-only, if you later need to remove the sandbox, you'll need to reset
#' file permissions manually; for example, with `renv::sandbox$unlock()`.
#'
#' If you'd prefer to keep the sandbox unlocked, you can also set:
#'
#' ```
#' RENV_SANDBOX_LOCKING_ENABLED = FALSE
#' ```
#'
#' in an appropriate startup `.Renviron` or `Renviron.site` file.
#'
#' The sandbox can also be disabled entirely with:
#'
#' ```
#' RENV_CONFIG_SANDBOX_ENABLED = FALSE
#' ```
#'
#' The sandbox library path can also be configured using the `RENV_PATHS_SANDBOX`
#' environment variable: see [paths] for more details.
#'
#' @format NULL
#' @export
sandbox <- list(
path = renv_sandbox_path,
lock = renv_sandbox_lock,
locked = renv_sandbox_locked,
unlock = renv_sandbox_unlock
)
renv/R/hydrate.R 0000644 0001762 0000144 00000030403 14547051446 013222 0 ustar ligges users
#' Copy packages from user libraries to a project library
#'
#' @description
#' `hydrate()` installs missing packages from a user library into the project
#' library. `hydrate()` is called automatically by [init()], and it is rare
#' that you should need it otherwise, as it can easily get your project into
#' an inconsistent state.
#'
#' It may very occasionally be useful to call `hydrate(update = "all")` if you
#' want to update project packages to match those installed in your global
#' library (as opposed to using [update()] which will get the latest versions
#' from CRAN). In this case, you should verify that your code continues to work,
#' then call [snapshot()] to record updated package versions in the lockfile.
#'
#' @inherit renv-params
#'
#' @param packages The set of \R packages to install. When `NULL`, the
#' packages found by [dependencies()] are used.
#'
#' @param library The \R library to be hydrated. When `NULL`, the active
#' library as reported by `.libPaths()` is used.
#'
#' @param repos The \R repositories to be used. If the project depends on any
#' \R packages which cannot be found within the user library paths, then
#' those packages will be installed from these repositories instead.
#'
#' @param update Boolean; should `hydrate()` attempt to update already-installed
#' packages if the requested package is already installed in the project
#' library? Set this to `"all"` if you'd like _all_ packages to be refreshed
#' from the source library if possible.
#'
#' @param sources A vector of library paths where renv should look for packages.
#' When `NULL` (the default), `hydrate()` will look in the system libraries
#' (the user library, the site library and the default library) then the
#' renv cache.
#'
#' If a package is not found in any of these locations, `hydrate()`
#' will try to install it from the active R repositories.
#'
#' @param prompt Boolean; prompt the user before taking any action? Ignored
#' when `report = FALSE`.
#'
#' @param report Boolean; display a report of what packages will be installed
#' by `renv::hydrate()`?
#'
#' @return A named \R list, giving the packages that were used for hydration
#' as well as the set of packages which were not found.
#'
#' @export
#'
#' @keywords internal
#'
#' @examples
#' \dontrun{
#'
#' # hydrate the active library
#' renv::hydrate()
#'
#' }
hydrate <- function(packages = NULL,
...,
library = NULL,
repos = getOption("repos"),
update = FALSE,
sources = NULL,
prompt = interactive(),
report = TRUE,
project = NULL)
{
renv_scope_error_handler()
renv_dots_check(...)
project <- renv_project_resolve(project)
renv_project_lock(project = project)
renv_scope_verbose_if(prompt)
renv_activate_prompt("hydrate", library, prompt, project)
renv_scope_options(repos = repos)
library <- renv_path_normalize(library %||% renv_libpaths_active())
packages <- packages %||% renv_hydrate_packages(project)
# find packages used in this project, and the dependencies of those packages
deps <- renv_hydrate_dependencies(project, packages, sources)
# remove 'renv' since it's managed separately
deps$renv <- NULL
# figure out required packages which aren't installed
missing <- deps[!nzchar(deps)]
# also consider remotes; treat these as 'missing' so we always try to install them
remotes <- renv_project_remotes(project = project, resolve = TRUE)
missing[map_chr(remotes, `[[`, "Package")] <- ""
# remove base + missing packages
base <- renv_packages_base()
packages <- deps[renv_vector_diff(names(deps), c(names(missing), base))]
# figure out if we will copy or link
linkable <- renv_cache_linkable(project = project, library = library)
# get and construct path to library
ensure_directory(library)
# only hydrate with packages that are either not currently installed,
# or (if update = TRUE) the version in the library is newer
packages <- renv_hydrate_filter(packages, library, update)
# inform user about changes
if (report) {
renv_hydrate_report(packages, missing, linkable)
if (length(packages) || length(missing))
cancel_if(prompt && !proceed())
}
# check for nothing to be done
if (empty(packages) && empty(missing)) {
if (report)
writef("- No new packages were discovered in this project; nothing to do.")
return(invisible(list(packages = list(), missing = list())))
}
# copy packages from user library to cache
before <- Sys.time()
if (length(packages)) {
if (linkable)
renv_hydrate_link_packages(packages, library, project)
else
renv_hydrate_copy_packages(packages, library, project)
}
after <- Sys.time()
if (report) {
time <- difftime(after, before, units = "auto")
fmt <- "- Hydrated %s packages in %s."
writef(fmt, length(packages), renv_difftime_format(time))
}
# attempt to install missing packages (if any)
missing <- renv_hydrate_resolve_missing(project, library, remotes, missing)
# we're done!
result <- list(packages = packages, missing = missing)
invisible(result)
}
renv_hydrate_filter <- function(packages, library, update) {
# run filter
keep <- enumerate(
packages,
renv_hydrate_filter_impl,
library = library,
update = update,
FUN.VALUE = logical(1)
)
# filter based on kept packages
packages[keep]
}
renv_hydrate_filter_impl <- function(package, path, library, update) {
# if user has requested hydration of all packages, respect that
if (identical(update, "all"))
return(TRUE)
# is the package already installed in the requested library?
# if not, then we'll want to hydrate this package
# if so, we'll want to compare the version first and
# hydrate only if the requested version is newer than the current
descpath <- file.path(library, package, "DESCRIPTION")
if (file.exists(descpath)) {
desc <- catch(renv_description_read(path = descpath))
if (inherits(desc, "error"))
return(TRUE)
}
# get the current package version
current <- catch(numeric_version(desc[["Version"]]))
if (inherits(current, "error"))
return(TRUE)
# if the package is already installed and we're not updating, stop here
if (identical(update, FALSE))
return(FALSE)
# check to-be-copied package version
requested <- catch({
desc <- renv_description_read(path = path)
numeric_version(desc[["Version"]])
})
# only hydrate with a newer version
requested > current
}
renv_hydrate_packages <- function(project) {
renv_snapshot_dependencies(project, dev = TRUE)
}
renv_hydrate_dependencies <- function(project,
packages = NULL,
libpaths = NULL)
{
ignored <- renv_project_ignored_packages(project = project)
packages <- renv_vector_diff(packages, ignored)
libpaths <- libpaths %||% renv_hydrate_libpaths()
renv_package_dependencies(packages, libpaths = libpaths, project = project)
}
# NOTE: we don't want to look in user / site libraries when testing
# on CRAN, as we may accidentally find versions of packages available
# on CRAN but not that we want to use during tests
renv_hydrate_libpaths <- function() {
conf <- config$hydrate.libpaths()
if (is.character(conf) && length(conf))
conf <- unlist(strsplit(conf, ":", fixed = TRUE))
libpaths <- case(
renv_tests_running() ~ character(),
length(conf) ~ conf,
~ c(
renv_libpaths_default(),
renv_libpaths_user(),
renv_libpaths_site(),
renv_libpaths_system()
)
)
libpaths <- .expand_R_libs_env_var(libpaths)
unique(renv_path_normalize(libpaths))
}
# takes a package called 'package' installed at location 'location',
# copies that package into the cache, and then links from the cache
# to the (private) library 'library'
renv_hydrate_link_package <- function(package, location, library) {
# construct path to cache
record <- catch(renv_snapshot_description(location))
if (inherits(record, "error"))
return(FALSE)
cache <- renv_cache_find(record)
if (!nzchar(cache))
return(FALSE)
# copy package into the cache
if (!file.exists(cache)) {
ensure_parent_directory(cache)
renv_file_copy(location, cache)
}
# link package back from cache to library
target <- file.path(library, package)
ensure_parent_directory(target)
renv_file_link(cache, target, overwrite = TRUE)
}
renv_hydrate_link_packages <- function(packages, library, project) {
if (renv_path_same(library, renv_paths_library(project = project)))
printf("- Linking packages into the project library ... ")
else
printf("- Linking packages into %s ... ", renv_path_pretty(library))
callback <- renv_progress_callback(renv_hydrate_link_package, length(packages))
cached <- enumerate(packages, callback, library = library)
writef("Done!")
cached
}
# takes a package called 'package' installed at location 'location',
# and copies it to the library 'library'
renv_hydrate_copy_package <- function(package, location, library) {
target <- file.path(library, package)
renv_file_copy(location, target, overwrite = TRUE)
}
renv_hydrate_copy_packages <- function(packages, library, project) {
if (renv_path_same(library, renv_paths_library(project = project)))
printf("- Copying packages into the project library ... ")
else
printf("- Copying packages into %s ... ", renv_path_pretty(library))
callback <- renv_progress_callback(renv_hydrate_copy_package, length(packages))
copied <- enumerate(packages, callback, library = library)
writef("Done!")
copied
}
renv_hydrate_resolve_missing <- function(project, library, remotes, missing) {
# make sure requested library is made active
#
# note that we only want to place the requested library on the library path;
# we want to ensure that all required packages are hydrated into the
# requested library
#
# https://github.com/rstudio/renv/issues/1177
ensure_directory(library)
renv_scope_libpaths(library)
packages <- names(missing)
writef("- Resolving missing dependencies ... ")
# define a custom error handler for packages which we cannot retrieve
errors <- stack()
handler <- function(package, action) {
error <- catch(action)
if (inherits(error, "error"))
errors$push(list(package = package, error = error))
}
# perform the restore
renv_scope_restore(
project = project,
library = library,
packages = packages,
records = remotes,
handler = handler
)
records <- retrieve(packages)
renv_install_impl(records)
# if we failed to restore anything, warn the user
data <- errors$data()
if (empty(data))
return()
if (renv_verbose()) {
text <- map_chr(data, function(item) {
package <- item$package
message <- conditionMessage(item$error)
short <- trunc(paste(message, collapse = ";"), 60L)
sprintf("[%s]: %s", package, short)
})
caution_bullets(
"The following package(s) were not installed successfully:",
text,
"You may need to manually download and install these packages."
)
}
invisible(data)
}
renv_hydrate_report <- function(packages, na, linkable) {
if (renv_bootstrap_tests_running())
return()
if (length(packages)) {
# this is mostly a hacky way to get a list of records that the existing
# record pretty-printer can handle in a clean way
records <- enumerate(packages, function(package, library) {
descpath <- file.path(library, "DESCRIPTION")
record <- renv_snapshot_description(descpath)
record$Repository <- NULL
record$Source <- renv_path_aliased(dirname(library))
record
})
preamble <- "The following packages were discovered:"
postamble <- sprintf(
"They will be %s into the project library.",
if (linkable) "linked" else "copied"
)
formatter <- function(lhs, rhs) {
renv_record_format_short(rhs, versioned = TRUE)
}
renv_pretty_print_records_pair(
preamble = preamble,
old = list(),
new = records,
postamble = postamble,
formatter = formatter
)
}
if (length(na)) {
caution_bullets(
"The following packages are used in this project, but not available locally:",
csort(names(na)),
"renv will attempt to download and install these packages."
)
}
}
renv/R/envvars.R 0000644 0001762 0000144 00000003653 14405756777 013271 0 ustar ligges users
renv_envvars_list <- function() {
c(
"R_PROFILE", "R_PROFILE_USER",
"R_ENVIRON", "R_ENVIRON_USER",
"R_LIBS_USER", "R_LIBS_SITE", "R_LIBS"
)
}
renv_envvars_save <- function() {
# save the common set of environment variables
keys <- renv_envvars_list()
vals <- Sys.getenv(keys, unset = "")
# check for defaults that have already been set
defkeys <- paste("RENV_DEFAULT", keys, sep = "_")
defvals <- Sys.getenv(defkeys, unset = NA)
if (any(!is.na(defvals)))
return(FALSE)
# prepare defaults
env <- vals
names(env) <- defkeys
do.call(Sys.setenv, as.list(env))
TRUE
}
renv_envvars_restore <- function() {
# read defaults
keys <- renv_envvars_list()
defkeys <- paste("RENV_DEFAULT", renv_envvars_list(), sep = "_")
defvals <- Sys.getenv(defkeys, unset = "")
# remove previously-unset environment variables
missing <- defvals == ""
Sys.unsetenv(keys[missing])
# restore old values for envvars
existing <- as.list(defvals[!missing])
if (length(existing)) {
names(existing) <- sub("^RENV_DEFAULT_", "", names(existing))
do.call(Sys.setenv, existing)
}
# remove saved RENV_DEFAULT values
Sys.unsetenv(defkeys)
TRUE
}
renv_envvars_init <- function() {
renv_envvars_normalize()
}
renv_envvars_normalize <- function() {
Sys.setenv(R_LIBS_SITE = .expand_R_libs_env_var(Sys.getenv("R_LIBS_SITE")))
Sys.setenv(R_LIBS_USER = .expand_R_libs_env_var(Sys.getenv("R_LIBS_USER")))
keys <- c(
"RENV_PATHS_ROOT",
"RENV_PATHS_LIBRARY",
"RENV_PATHS_LIBRARY_ROOT",
"RENV_PATHS_LIBRARY_STAGING",
"RENV_PATHS_LOCAL",
"RENV_PATHS_CELLAR",
"RENV_PATHS_SOURCE",
"RENV_PATHS_BINARY",
"RENV_PATHS_CACHE",
"RENV_PATHS_RTOOLS",
"RENV_PATHS_EXTSOFT",
"RENV_PATHS_MRAN"
)
envvars <- as.list(keep(Sys.getenv(), keys))
if (empty(envvars))
return()
args <- lapply(envvars, renv_path_normalize)
do.call(Sys.setenv, args)
}
renv/R/download.R 0000644 0001762 0000144 00000055741 14604445611 013400 0 ustar ligges users
# download a file from 'url' to file 'destfile'. the 'type'
# argument tells us the remote type, which is used to motivate
# what form of authentication is appropriate; the 'quiet'
# argument is used to display / suppress output. use 'headers'
# (as a named character vector) to supply additional headers
download <- function(url,
destfile,
preamble = NULL,
type = NULL,
quiet = FALSE,
headers = NULL)
{
# allow for user-defined overrides
override <- getOption("renv.download.override")
if (is.function(override)) {
result <- catch(
override(
url = url,
destfile = destfile,
quiet = quiet,
mode = "wb",
headers = headers
)
)
if (inherits(result, "error"))
renv_download_error(result, "%s", conditionMessage(result))
if (!file.exists(destfile))
renv_download_error(url, "%s does not exist", renv_path_pretty(destfile))
return(destfile)
}
if (quiet)
renv_scope_options(renv.verbose = FALSE)
# normalize separators (file URIs should normally use forward
# slashes, even on Windows where the native separator is backslash)
url <- chartr("\\", "/", url)
destfile <- chartr("\\", "/", destfile)
# notify user we're about to try downloading
preamble <- preamble %||% sprintf("- Downloading '%s' ... ", url)
printf(preamble)
# add custom headers as appropriate for the URL
custom <- renv_download_custom_headers(url)
headers[names(custom)] <- custom
# handle local files by just copying the file
if (renv_download_local(url, destfile, headers))
return(destfile)
# on Windows, try using our local curl binary if available
renv_scope_downloader()
# if the file already exists, compare its size with
# the server's reported size for that file
info <- renv_file_info(destfile)
if (identical(info$isdir, FALSE)) {
size <- renv_download_size(url, type, headers)
if (info$size == size) {
writef("OK [file is up to date]")
return(destfile)
}
}
# back up a pre-existing file if necessary
callback <- renv_file_backup(destfile)
defer(callback())
# form path to temporary file
tempfile <- renv_scope_tempfile(tmpdir = dirname(destfile))
# request the download
before <- Sys.time()
status <- renv_download_impl(
url = url,
destfile = tempfile,
type = type,
request = "GET",
headers = headers
)
after <- Sys.time()
# check for failure
if (inherits(status, "condition"))
renv_download_error(url, "%s", conditionMessage(status))
if (status != 0L)
renv_download_error(url, "error code %i", status)
if (!file.exists(tempfile))
renv_download_error(url, "%s", "unknown reason")
# double-check archives are readable
status <- renv_download_check_archive(tempfile)
if (inherits(status, "error"))
renv_download_error(url, "%s", "archive cannot be read")
# everything looks ok: report success
elapsed <- difftime(after, before, units = "auto")
renv_download_report(elapsed, tempfile)
# move the file to the requested location
renv_file_move(tempfile, destfile)
# one final sanity check
if (!file.exists(destfile)) {
fmt <- "could not move %s to %s"
msg <- sprintf(fmt, renv_path_pretty(tempfile), renv_path_pretty(destfile))
renv_download_error(url, msg)
}
# and return path to successfully retrieved file
destfile
}
# NOTE: only 'GET' and 'HEAD' are supported
#
# each downloader should return 0 on success
renv_download_impl <- function(url, destfile, type = NULL, request = "GET", headers = NULL) {
# normalize separators (file URIs should normally use forward
# slashes, even on Windows where the native separator is backslash)
url <- chartr("\\", "/", url)
destfile <- chartr("\\", "/", destfile)
# check that the destination file is writable
if (!renv_file_writable(destfile)) {
fmt <- "destination path '%s' is not writable; cannot proceed"
stopf(fmt, renv_path_pretty(destfile))
}
# select the appropriate downloader
downloader <- switch(
renv_download_method(),
curl = renv_download_curl,
wget = renv_download_wget,
renv_download_default
)
# disable warnings in this scope; it is not safe to try and catch
# warnings as R will try to clean up open sockets after emitting
# warnings, and catching a warning would hence prevent that
# https://bugs.r-project.org/show_bug.cgi?id=18634
catch(
withCallingHandlers(
downloader(url, destfile, type, request, headers),
warning = function(cnd) invokeRestart("muffleWarning")
)
)
}
renv_download_default_mode <- function(url, method) {
mode <- "wb"
fixup <-
renv_platform_windows() &&
identical(method, "wininet") &&
substring(url, 1L, 5L) == "file:"
if (fixup)
mode <- "w+b"
mode
}
renv_download_default <- function(url, destfile, type, request, headers) {
# custom request types are not supported with the default downloader
if (request != "GET")
stopf("the default downloader does not support %s requests", request)
# try and ensure headers are set for older versions of R
auth <- renv_download_auth(url, type)
headers[names(auth)] <- auth
renv_download_default_agent_scope(headers)
# on Windows, prefer 'wininet' as most users will have already configured
# authentication etc. to work with this protocol
methods <- c(
Sys.getenv("RENV_DOWNLOAD_METHOD", unset = NA),
Sys.getenv("RENV_DOWNLOAD_FILE_METHOD", unset = NA),
if (renv_platform_windows()) "wininet" else "auto"
)
method <- Find(Negate(is.na), methods)
# headers _must_ be NULL rather than zero-length character
if (length(headers) == 0)
headers <- NULL
mode <- renv_download_default_mode(url, method)
# handle absence of 'headers' argument in older versions of R
args <- list(url = url,
destfile = destfile,
method = method,
headers = headers,
mode = mode,
quiet = TRUE)
fmls <- formals(download.file)
args <- keep(args, names(fmls))
renv_download_trace_begin(url, method)
if (renv_download_trace())
str(args)
do.call(download.file, args)
}
renv_download_default_agent_scope <- function(headers, scope = parent.frame()) {
if (empty(headers))
return(FALSE)
if (getRversion() >= "3.6.0")
return(FALSE)
renv_download_default_agent_scope_impl(headers, scope)
}
renv_download_default_agent_scope_impl <- function(headers, scope = parent.frame()) {
utils <- asNamespace("utils")
makeUserAgent <- utils$makeUserAgent
ok <-
is.function(makeUserAgent) &&
identical(formals(makeUserAgent), pairlist(format = TRUE))
if (!ok)
return(FALSE)
agent <- makeUserAgent(FALSE)
all <- c("User-Agent" = agent, headers)
headertext <- paste0(names(all), ": ", all, "\r\n", collapse = "")
renv_scope_binding(utils, "makeUserAgent", function(format = TRUE) {
if (format) headertext else agent
}, scope = scope)
return(TRUE)
}
renv_download_curl <- function(url, destfile, type, request, headers) {
renv_download_trace_begin(url, "curl")
configfile <- renv_scope_tempfile("renv-download-config-")
fields <- c(
"user-agent" = renv_http_useragent(),
"url" = url,
"output" = destfile
)
# set connect timeout
timeout <- config$connect.timeout()
if (is.numeric(timeout))
fields[["connect-timeout"]] <- timeout
# set number of retries
retries <- config$connect.retry()
if (is.numeric(retries))
fields[["retry"]] <- retries
# set up authentication headers
auth <- renv_download_auth(url, type)
if (length(auth)) {
authtext <- paste(names(auth), auth, sep = ": ")
names(authtext) <- rep.int("header", times = length(authtext))
fields <- c(fields, authtext)
}
# add other custom headers
if (length(headers)) {
lines <- paste(names(headers), headers, sep = ": ")
names(lines) <- rep.int("header", times = length(lines))
fields <- c(fields, lines)
}
# join together
keys <- names(fields)
vals <- renv_json_quote(fields)
text <- paste(keys, vals, sep = " = ")
# remove duplicated authorization headers
dupes <- startswith(text, "header =") & duplicated(text)
text <- text[!dupes]
# add in stand-along flags
flags <- c("location", "fail", "silent", "show-error")
if (request == "HEAD")
flags <- c(flags, "head", "include")
# put it all together
text <- c(flags, text)
writeLines(text, con = configfile)
renv_download_trace_request(text)
# generate the arguments to be passed to 'curl'
args <- stack()
# include anything provided explicitly in 'download.file.extra' here
if (identical(getOption("download.file.method"), "curl")) {
extra <- getOption("download.file.extra")
if (length(extra))
args$push(extra)
}
# https://github.com/rstudio/renv/issues/1739
if (renv_platform_windows()) {
enabled <- Sys.getenv("R_LIBCURL_SSL_REVOKE_BEST_EFFORT", unset = "TRUE")
if (truthy(enabled))
args$push("--ssl-revoke-best-effort")
}
# add in any user configuration files
userconfig <- getOption(
"renv.curl.config",
renv_download_curl_config()
)
for (entry in userconfig)
if (file.exists(entry))
args$push("--config", renv_shell_path(entry))
# add in our own config file (the actual request)
args$push("--config", renv_shell_path(configfile))
# perform the download
curl <- renv_curl_exe()
output <- suppressWarnings(
system2(curl, args$data(), stdout = TRUE, stderr = TRUE)
)
renv_download_trace_result(output)
# report non-zero status as warning
status <- attr(output, "status", exact = TRUE) %||% 0L
if (status != 0L)
warning(output, call. = FALSE)
status
}
renv_download_curl_config <- function() {
rc <- if (renv_platform_windows()) "_curlrc" else ".curlrc"
homes <- c(
Sys.getenv("CURL_HOME"),
Sys.getenv("HOME"),
Sys.getenv("R_USER"),
path.expand("~/")
)
# nocov start
if (renv_platform_windows()) {
extra <- c(
Sys.getenv("APPDATA"),
file.path(Sys.getenv("USERPROFILE"), "Application Data"),
dirname(Sys.which("curl"))
)
homes <- c(homes, extra)
}
# nocov end
homes <- Filter(nzchar, homes)
for (home in homes) {
path <- file.path(home, rc)
if (file.exists(path))
return(path)
}
NULL
}
# nocov start
renv_download_wget <- function(url, destfile, type, request, headers) {
renv_download_trace_begin(url, "wget")
configfile <- renv_scope_tempfile("renv-download-config-")
fields <- c(
"user-agent" = renv_http_useragent(),
"quiet" = "on"
)
auth <- renv_download_auth(url, type)
if (length(auth)) {
authtext <- paste(names(auth), auth, sep = ": ")
names(authtext) <- "header"
fields <- c(fields, authtext)
}
if (length(headers)) {
lines <- paste(names(headers), headers, sep = ": ")
names(lines) <- "header"
fields <- c(fields, lines)
}
keys <- names(fields)
vals <- unlist(fields)
text <- paste(keys, vals, sep = " = ")
writeLines(text, con = configfile)
renv_download_trace_request(text)
args <- stack()
if (identical(getOption("download.file.method"), "wget")) {
extra <- getOption("download.file.extra")
if (length(extra))
args$push(extra)
}
args$push("--config", renv_shell_path(configfile))
# NOTE: '-O' does not write headers to file; we need to manually redirect
# in that case
status <- if (request == "HEAD") {
args$push("--server-response", "--spider")
args$push(">", renv_shell_path(destfile), "2>&1")
cmdline <- paste("wget", paste(args$data(), collapse = " "))
return(suppressWarnings(system(cmdline)))
}
args$push("-O", renv_shell_path(destfile))
args$push(renv_shell_quote(url))
output <- suppressWarnings(
system2("wget", args$data(), stdout = TRUE, stderr = TRUE)
)
renv_download_trace_result(output)
status <- attr(output, "status", exact = TRUE) %||% 0L
if (status != 0L)
warning(output, call. = FALSE)
status
}
# nocov end
renv_download_auth_type <- function(url) {
github_hosts <- c(
"https://api.github.com/",
"https://raw.githubusercontent.com/"
)
for (host in github_hosts)
if (startswith(url, host))
return("github")
gitlab_hosts <- c(
"https://gitlab.com/"
)
for (host in gitlab_hosts)
if (startswith(url, host))
return("gitlab")
bitbucket_hosts <- c(
"https://api.bitbucket.org/",
"https://bitbucket.org/"
)
for (host in bitbucket_hosts)
if (startswith(url, host))
return("bitbucket")
"unknown"
}
renv_download_auth <- function(url, type) {
type <- tolower(type %||% renv_download_auth_type(url))
switch(
type,
bitbucket = renv_download_auth_bitbucket(),
github = renv_download_auth_github(url),
gitlab = renv_download_auth_gitlab(),
character()
)
}
renv_download_auth_bitbucket <- function() {
user <-
Sys.getenv("BITBUCKET_USER", unset = NA) %NA%
Sys.getenv("BITBUCKET_USERNAME", unset = NA)
pass <-
Sys.getenv("BITBUCKET_PASS", unset = NA) %NA%
Sys.getenv("BITBUCKET_PASSWORD", unset = NA)
if (is.na(user) || is.na(pass))
return(character())
userpass <- paste(user, pass, sep = ":")
c("Authorization" = paste("Basic", renv_base64_encode(userpass)))
}
renv_download_auth_github <- function(url) {
pat <- renv_download_auth_github_pat(url)
if (is.null(pat))
return(character())
c("Authorization" = paste("token", pat))
}
renv_download_auth_github_pat <- function(url) {
# check for an existing PAT
pat <- Sys.getenv("GITHUB_PAT", unset = NA)
if (!is.na(pat))
return(pat)
# if gitcreds is available, try to use it
gitcreds <-
getOption("renv.gitcreds.enabled", default = TRUE) &&
requireNamespace("gitcreds", quietly = TRUE)
if (gitcreds) {
# ensure URL has protocol pre-pended
url <- renv_retrieve_origin(url)
# request token
dlog("download", "requesting git credentials for url '%s'", url)
token <- tryCatch(
gitcreds::gitcreds_get(url),
error = function(cnd) {
warning(conditionMessage(cnd))
NULL
}
)
# use if available
if (!is.null(token))
return(token$password)
}
# ask the user to set a GITHUB_PAT
if (once()) {
writeLines(c(
"- GitHub authentication credentials are not available.",
"- Please set GITHUB_PAT, or ensure the 'gitcreds' package is installed.",
"- See https://usethis.r-lib.org/articles/git-credentials.html for more details."
))
}
}
renv_download_auth_gitlab <- function() {
pat <- Sys.getenv("GITLAB_PAT", unset = NA)
if (is.na(pat))
return(character())
c("Private-Token" = pat)
}
renv_download_headers <- function(url, type, headers) {
# check for compatible download method
method <- renv_download_method()
if (!method %in% c("libcurl", "curl", "wget"))
return(list())
# perform the download
file <- renv_scope_tempfile("renv-headers-")
status <- renv_download_impl(
url = url,
destfile = file,
type = type,
request = "HEAD",
headers = headers
)
# check for failure
failed <-
inherits(status, "error") ||
!identical(status, 0L) ||
!file.exists(file)
if (failed) {
unlink(file)
return(list())
}
# read the downloaded headers
contents <- read(file)
# if redirects were required, each set of headers will
# be reported separately, so just report the final set
# of headers (ie: ignore redirects)
splat <- strsplit(contents, "\n\n", fixed = TRUE)[[1]]
text <- strsplit(splat[[length(splat)]], "\n", fixed = TRUE)[[1]]
# keep only header lines
lines <- grep(":", text, fixed = TRUE, value = TRUE)
headers <- catch(renv_properties_read(text = lines))
names(headers) <- tolower(names(headers))
if (inherits(headers, "error"))
return(list())
headers
}
renv_download_size <- function(url, type = NULL, headers = NULL) {
memoize(
key = url,
value = renv_download_size_impl(url, type, headers)
)
}
renv_download_size_impl <- function(url, type = NULL, headers = NULL) {
headers <- catch(renv_download_headers(url, type, headers))
if (inherits(headers, "error"))
return(-1L)
size <- headers[["x-gitlab-size"]]
if (!is.null(size))
return(as.numeric(size))
size <- headers[["content-length"]]
if (!is.null(size))
return(as.numeric(size))
return(-1L)
}
# select an appropriate download file method. we prefer curl
# when available as it's the most user-customizable of all the
# download methods; when not available, we fall back to libcurl
# and wget (in that order). note that we don't want to use the
# internal or wininet downloaders as we cannot set custom headers
# with those methods. users can force a method with the
# RENV_DOWNLOAD_FILE_METHOD environment variable but we generally
# want to override a user-specified 'download.file.method'
renv_download_method <- function() {
method <- Sys.getenv("RENV_DOWNLOAD_METHOD", unset = NA)
if (!is.na(method))
return(method)
method <- Sys.getenv("RENV_DOWNLOAD_FILE_METHOD", unset = NA)
if (!is.na(method))
return(method)
# prefer curl if available
if (nzchar(Sys.which("curl")))
return("curl")
# if curl is not available, use libcurl if available
libcurl <- capabilities("libcurl")
if (length(libcurl) && libcurl)
return("libcurl")
# on windows, just use wininet here
if (renv_platform_windows())
return("wininet")
# if neither curl nor libcurl is available, prefer wget
if (nzchar(Sys.which("wget")))
return("wget")
# all else fails, use the internal downloader
"internal"
}
renv_download_report <- function(elapsed, file) {
if (!renv_verbose())
return()
info <- renv_file_info(file)
size <- if (testing())
"XXXX bytes"
else
structure(info$size, class = "object_size")
renv_report_ok(
message = format(size, units = "auto"),
elapsed = elapsed
)
}
renv_download_check_archive <- function(destfile) {
# validate the file exists
if (!file.exists(destfile))
return(FALSE)
# validate archive type
type <- renv_archive_type(destfile)
if (type == "unknown")
return(FALSE)
# try listing files in the archive
tryCatch({renv_archive_list(destfile); TRUE}, error = identity)
}
renv_download_local <- function(url, destfile, headers) {
# only ever used for downloads from file URIs and server URIs
ok <-
grepl("^file:", url) ||
!grepl("^[a-zA-Z]+://", url)
if (!ok)
return(FALSE)
methods <- list(
renv_download_local_copy,
renv_download_local_default
)
for (method in methods) {
# perform the copy
before <- Sys.time()
status <- catch(method(url, destfile, headers))
after <- Sys.time()
# check for success
if (!identical(status, TRUE))
next
# report download summary
elapsed <- difftime(after, before, units = "auto")
renv_download_report(elapsed, destfile)
return(TRUE)
}
FALSE
}
renv_download_local_copy <- function(url, destfile, headers) {
# remove file prefix (to get path to local / server file)
url <- case(
startswith(url, "file:///") ~ substring(url, 8L),
startswith(url, "file://") ~ substring(url, 6L),
startswith(url, "file:") ~ substring(url, 6L),
TRUE ~ url
)
# fix up file URIs to local paths on Windows
if (renv_platform_windows()) {
badpath <- grepl("^/[a-zA-Z]:", url)
if (badpath)
url <- substring(url, 2L)
}
# attempt to copy
ensure_parent_directory(destfile)
status <- catchall(renv_file_copy(url, destfile, overwrite = TRUE))
if (!identical(status, TRUE))
return(FALSE)
TRUE
}
renv_download_local_default <- function(url, destfile, headers) {
status <- renv_download_impl(
url = url,
destfile = destfile,
headers = headers
)
identical(status, 0L)
}
renv_download_custom_headers <- function(url) {
renv_bootstrap_download_custom_headers(url)
}
renv_download_available <- function(url) {
# normalize separators (file URIs should normally use forward
# slashes, even on Windows where the native separator is backslash)
url <- chartr("\\", "/", url)
# on Windows, try using our local curl binary if available
renv_scope_downloader()
# if we're not using curl, then use fallback method
method <- renv_download_method()
if (!identical(method, "curl"))
return(renv_download_available_fallback(url))
# otherwise, try a couple candidate methods
methods <- list(
renv_download_available_headers,
renv_download_available_range
)
for (method in methods) {
result <- catch(method(url))
if (identical(result, TRUE))
return(TRUE)
}
FALSE
}
renv_download_available_headers <- function(url) {
status <- catchall(
renv_download_headers(
url = url,
type = NULL,
headers = renv_download_custom_headers(url)
)
)
if (inherits(status, "condition"))
return(FALSE)
is.list(status) && length(status)
}
renv_download_available_range <- function(url) {
destfile <- renv_scope_tempfile("renv-download-")
# instruct curl to request only first byte
extra <- c(
if (identical(getOption("download.file.method"), "curl"))
getOption("download.file.extra"),
"-r 0-0"
)
renv_scope_options(download.file.extra = paste(extra, collapse = " "))
# perform the download
status <- catchall(
renv_download_curl(
url = url,
destfile = destfile,
type = NULL,
request = "GET",
headers = renv_download_custom_headers(url)
)
)
if (inherits(status, "condition"))
return(FALSE)
# check for success
identical(status, 0L)
}
renv_download_available_fallback <- function(url) {
destfile <- renv_scope_tempfile("renv-download-")
# just try downloading the requested URL
status <- catchall(
renv_download_impl(
url = url,
destfile = destfile,
type = NULL,
request = "GET",
headers = renv_download_custom_headers(url)
)
)
if (inherits(status, "condition"))
return(FALSE)
identical(status, 0L)
}
renv_download_error <- function(url, fmt, ...) {
msg <- sprintf(fmt, ...)
writef("\tERROR [%s]", msg)
stopf("error downloading '%s' [%s]", url, msg, call. = FALSE)
}
renv_download_trace <- function() {
getOption("renv.download.trace", default = FALSE)
}
renv_download_trace_begin <- function(url, type) {
if (!renv_download_trace())
return()
fmt <- "Downloading '%s' [%s]"
msg <- sprintf(fmt, url, type)
title <- header(msg, n = 78L)
writef(c("", title, ""))
}
renv_download_trace_request <- function(text) {
if (!renv_download_trace())
return()
title <- header("Request", n = 78L, prefix = "##")
writef(c(title, text, ""))
}
renv_download_trace_result <- function(output) {
if (!renv_download_trace())
return()
title <- header("Output", prefix = "##", n = 78L)
text <- if (empty(output)) "[no output generated]" else output
all <- c(title, text, "")
writef(all)
status <- attr(output, "status", exact = TRUE) %||% 0L
title <- header("Status", prefix = "##", n = 78L)
all <- c(title, status, "")
writef(all)
}
renv/R/nexus.R 0000644 0001762 0000144 00000000435 14311165205 012712 0 ustar ligges users
renv_nexus_enabled <- function(repo) {
# first, check a global option
enabled <- getOption("renv.nexus.enabled", default = FALSE)
if (enabled)
return(TRUE)
# otherwise, check cached repository information
info <- renv_repos_info(repo)
identical(info$nexus, TRUE)
}
renv/R/rebuild.R 0000644 0001762 0000144 00000004766 14464550375 013230 0 ustar ligges users
#' Rebuild the packages in your project library
#'
#' Rebuild and reinstall packages in your library. This can be useful as a
#' diagnostic tool -- for example, if you find that one or more of your
#' packages fail to load, and you want to ensure that you are starting from a
#' clean slate.
#'
#' @inherit renv-params
#'
#' @param packages The package(s) to be rebuilt. When `NULL`, all packages
#' in the library will be reinstalled.
#'
#' @param recursive Boolean; should dependencies of packages be rebuilt
#' recursively? Defaults to `TRUE`.
#'
#' @return A named list of package records which were installed by renv.
#'
#' @export
#'
#' @examples
#' \dontrun{
#'
#' # rebuild the 'dplyr' package + all of its dependencies
#' renv::rebuild("dplyr", recursive = TRUE)
#'
#' # rebuild only 'dplyr'
#' renv::rebuild("dplyr", recursive = FALSE)
#'
#' }
rebuild <- function(packages = NULL,
recursive = TRUE,
...,
type = NULL,
prompt = interactive(),
library = NULL,
project = NULL)
{
renv_consent_check()
renv_scope_error_handler()
renv_dots_check(...)
project <- renv_project_resolve(project)
renv_project_lock(project = project)
renv_scope_verbose_if(prompt)
libpaths <- renv_libpaths_resolve(library)
library <- nth(libpaths, 1L)
# get collection of packages currently installed
records <- renv_snapshot_libpaths(libpaths = libpaths, project = project)
packages <- setdiff(packages %||% names(records), "renv")
# add in missing packages
for (package in packages) {
records[[package]] <- records[[package]] %||%
renv_available_packages_latest(package)
}
# make sure records are named
names(records) <- map_chr(records, `[[`, "Package")
if (empty(records)) {
writef("- There are no packages currently installed -- nothing to rebuild.")
return(invisible(records))
}
# apply any overrides
records <- renv_records_override(records)
# notify the user
preamble <- if (recursive)
"The following package(s) and their dependencies will be reinstalled:"
else
"The following package(s) will be reinstalled:"
renv_pretty_print_records(preamble, records[packages])
cancel_if(prompt && !proceed())
# figure out rebuild parameter
rebuild <- if (recursive) NA else packages
# perform the install
install(
packages = records[packages],
library = libpaths,
type = type,
rebuild = rebuild,
project = project
)
}
renv/R/lockfile-api.R 0000644 0001762 0000144 00000006374 14547051446 014133 0 ustar ligges users
# NOTE: These functions are used by the 'dockerfiler' package, even though
# they are not exported. We retain these functions here just to avoid issues
# during CRAN submission. We'll consider removing them in a future release.
renv_lockfile_api <- function(lockfile = NULL) {
.lockfile <- lockfile
.self <- new.env(parent = emptyenv())
.self$repos <- function(..., .repos = NULL) {
if (nargs() == 0) {
repos <- .lockfile$R$Repositories
return(repos)
}
repos <- .repos %||% list(...)
if (is.null(names(repos)) || "" %in% names(repos))
stop("repositories must all be named", call. = FALSE)
.lockfile$R$Repositories <<- as.list(convert(repos, "character"))
invisible(.self)
}
.self$version <- function(..., .version = NULL) {
if (nargs() == 0) {
version <- .lockfile$R$Version
return(version)
}
version <- .version %||% c(...)
if (length(version) > 1) {
stop("Version should be length 1 character e.g. `\"3.6.3\"`")
}
.lockfile$R$Version <<- version
invisible(.self)
}
.self$add <- function(..., .list = NULL) {
records <- renv_lockfile_records(.lockfile)
dots <- .list %||% list(...)
enumerate(dots, function(package, remote) {
resolved <- renv_remotes_resolve(remote)
records[[package]] <<- resolved
})
renv_lockfile_records(.lockfile) <<- records
invisible(.self)
}
.self$remove <- function(packages) {
records <- renv_lockfile_records(.lockfile) %>% omit(packages)
renv_lockfile_records(.lockfile) <<- records
invisible(.self)
}
.self$write <- function(file = stdout()) {
renv_lockfile_write(.lockfile, file = file)
invisible(.self)
}
.self$data <- function() {
.lockfile
}
class(.self) <- "renv_lockfile_api"
.self
}
#' Programmatically Create and Modify a Lockfile
#'
#' This function provides an API for creating and modifying `renv` lockfiles.
#' This can be useful when you'd like to programmatically generate or modify
#' a lockfile -- for example, because you want to update or change a package
#' record in an existing lockfile.
#'
#' @inheritParams renv-params
#'
#' @param file The path to an existing lockfile. When no lockfile is provided,
#' a new one will be created based on the current project context. If you
#' want to create a blank lockfile, use `file = NA` instead.
#'
#' @seealso \code{\link{lockfiles}}, for a description of the structure of an
#' `renv` lockfile.
#'
#' @examples
#'
#' \dontrun{
#'
#' lock <- lockfile("renv.lock")
#'
#' # set the repositories for a lockfile
#' lock$repos(CRAN = "https://cran.r-project.org")
#'
#' # depend on digest 0.6.22
#' lock$add(digest = "digest@@0.6.22")
#'
#' # write to file
#' lock$write("renv.lock")
#'
#' }
#'
#' @keywords internal
#' @rdname lockfile-api
#' @name lockfile-api
#'
lockfile <- function(file = NULL, project = NULL) {
project <- renv_project_resolve(project)
renv_scope_error_handler()
lock <- if (is.null(file)) {
renv_lockfile_create(
project = project,
libpaths = renv_libpaths_all(),
type = settings$snapshot.type(project = project)
)
} else if (is.na(file)) {
renv_lockfile_init(project)
} else {
renv_lockfile_read(file = file)
}
renv_lockfile_api(lock)
}
renv/R/pretty.R 0000644 0001762 0000144 00000005014 14547051446 013111 0 ustar ligges users
renv_pretty_print_records <- function(preamble, records, postamble = NULL) {
if (empty(records))
return(invisible(NULL))
if (!renv_verbose())
return(invisible(NULL))
# NOTE: use 'sort()' rather than 'csort()' here so that
# printed output is sorted in the expected way in the users locale
# https://github.com/rstudio/renv/issues/1289
names(records) <- names(records) %||% map_chr(records, `[[`, "Package")
records <- records[sort(names(records))]
packages <- names(records)
descs <- map_chr(records, renv_record_format_short)
text <- sprintf("- %s [%s]", format(packages), descs)
all <- c(preamble, text, postamble, if (length(postamble)) "")
renv_caution_impl(all)
}
renv_pretty_print_records_pair <- function(preamble,
old,
new,
postamble = NULL,
formatter = NULL)
{
formatter <- formatter %||% renv_record_format_pair
all <- c(
c(preamble, ""),
renv_pretty_print_records_pair_impl(old, new, formatter),
if (length(postamble)) c(postamble, "")
)
renv_caution_impl(all)
}
renv_pretty_print_records_pair_impl <- function(old, new, formatter) {
# NOTE: use 'sort()' rather than 'csort()' here so that
# printed output is sorted in the expected way in the users locale
# https://github.com/rstudio/renv/issues/1289
all <- sort(union(names(old), names(new)))
# compute groups
groups <- map_chr(all, function(package) {
lhs <- old[[package]]; rhs <- new[[package]]
case(
is.null(lhs$Source) ~ rhs$Repository %||% rhs$Source,
is.null(rhs$Source) ~ lhs$Repository %||% lhs$Source,
!is.null(rhs$Repository) ~ rhs$Repository,
!is.null(rhs$Source) ~ rhs$Source
)
})
n <- max(nchar(all))
# iterate over each group and print
uapply(csort(unique(groups)), function(group) {
lhs <- renv_records_select(old, groups, group)
rhs <- renv_records_select(new, groups, group)
nms <- union(names(lhs), names(rhs))
text <- map_chr(nms, function(nm) {
formatter(lhs[[nm]], rhs[[nm]])
})
if (group == "unknown")
group <- "(Unknown Source)"
c(
header(group),
paste("-", format(nms, width = n), " ", text),
""
)
})
}
# NOTE: Used by vetiver, so perhaps is part of the API.
# We should think of a cleaner way of exposing this.
# https://github.com/rstudio/renv/issues/1413
renv_pretty_print_impl <- renv_caution_impl
renv/R/cleanse.R 0000644 0001762 0000144 00000003162 14567711254 013200 0 ustar ligges users
# tools for cleaning up renv's cached data
cleanse <- function() {
enabled <- Sys.getenv("RENV_CLEANSE_ENABLED", unset = "TRUE")
if (!truthy(enabled))
return(invisible(FALSE))
# remove unused sandbox directories
renv_cleanse_sandbox(path = renv_paths_sandbox())
# remove empty directories in the root directory
# we can't do this on Windows, as some empty directories
# might also be broken junctions, and we want to keep
# those around so we can inform the user that they need
# to repair that
if (!renv_platform_windows())
renv_cleanse_empty(path = renv_paths_root())
invisible(TRUE)
}
renv_cleanse_sandbox <- function(path) {
# get sandbox root path
root <- dirname(path)
if (!file.exists(root))
return(FALSE)
# list directories within
dirs <- list.files(root, full.names = TRUE)
# look for apparently-unused sandbox directories
info <- suppressWarnings(file.info(dirs, extra_cols = FALSE))
age <- difftime(Sys.time(), info$mtime, units = "days")
old <- age >= 7
# remove the old sandbox directories
unlink(dirs[old], recursive = TRUE, force = TRUE)
}
renv_cleanse_empty <- function(path) {
# no-op for Solaris
if (renv_platform_solaris())
return(FALSE)
if (!file.exists(path))
return(FALSE)
renv_scope_wd(path)
# execute system command for removing empty directories
action <- "removing empty directories"
if (renv_platform_windows()) {
args <- c(".", ".", "/S", "/MOVE")
renv_system_exec("robocopy", args, action, 0:8)
} else {
args <- c(".", "-type", "d", "-empty", "-delete")
renv_system_exec("find", args, action)
}
TRUE
}
renv/R/status.R 0000644 0001762 0000144 00000026267 14551607324 013117 0 ustar ligges users
the$status_running <- FALSE
#' Report inconsistencies between lockfile, library, and dependencies
#'
#' @description
#' `renv::status()` reports issues caused by inconsistencies across the project
#' lockfile, library, and [dependencies()]. In general, you should strive to
#' ensure that `status()` reports no issues, as this maximizes your chances of
#' successfully `restore()`ing the project in the future or on another machine.
#'
#' `renv::load()` will report if any issues are detected when starting an
#' renv project; we recommend resolving these issues before doing any
#' further work on your project.
#'
#' See the headings below for specific advice on resolving any issues
#' revealed by `status()`.
#'
#' # Missing packages
#'
#' `status()` first checks that all packages used by the project are installed.
#' This must be done first because if any packages are missing we can't tell for
#' sure that a package isn't used; it might be a dependency that we don't know
#' about. Once you have resolve any installation issues, you'll need to run
#' `status()` again to reveal the next set of potential problems.
#'
#' There are four possibilities for an uninstalled package:
#'
#' * If it's used and recorded, call `renv::restore()` to install the version
#' specified in the lockfile.
#' * If it's used and not recorded, call `renv::install()` to install it
#' from CRAN or elsewhere.
#' * If it's not used and recorded, call `renv::snapshot()` to
#' remove it from the lockfile.
#' * If it's not used and not recorded, there's nothing to do. This the most
#' common state because you only use a small fraction of all available
#' packages in any one project.
#'
#' If you have multiple packages in an inconsistent state, we recommend
#' `renv::restore()`, then `renv::install()`, then `renv::snapshot()`, but
#' that also suggests you should be running status more frequently.
#'
#' # Lockfile vs `dependencies()`
#'
#' Next we need to ensure that packages are recorded in the lockfile if and
#' only if they are used by the project. Fixing issues of this nature only
#' requires calling `snapshot()` because there are four possibilities for
#' a package:
#'
#' * If it's used and recorded, it's ok.
#' * If it's used and not recorded, call `renv::snapshot()` to add it to the
#' lockfile.
#' * If it's not used but is recorded, call `renv::snapshot()` to remove
#' it from the lockfile.
#' * If it's not used and not recorded, it's also ok, as it may be a
#' development dependency.
#'
#' # Out-of-sync sources
#'
#' The final issue to resolve is any inconsistencies between the version of
#' the package recorded in the lockfile and the version installed in your
#' library. To fix these issues you'll need to either call `renv::restore()`
#' or `renv::snapshot()`:
#'
#' * Call `renv::snapshot()` if your project code is working. This implies that
#' the library is correct and you need to update your lockfile.
#' * Call `renv::restore()` if your project code isn't working. This probably
#' implies that you have the wrong package versions installed and you need
#' to restore from known good state in the lockfile.
#'
#' If you're not sure which case applies, it's generally safer to call
#' `renv::snapshot()`. If you want to rollback to an earlier known good
#' status, see [renv::history()] and [renv::revert()].
#'
#' # Different R Version
#'
#' renv will also notify you if the version of R used when the lockfile was
#' generated, and the version of R currently in use, do not match. In this
#' scenario, you'll need to consider:
#'
#' - Is the version of R recorded in the lockfile correct? If so, you'll want
#' to ensure that version of R is installed and used when working in this
#' project.
#'
#' - Otherwise, you can call `renv::snapshot()` to update the version of R
#' recorded in the lockfile, to match the version of R currently in use.
#'
#' If you'd like to set the version of R recorded in a lockfile independently
#' of the version of R currently in use, you can set the `r.version` project
#' setting -- see [settings] for more details.
#'
#' @inherit renv-params
#'
#' @param library The library paths. By default, the library paths associated
#' with the requested project are used.
#'
#' @param sources Boolean; check that each of the recorded packages have a
#' known installation source? If a package has an unknown source, renv
#' may be unable to restore it.
#'
#' @param cache Boolean; perform diagnostics on the global package cache?
#' When `TRUE`, renv will validate that the packages installed into the
#' cache are installed at the expected + proper locations, and validate the
#' hashes used for those storage locations.
#'
#' @inheritParams dependencies
#'
#' @return This function is normally called for its side effects, but
#' it invisibly returns a list containing the following components:
#'
#' * `library`: packages in your library.
#' * `lockfile`: packages in the lockfile.
#' * `synchronized`: are the library and lockfile in sync?
#'
#' @export
#'
#' @example examples/examples-init.R
status <- function(project = NULL,
...,
library = NULL,
lockfile = NULL,
sources = TRUE,
cache = FALSE,
dev = FALSE)
{
renv_scope_error_handler()
renv_dots_check(...)
renv_snapshot_auto_suppress_next()
renv_scope_options(renv.prompt.enabled = FALSE)
the$status_running <- TRUE
defer(the$status_running <- FALSE)
project <- renv_project_resolve(project)
renv_project_lock(project = project)
# check to see if we've initialized this project
if (!renv_status_check_initialized(project, library, lockfile)) {
result <- list(
library = list(Packages = named(list())),
lockfile = list(Packages = named(list())),
synchronized = FALSE
)
return(invisible(result))
}
libpaths <- library %||% renv_libpaths_resolve()
lockpath <- lockfile %||% renv_paths_lockfile(project = project)
# get all dependencies, including transitive
dependencies <- renv_snapshot_dependencies(project, dev = dev)
packages <- sort(union(dependencies, "renv"))
paths <- renv_package_dependencies(packages, libpaths = libpaths, project = project)
packages <- as.character(names(paths))
# read project lockfile
lockfile <- if (file.exists(lockpath))
renv_lockfile_read(lockpath)
else
renv_lockfile_init(project = project)
# get lockfile capturing current library state
library <- renv_lockfile_create(
libpaths = libpaths,
type = "all",
prompt = FALSE,
project = project
)
# remove ignored packages
ignored <- c(
renv_project_ignored_packages(project),
renv_packages_base(),
if (renv_tests_running()) "renv"
)
packages <- setdiff(packages, ignored)
renv_lockfile_records(lockfile) <- omit(renv_lockfile_records(lockfile), ignored)
renv_lockfile_records(library) <- omit(renv_lockfile_records(library), ignored)
synchronized <- all(
renv_status_check_consistent(lockfile, library, packages),
renv_status_check_synchronized(lockfile, library),
renv_status_check_version(lockfile)
)
if (sources) {
synchronized <- synchronized &&
renv_status_check_unknown_sources(project, lockfile)
}
if (cache)
renv_status_check_cache(project)
if (synchronized)
writef("No issues found -- the project is in a consistent state.")
else
writef("See ?renv::status() for advice on resolving these issues.")
result <- list(
library = library,
lockfile = lockfile,
synchronized = synchronized
)
invisible(result)
}
renv_status_check_unknown_sources <- function(project, lockfile) {
renv_check_unknown_source(renv_lockfile_records(lockfile), project)
}
renv_status_check_consistent <- function(lockfile, library, used) {
lockfile <- renv_lockfile_records(lockfile)
library <- renv_lockfile_records(library)
packages <- sort(unique(c(names(library), names(lockfile), used)))
status <- data_frame(
package = packages,
installed = packages %in% names(library),
recorded = packages %in% names(lockfile),
used = packages %in% used
)
ok <- status$installed & (status$used == status$recorded)
if (all(ok))
return(TRUE)
if (!renv_verbose())
return(FALSE)
issues <- status[!ok, , drop = FALSE]
missing <- issues$used & !issues$installed
if (all(missing)) {
caution_bullets(
preamble = "The following package(s) are used in this project, but are not installed:",
values = issues$package[missing]
)
return(FALSE)
}
issues$installed <- ifelse(issues$installed, "y", "n")
issues$recorded <- ifelse(issues$recorded, "y", "n")
issues$used <- ifelse(issues$used, "y", if (any(missing)) "?" else "n")
preamble <- "The following package(s) are in an inconsistent state:"
writef(preamble)
writef()
print(issues, row.names = FALSE, right = FALSE)
writef()
FALSE
}
renv_status_check_initialized <- function(project, library = NULL, lockfile = NULL) {
# only done if library and lockfile are NULL; that is, if the user
# is calling `renv::status()` without arguments
if (!is.null(library) || !is.null(lockfile))
return(TRUE)
# resolve paths to lockfile, primary library path
library <- library %||% renv_paths_library(project = project)
lockfile <- lockfile %||% renv_paths_lockfile(project = project)
# check whether the lockfile + library exist
haslib <- all(file.exists(library))
haslock <- file.exists(lockfile)
if (haslib && haslock)
return(TRUE)
# TODO: what about the case where the library exists but no packages are installed?
# TODO: should this check for an 'renv/activate.R' script?
# TODO: what if a different project is loaded?
if (haslib && !haslock) {
writef(c(
"This project does not contain a lockfile.",
"Use `renv::snapshot()` to create a lockfile."
))
} else if (!haslib && haslock) {
writef(c(
"There are no packages installed in the project library.",
"Use `renv::restore()` to install the packages defined in lockfile."
))
} else {
writef(c(
"This project does not appear to be using renv.",
"Use `renv::init()` to initialize the project."
))
}
FALSE
}
renv_status_check_synchronized <- function(lockfile, library) {
lockfile <- renv_lockfile_records(lockfile)
library <- renv_lockfile_records(library)
actions <- renv_lockfile_diff_packages(lockfile, library)
rest <- c("upgrade", "downgrade", "crossgrade")
if (all(!rest %in% actions))
return(TRUE)
pkgs <- names(actions[actions %in% rest])
formatter <- function(lhs, rhs)
renv_record_format_pair(lhs, rhs, separator = "!=")
renv_pretty_print_records_pair(
preamble = "The following package(s) are out of sync [lockfile != library]:",
old = lockfile[pkgs],
new = library[pkgs],
formatter = formatter
)
FALSE
}
renv_status_check_version <- function(lockfile) {
version <- lockfile$R$Version
if (renv_version_eq(version, getRversion(), n = 2L))
return(TRUE)
fmt <- "The lockfile was generated with R %s, but you're using R %s."
writef(fmt, version, getRversion())
writef()
FALSE
}
renv_status_check_cache <- function(project) {
if (renv_cache_config_enabled(project = project))
renv_cache_diagnose()
}
renv/R/parallel.R 0000644 0001762 0000144 00000000707 14402531323 013345 0 ustar ligges users
renv_parallel_cores <- function() {
if (renv_platform_windows())
return(1L)
value <- config$updates.parallel()
case(
identical(value, TRUE) ~ getOption("mc.cores", default = 2L),
identical(value, FALSE) ~ 1L,
~ as.integer(value)
)
}
renv_parallel_exec <- function(data, callback) {
cores <- renv_parallel_cores()
if (cores > 1)
parallel::mclapply(data, callback, mc.cores = cores)
else
lapply(data, callback)
}
renv/R/rstudio.R 0000644 0001762 0000144 00000002530 14464550375 013256 0 ustar ligges users
renv_rstudio_available <- function() {
# NOTE: detecting whether we're running within RStudio is a bit
# tricky because not all of the expected RStudio bits have been
# initialized when the R session is being initialized (e.g.
# when the .Rprofile is being executed)
args <- commandArgs(trailingOnly = FALSE)
args[[1L]] == "RStudio" || .Platform$GUI == "RStudio"
}
renv_rstudio_initialize <- function(project) {
tools <- catch(as.environment("tools:rstudio"))
if (inherits(tools, "error"))
return(FALSE)
if (is.null(tools$.rs.api.initializeProject))
return(FALSE)
tools$.rs.api.initializeProject(project)
TRUE
}
renv_rstudio_fixup <- function() {
# if RStudio's tools are on the search path, we should try
# to fix them up so that renv's own routines don't get seen
tools <- catch(as.environment("tools:rstudio"))
if (inherits(tools, "error"))
return(FALSE)
helper <- tools[[".rs.clearVar"]]
if (is.null(helper))
return(FALSE)
# if the helper environment has been fixed up (as e.g. by
# newer versions of RStudio) then nothing to do
if (identical(tools, environment(helper)))
return(FALSE)
# put common tools from base into the environment
envir <- environment(helper)
for (var in c("assign", "exists", "get", "remove", "paste"))
envir[[var]] <- get(var, envir = baseenv())
TRUE
}
renv/R/lockfiles.R 0000644 0001762 0000144 00000013403 14464550375 013541 0 ustar ligges users
#' Lockfiles
#'
#' A **lockfile** records the state of a project at some point in time.
#'
#' A lockfile captures the state of a project's library at some point in time.
#' In particular, the package names, their versions, and their sources (when
#' known) are recorded in the lockfile.
#'
#' Projects can be restored from a lockfile using the [restore()] function. This
#' implies reinstalling packages into the project's private library, as encoded
#' within the lockfile.
#'
#' While lockfiles are normally generated and used with [snapshot()] /
#' [restore()], they can also be edited by hand if so desired. Lockfiles are
#' written as `.json`, to allow for easy consumption by other tools.
#'
#' An example lockfile follows:
#'
#' ```
#' {
#' "R": {
#' "Version": "3.6.1",
#' "Repositories": [
#' {
#' "Name": "CRAN",
#' "URL": "https://cloud.r-project.org"
#' }
#' ]
#' },
#' "Packages": {
#' "markdown": {
#' "Package": "markdown",
#' "Version": "1.0",
#' "Source": "Repository",
#' "Repository": "CRAN",
#' "Hash": "4584a57f565dd7987d59dda3a02cfb41"
#' },
#' "mime": {
#' "Package": "mime",
#' "Version": "0.7",
#' "Source": "Repository",
#' "Repository": "CRAN",
#' "Hash": "908d95ccbfd1dd274073ef07a7c93934"
#' }
#' }
#' }
#' ```
#'
#' The sections used within a lockfile are described next.
#'
#' ## renv
#'
#' Information about the version of renv used to manage this project.
#'
#' \tabular{ll}{
#' \strong{Version} \tab The version of the renv package used with this project. \cr
#' }
#'
#' ## R
#'
#' Properties related to the version of \R associated with this project.
#'
#' \tabular{ll}{
#' \strong{Version} \tab The version of \R used. \cr
#' \strong{Repositories} \tab The \R repositories used in this project. \cr
#' }
#'
#' ## Packages
#'
#' \R package records, capturing the packages used or required by a project
#' at the time when the lockfile was generated.
#'
#' \tabular{ll}{
#' \strong{Package} \tab The package name. \cr
#' \strong{Version} \tab The package version. \cr
#' \strong{Source} \tab The location from which this package was retrieved. \cr
#' \strong{Repository} \tab The name of the repository (if any) from which this package was retrieved. \cr
#' \strong{Hash} \tab (Optional) A unique hash for this package, used for package caching. \cr
#' }
#'
#' Additional remote fields, further describing how the package can be
#' retrieved from its corresponding source, will also be included as
#' appropriate (e.g. for packages installed from GitHub).
#'
#' ## Python
#'
#' Metadata related to the version of Python used with this project (if any).
#'
#' \tabular{ll}{
#' \strong{Version} \tab The version of Python being used. \cr
#' \strong{Type} \tab The type of Python environment being used ("virtualenv", "conda", "system") \cr
#' \strong{Name} \tab The (optional) name of the environment being used.
#' }
#'
#' Note that the `Name` field may be empty. In that case, a project-local Python
#' environment will be used instead (when not directly using a system copy of Python).
#'
#' # Caveats
#'
#' These functions are primarily intended for expert users -- in most cases,
#' [snapshot()] and [restore()] are the primariy tools you will need when
#' creating and using lockfiles.
#'
#' @inheritParams snapshot
#' @inheritParams renv-params
#'
#' @param lockfile An `renv` lockfile; typically created by either
#' `lockfile_create()` or `lockfile_read()`.
#'
#' @param file A file path, or \R connection.
#'
#' @family reproducibility
#' @name lockfiles
#' @rdname lockfiles
NULL
#' @param libpaths The library paths to be used when generating the lockfile.
#' @rdname lockfiles
#' @export
lockfile_create <- function(type = settings$snapshot.type(project = project),
libpaths = .libPaths(),
packages = NULL,
exclude = NULL,
prompt = interactive(),
force = FALSE,
...,
project = NULL)
{
renv_dots_check(...)
project <- renv_project_resolve(project)
renv_scope_verbose_if(prompt)
renv_lockfile_create(
project = project,
type = type,
libpaths = libpaths,
packages = packages,
exclude = exclude,
prompt = prompt,
force = force
)
}
#' @rdname lockfiles
#' @export
lockfile_read <- function(file = NULL, ..., project = NULL) {
project <- renv_project_resolve(project)
file <- file %||% renv_paths_lockfile(project = project)
renv_lockfile_read(file = file)
}
#' @rdname lockfiles
#' @export
lockfile_write <- function(lockfile, file = NULL, ..., project = NULL) {
project <- renv_project_resolve(project)
file <- file %||% renv_paths_lockfile(project = project)
renv_lockfile_write(lockfile, file = file)
}
#' @param remotes An \R vector of remote specifications.
#'
#' @param repos A named vector, mapping \R repository names to their URLs.
#'
#' @rdname lockfiles
#' @export
lockfile_modify <- function(lockfile = NULL,
...,
remotes = NULL,
repos = NULL,
project = NULL)
{
renv_dots_check(...)
project <- renv_project_resolve(project)
lockfile <- lockfile %||% renv_lockfile_load(project, strict = TRUE)
if (!is.null(repos))
lockfile$R$Repositories <- as.list(repos)
if (!is.null(remotes)) {
remotes <- renv_records_resolve(remotes, latest = TRUE)
names(remotes) <- map_chr(remotes, `[[`, "Package")
enumerate(remotes, function(package, remote) {
record <- renv_remotes_resolve(remote)
renv_lockfile_records(lockfile)[[package]] <<- record
})
}
lockfile
}
renv/R/equip-macos.R 0000644 0001762 0000144 00000005527 14464550375 014021 0 ustar ligges users
renv_equip_macos_specs <- function() {
list(
"4.0" = list(
url = "https://cran.r-project.org/bin/macosx/tools/clang-8.0.0.pkg",
dst = "/usr/local/clang8"
),
"3.7" = list(
url = "https://cran.r-project.org/bin/macosx/tools/clang-8.0.0.pkg",
dst = "/usr/local/clang8"
),
"3.6" = list(
url = "https://cran.r-project.org/bin/macosx/tools/clang-7.0.0.pkg",
dst = "/usr/local/clang7"
),
"3.5" = list(
url = "https://cran.r-project.org/bin/macosx/tools/clang-6.0.0.pkg",
dst = "/usr/local/clang6"
)
)
}
renv_equip_macos_spec <- function(version = getRversion()) {
renv_equip_macos_specs()[[renv_version_maj_min(version)]]
}
renv_equip_macos <- function() {
renv_equip_macos_sdk()
renv_equip_macos_toolchain()
}
renv_equip_macos_sdk <- function() {
sdk <- "/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk"
if (file.exists(sdk) || file.exists("/usr/include"))
return(TRUE)
system("/usr/bin/xcode-select --install")
# give the user some time to respond to the dialog)
Sys.sleep(5)
}
renv_equip_macos_toolchain <- function() {
if (getRversion() >= "4.1.0")
return()
spec <- renv_equip_macos_spec()
if (is.null(spec)) {
fmt <- "no known toolchain recorded in renv for R %s"
warningf(fmt, getRversion())
return(FALSE)
}
url <- spec$url
dst <- spec$dst
clang <- file.path(dst, "bin/clang")
if (file.exists(clang)) {
fmt <- "- LLVM toolchain for R %s is already installed at %s."
writef(fmt, getRversion(), shQuote(dst))
return(TRUE)
}
destfile <- file.path(tempdir(), basename(url))
download(url, destfile = destfile)
if (renv_equip_macos_rstudio(spec, destfile))
return(TRUE)
command <- paste("sudo /usr/sbin/installer -pkg", shQuote(destfile), "-target /")
caution_bullets(
"The R LLVM toolchain has been successfully downloaded. Please execute:",
command,
"in a separate terminal to complete installation."
)
TRUE
}
renv_equip_macos_rstudio <- function(spec, destfile) {
rstudio <-
renv_rstudio_available() &&
requireNamespace("rstudioapi", quietly = TRUE)
if (!rstudio)
return(FALSE)
command <- paste("sudo -kS /usr/sbin/installer -pkg", shQuote(destfile), "-target /")
prompt <- paste(
"Installation of the R LLVM toolchain requires sudo.",
"Please enter your account password.",
sep = "\n"
)
installed <- local({
password <- rstudioapi::askForPassword(prompt)
if (is.null(password))
return(FALSE)
status <- system(command, input = password)
if (status != 0L)
return(FALSE)
TRUE
})
if (!installed)
return(FALSE)
caution_bullets(
"The R LLVM toolchain has been downloaded and installed to:",
spec$dst,
"This toolchain will be used by renv when installing packages from source."
)
return(TRUE)
}
renv/R/difftime.R 0000644 0001762 0000144 00000002100 14466465760 013352 0 ustar ligges users
renv_difftime_format <- function(time, digits = 2L) {
if (testing())
return("XXXX seconds")
units <- attr(time, "units") %||% ""
if (units == "secs" && time < 0.1) {
time <- time * 1000
units <- "milliseconds"
}
units <- switch(
units,
secs = "seconds",
mins = "minutes",
hours = "hours",
days = "days",
weeks = "weeks",
units
)
elapsed <- format(unclass(signif(time, digits = digits)))
if (elapsed %in% c("1", "1.0"))
units <- substring(units, 1L, nchar(units) - 1L)
paste(elapsed, units)
}
renv_difftime_format_short <- function(time, digits = 2L) {
if (testing())
return("XXs")
units <- attr(time, "units") %||% ""
if (units == "secs" && time < 0.1) {
time <- time * 1000
units <- "ms"
}
elapsed <- signif(time, digits = digits)
if (nchar(elapsed) == 1L)
elapsed <- paste(elapsed, ".0", sep = "")
units <- switch(
attr(time, "units"),
secs = "s",
mins = "m",
hours = "h",
days = "d",
weeks = "w",
units
)
paste(elapsed, units, sep = "")
}
renv/R/config.R 0000644 0001762 0000144 00000015340 14435501307 013022 0 ustar ligges users
#' User-level settings
#'
#' Configure different behaviors of renv.
#'
#' For a given configuration option:
#'
#' 1. If an \R option of the form `renv.config.` is available,
#' then that option's value will be used;
#'
#' 2. If an environment variable of the form `RENV_CONFIG_` is available,
#' then that option's value will be used;
#'
#' 3. Otherwise, the default for that particular configuration value is used.
#'
#' Any periods (`.`)s in the option name are transformed into underscores (`_`)
#' in the environment variable name, and vice versa. For example, the
#' configuration option `auto.snapshot` could be configured as:
#'
#' - `options(renv.config.auto.snapshot = <...>)`
#' - `Sys.setenv(RENV_CONFIG_AUTO_SNAPSHOT = <...>)`
#'
#' Note that if both the \R option and the environment variable are defined, the
#' \R option will be used instead. Environment variables can be more useful when
#' you want a particular configuration to be automatically inherited by child
#' processes; if that behavior is not desired, then the R option may be
#' preferred.
#'
#' If you want to set and persist these options across multiple projects, it is
#' recommended that you set them in a a startup `.Renviron` file; e.g. in your
#' own `~/.Renviron`, or in the R installation's `etc/Rprofile.site` file. See
#' [Startup] for more details.
#'
#' Configuration options can also be set within the project `.Rprofile`, but
#' be aware the options should be set before `source("renv/activate.R")` is
#' called.
#'
#' @eval renv_roxygen_config_section()
#'
#' @section Copy methods:
#'
#' If you find that renv is unable to copy some directories in your
#' environment, you may want to try setting the `copy.method` option. By
#' default, renv will try to choose a system tool that is likely to succeed in
#' copying files on your system -- `robocopy` on Windows, and `cp` on Unix.
#' renv will also instruct these tools to preserve timestamps and attributes
#' when copying files. However, you can select a different method as
#' appropriate.
#'
#' The following methods are supported:
#'
#' \tabular{ll}{
#' `auto` \tab Use `robocopy` on Windows, and `cp` on Unix-alikes. \cr
#' `R` \tab Use \R's built-in `file.copy()` function. \cr
#' `cp` \tab Use `cp` to copy files. \cr
#' `robocopy` \tab Use `robocopy` to copy files. (Only available on Windows.) \cr
#' `rsync` \tab Use `rsync` to copy files. \cr
#' }
#'
#' You can also provide a custom copy method if required; e.g.
#'
#' ```
#' options(renv.config.copy.method = function(src, dst) {
#' # copy a file from 'src' to 'dst'
#' })
#' ```
#'
#' Note that renv will always first attempt to copy a directory first to a
#' temporary path within the target folder, and then rename that temporary path
#' to the final target destination. This helps avoid issues where a failed
#' attempt to copy a directory could leave a half-copied directory behind
#' in the final location.
#'
#' @section Project-local settings:
#'
#' For settings that should persist alongside a particular project, the
#' various settings available in [settings] can be used.
#'
#' @examples
#'
#' # disable automatic snapshots
#' options(renv.config.auto.snapshot = FALSE)
#'
#' # disable with environment variable
#' Sys.setenv(RENV_CONFIG_AUTO_SNAPSHOT = FALSE)
#'
#' @rdname config
#' @name config
NULL
renv_config_get <- function(name,
scope = "config",
type = "*",
default = NULL,
args = NULL)
{
# check for R option of associated name
optname <- tolower(name)
optkey <- paste("renv", scope, optname, sep = ".")
optval <- getOption(optkey)
if (!is.null(optval))
return(renv_config_validate(name, optval, type, default, args))
# check for environment variable
envname <- gsub(".", "_", toupper(name), fixed = TRUE)
envkey <- paste("RENV", toupper(scope), envname, sep = "_")
envval <- Sys.getenv(envkey, unset = NA)
if (!is.na(envval) && nzchar(envval)) {
decoded <- renv_config_decode_envvar(envkey, envval)
return(renv_config_validate(name, decoded, type, default, args))
}
# return default if nothing found
default
}
renv_config_decode_envvar <- function(envname, envval) {
map <- env(
"NULL" = NULL,
"NA" = NA,
"NaN" = NaN,
"true" = TRUE,
"True" = TRUE,
"TRUE" = TRUE,
"false" = FALSE,
"False" = FALSE,
"FALSE" = FALSE
)
if (exists(envval, envir = map, inherits = FALSE))
return(get(envval, envir = map, inherits = FALSE))
libvars <- c("RENV_CONFIG_EXTERNAL_LIBRARIES", "RENV_CONFIG_HYDRATE_LIBPATHS")
pattern <- if (envname %in% libvars)
"\\s*[:;,]\\s*"
else
"\\s*,\\s*"
strsplit(envval, pattern, perl = TRUE)[[1L]]
}
renv_config_validate <- function(name, value, type, default, args) {
# no validation required for type = '*'
if (identical(type, "*"))
return(value)
# if 'value' is a function, invoke it with args
if (is.function(value)) {
value <- catch(do.call(value, args))
if (inherits(value, "error")) {
warning(value, call. = FALSE)
return(default)
}
}
# parse the type string
pattern <- paste0(
"^", # start of specifier
"([^[(]+)", # type name
"[[(]", # opening bracket
"([^])]+)", # length specifier
"[])]", # closing bracket
"$" # end of specifier
)
m <- regexec(pattern, type)
matches <- regmatches(type, m)
fields <- matches[[1L]]
# extract declared mode, size
mode <- fields[[2L]]
size <- fields[[3L]]
# validate the requested size for this option
if (!renv_config_validate_size(value, size)) {
fmt <- "value for option '%s' does not satisfy constraint '%s'"
warningf(fmt, name, type)
}
# convert NULL values to requested type
if (is.null(value)) {
value <- convert(value, mode)
return(value)
}
# otherwise, validate that this is a valid option
if (identical(storage.mode(value), mode))
return(value)
# try converting
converted <- catchall(convert(value, mode))
if (any(is.na(converted)) || inherits(converted, "condition")) {
fmt <- "'%s' does not satisfy constraint '%s' for config '%s'; using default '%s' instead"
warningf(fmt, stringify(value), type, name, stringify(default))
return(default)
}
# ok, validated + converted option
converted
}
renv_config_validate_size <- function(value, size) {
case(
size == "*" ~ TRUE,
size == "+" ~ length(value) > 0,
size == "?" ~ length(value) %in% c(0, 1),
TRUE ~ as.numeric(size) == length(value)
)
}
renv_config_install_staged <- function(default = TRUE) {
values <- c(
config$install.staged(default = NULL),
config$install.transactional(default = NULL),
default
)
values[[1L]]
}
renv/R/updates.R 0000644 0001762 0000144 00000000626 14464550375 013236 0 ustar ligges users
renv_updates_create <- function(diff, old, new) {
structure(
list(diff = diff, old = old, new = new),
class = "renv_updates"
)
}
renv_updates_report <- function(preamble, diff, old, new) {
lhs <- renv_lockfile_records(old)
rhs <- renv_lockfile_records(new)
renv_pretty_print_records_pair(
preamble,
lhs[names(lhs) %in% names(diff)],
rhs[names(rhs) %in% names(diff)]
)
}
renv/R/json-write.R 0000644 0001762 0000144 00000004713 14475740262 013671 0 ustar ligges users
# @param box A vector of names, whose values should be boxed. By default,
# scalar values are unboxed.
renv_json_config <- function(box = character()) {
list(box = box)
}
renv_json_write <- function(object,
config = NULL,
file = stdout())
{
config <- config %||% renv_json_config()
json <- renv_json_convert_impl(NULL, object, config, 0L)
if (is.null(file))
return(json)
writeLines(json, con = file)
}
renv_json_convert <- function(object, config = renv_json_config()) {
renv_json_convert_impl(NULL, object, config, 0L)
}
renv_json_convert_impl <- function(key, value, config, depth) {
if (is.list(value) || !is.null(names(value)))
return(renv_json_convert_list(key, value, config, depth))
json <- renv_json_convert_atom(key, value, config, depth)
indent <- renv_json_convert_indent(depth)
paste0(indent, json)
}
renv_json_convert_list <- function(key, value, config, depth) {
indent <- renv_json_convert_indent(depth)
if (empty(value)) {
json <- if (is.null(names(value))) "[]" else "{}"
paste0(indent, json)
} else if (is.null(names(value))) {
json <- enum_chr(value, renv_json_convert_impl, config = config, depth = depth + 1L)
paste0(indent, "[", "\n", paste(json, collapse = ",\n"), "\n", indent, "]")
} else {
keys <- renv_json_quote(names(value))
vals <- enum_chr(value, renv_json_convert_impl, config = config, depth = depth + 1L)
idx <- regexpr("[^[:space:]]", vals)
json <- paste0(substring(vals, 1L, idx - 1L), keys, ": ", substring(vals, idx))
paste0(indent, "{", "\n", paste(json, collapse = ",\n"), "\n", indent, "}")
}
}
renv_json_convert_atom <- function(key, value, config, depth) {
unbox <- is.null(key) || !key %in% config$box || inherits(value, "AsIs")
if (is.null(value))
return(if (unbox) "null" else "[]")
n <- length(value)
if (n == 0L)
return("[]")
if (is.character(value)) {
value <- renv_json_quote(value)
value[value %in% c("NA")] <- "null"
}
if (is.logical(value)) {
value <- ifelse(value, "true", "false")
value[is.na(value)] <- "null"
}
if (unbox && n == 1L)
return(if (is.na(value)) "null" else paste0(value))
indent <- renv_json_convert_indent(depth)
json <- paste0(renv_json_convert_indent(depth + 1L), value)
paste0("[", "\n", paste(json, collapse = ",\n"), "\n", indent, "]")
}
renv_json_convert_indent <- function(level) {
paste(rep(" ", level), collapse = "")
}
renv/R/renv-package.R 0000644 0001762 0000144 00000000604 14431215655 014121 0 ustar ligges users
#' Project-local Environments for R
#'
#' Project-local environments for \R.
#'
#' You can use renv to construct isolated, project-local \R libraries.
#' Each project using renv will share package installations from a global
#' cache of packages, helping to avoid wasting disk space on multiple
#' installations of a package that might otherwise be shared across projects.
#'
"_PACKAGE"
renv/R/warnings.R 0000644 0001762 0000144 00000001207 14464550375 013415 0 ustar ligges users
renv_warnings_unknown_sources <- function(records) {
if (empty(records))
return(FALSE)
# TODO: Should this be documented?
enabled <- renv_config_get(
name = "unknown.sources",
scope = "warnings",
type = "logical[1]",
default = TRUE
)
if (!enabled)
return(FALSE)
renv_scope_options(renv.verbose = TRUE)
renv_pretty_print_records(
"The following package(s) were installed from an unknown source:",
records,
c(
"renv may be unable to restore these packages in the future.",
"Consider reinstalling these packages from a known source (e.g. CRAN)."
)
)
return(TRUE)
}
renv/R/retrieve.R 0000644 0001762 0000144 00000107354 14574414431 013416 0 ustar ligges users
the$repos_archive <- new.env(parent = emptyenv())
# this routine retrieves a package + its dependencies, and as a side
# effect populates the restore state's `retrieved` member with a
# list of package records which can later be used for install
retrieve <- function(packages) {
# confirm that we have restore state set up
state <- renv_restore_state()
if (is.null(state))
stopf("renv_restore_begin() must be called first")
# normalize repositories (ensure @CRAN@ is resolved)
options(repos = renv_repos_normalize())
# transform repository URLs for PPM
if (renv_ppm_enabled()) {
repos <- getOption("repos")
renv_scope_options(repos = renv_ppm_transform(repos))
}
# ensure HTTPUserAgent is set (required for PPM binaries)
agent <- renv_http_useragent()
if (!grepl("renv", agent)) {
renv <- sprintf("renv (%s)", renv_metadata_version())
agent <- paste(renv, agent, sep = "; ")
}
renv_scope_options(HTTPUserAgent = agent)
before <- Sys.time()
handler <- state$handler
for (package in packages)
handler(package, renv_retrieve_impl(package))
after <- Sys.time()
state <- renv_restore_state()
count <- state$downloaded
if (count) {
elapsed <- difftime(after, before, units = "secs")
writef("Successfully downloaded %s in %s.", nplural("package", count), renv_difftime_format(elapsed))
writef("")
}
state$install$data()
}
renv_retrieve_impl <- function(package) {
# skip packages with 'base' priority
if (package %in% renv_packages_base())
return()
# if we've already attempted retrieval of this package, skip
state <- renv_restore_state()
if (!is.null(state$retrieved[[package]]))
return()
# insert a dummy value just to avoid infinite recursions
# (this will get updated on a successful installation later)
state$retrieved[[package]] <- NA
# extract record for package
records <- state$records
record <- records[[package]] %||% renv_retrieve_resolve(package)
# resolve lazy records
if (is.function(record)) {
state$records[[package]] <- resolve(record)
record <- state$records[[package]]
}
# normalize the record source
source <- renv_record_source(record, normalize = TRUE)
# don't install packages from incompatible OS
ostype <- tolower(record[["OS_type"]] %||% "")
skip <-
renv_platform_unix() && identical(ostype, "windows") ||
renv_platform_windows() && identical(ostype, "unix")
if (skip)
return()
# if this is a package from Bioconductor, activate those repositories now
if (source %in% c("bioconductor")) {
project <- renv_restore_state(key = "project")
renv_scope_bioconductor(project = project)
}
# if this is a package from R-Forge, activate its repository
if (source %in% c("repository")) {
repository <- record$Repository %||% ""
if (tolower(repository) %in% c("rforge", "r-forge")) {
repos <- getOption("repos")
if (!"R-Forge" %in% names(repos)) {
repos[["R-Forge"]] <- "https://R-Forge.R-project.org"
renv_scope_options(repos = repos)
}
}
}
# if the record doesn't declare the package version,
# treat it as a request for the latest version on CRAN
# TODO: should make this behavior configurable
uselatest <-
source %in% c("repository", "bioconductor") &&
is.null(record$Version)
if (uselatest) {
record <- withCallingHandlers(
renv_available_packages_latest(package),
error = function(err) stopf("package '%s' is not available", package)
)
}
# if the requested record is incompatible with the set
# of requested package versions thus far, request the
# latest version on the R package repositories
#
# TODO: handle more explicit dependency requirements
# TODO: report to the user if they have explicitly requested
# installation of this package version despite it being incompatible
compat <- renv_retrieve_incompatible(package, record)
if (NROW(compat)) {
# get the latest available package version
replacement <- renv_available_packages_latest(package)
if (is.null(replacement))
stopf("package '%s' is not available", package)
# if it's not compatible, then we might need to try again with
# a source version (assuming type = "both")
pkgtype <- getOption("pkgType")
if (identical(pkgtype, "both")) {
iscompat <- renv_retrieve_incompatible(package, replacement)
if (NROW(iscompat)) {
replacement <- renv_available_packages_latest(package, type = "source")
}
}
# report if we couldn't find a compatible package
renv_retrieve_incompatible_report(package, record, replacement, compat)
record <- replacement
}
rebuild <- renv_restore_rebuild_required(record)
if (!rebuild) {
# if we have an installed package matching the requested record, finish early
path <- renv_restore_find(package, record)
if (file.exists(path)) {
install <- !dirname(path) %in% renv_libpaths_all()
return(renv_retrieve_successful(record, path, install = install))
}
# if the requested record already exists in the cache,
# we'll use that package for install
cacheable <-
renv_cache_config_enabled(project = state$project) &&
renv_record_cacheable(record)
if (cacheable) {
# try to find the record in the cache
path <- renv_cache_find(record)
if (nzchar(path) && renv_cache_package_validate(path))
return(renv_retrieve_successful(record, path))
}
}
# if this is a URL source, then it should already have a local path
# check for the Path and Source fields and see if they resolve
fields <- c("Path", "Source")
for (field in fields) {
# check for a valid field
path <- record[[field]]
if (is.null(path))
next
# check whether it looks like an explicit source
isurl <-
is.character(path) &&
nzchar(path) &&
grepl("[/\\]|[.](?:zip|tgz|gz)$", path)
if (!isurl)
next
# error if the field is declared but doesn't exist
if (!file.exists(path)) {
fmt <- "record for package '%s' declares local source '%s', but that file does not exist"
stopf(fmt, record$Package, path)
}
# otherwise, success
path <- renv_path_normalize(path, mustWork = TRUE)
return(renv_retrieve_successful(record, path))
}
# try some early shortcut methods
shortcuts <- if (rebuild) c(
renv_retrieve_cellar
) else c(
renv_retrieve_explicit,
renv_retrieve_cellar,
if (!renv_tests_running() && config$install.shortcuts())
renv_retrieve_libpaths
)
for (shortcut in shortcuts) {
retrieved <- catch(shortcut(record))
if (identical(retrieved, TRUE))
return(TRUE)
}
state$downloaded <- state$downloaded + 1L
if (state$downloaded == 1L)
writef(header("Downloading packages"))
# time to retrieve -- delegate based on previously-determined source
switch(source,
bioconductor = renv_retrieve_bioconductor(record),
bitbucket = renv_retrieve_bitbucket(record),
git = renv_retrieve_git(record),
github = renv_retrieve_github(record),
gitlab = renv_retrieve_gitlab(record),
repository = renv_retrieve_repos(record),
url = renv_retrieve_url(record),
renv_retrieve_unknown_source(record)
)
}
renv_retrieve_name <- function(record, type = "source", ext = NULL) {
package <- record$Package
version <- record$RemoteSha %||% record$Version
ext <- ext %||% renv_package_ext(type)
sprintf("%s_%s%s", package, version, ext)
}
renv_retrieve_path <- function(record, type = "source", ext = NULL) {
# extract relevant record information
package <- record$Package
name <- renv_retrieve_name(record, type, ext)
source <- renv_record_source(record)
# check for packages from an PPM binary URL, and
# update the package type if known
if (renv_ppm_enabled()) {
url <- attr(record, "url")
if (is.character(url) && grepl("/__[^_]+__/", url))
type <- "binary"
}
# form path for package to be downloaded
if (type == "source")
renv_paths_source(source, package, name)
else if (type == "binary")
renv_paths_binary(source, package, name)
else
stopf("unrecognized type '%s'", type)
}
renv_retrieve_bioconductor <- function(record) {
# try to read the bioconductor version from the record
version <- renv_retrieve_bioconductor_version(record)
# activate Bioconductor repositories in this context
project <- renv_restore_state(key = "project")
renv_scope_bioconductor(project = project, version = version)
# retrieve record using updated repositories
renv_retrieve_repos(record)
}
renv_retrieve_bioconductor_version <- function(record) {
# read git branch
branch <- record[["git_branch"]]
if (is.null(branch))
return(NULL)
# try and parse version
parts <- strsplit(branch, "_", fixed = TRUE)[[1L]]
ok <-
length(parts) == 3L &&
tolower(parts[[1L]]) == "release"
if (!ok)
return(NULL)
# we have a version; use it
paste(tail(parts, n = -1L), collapse = ".")
}
renv_retrieve_bitbucket <- function(record) {
# query repositories endpoint to find download URL
host <- record$RemoteHost %||% config$bitbucket.host()
origin <- renv_retrieve_origin(host)
username <- record$RemoteUsername
repo <- record$RemoteRepo
# scope authentication
renv_scope_auth(repo)
fmt <- "%s/repositories/%s/%s"
url <- sprintf(fmt, origin, username, repo)
destfile <- renv_scope_tempfile("renv-bitbucket-")
download(url, destfile = destfile, quiet = TRUE)
json <- renv_json_read(destfile)
# now build URL to tarball
base <- json$links$html$href
ref <- record$RemoteSha %||% record$RemoteRef
fmt <- "%s/get/%s.tar.gz"
url <- sprintf(fmt, base, ref)
path <- renv_retrieve_path(record)
renv_retrieve_package(record, url, path)
}
renv_retrieve_github <- function(record) {
host <- record$RemoteHost %||% config$github.host()
origin <- renv_retrieve_origin(host)
username <- record$RemoteUsername
repo <- record$RemoteRepo
ref <- record$RemoteSha %||% record$RemoteRef
if (is.null(ref)) {
fmt <- "GitHub record for package '%s' has no recorded 'RemoteSha' / 'RemoteRef'"
stopf(fmt, record$Package)
}
fmt <- "%s/repos/%s/%s/tarball/%s"
url <- with(record, sprintf(fmt, origin, username, repo, ref))
path <- renv_retrieve_path(record)
renv_retrieve_package(record, url, path)
}
renv_retrieve_gitlab <- function(record) {
host <- record$RemoteHost %||% config$gitlab.host()
origin <- renv_retrieve_origin(host)
user <- record$RemoteUsername
repo <- record$RemoteRepo
id <- URLencode(paste(user, repo, sep = "/"), reserved = TRUE)
fmt <- "%s/api/v4/projects/%s/repository/archive.tar.gz"
url <- sprintf(fmt, origin, id)
path <- renv_retrieve_path(record)
sha <- record$RemoteSha %||% record$RemoteRef
if (!is.null(sha))
url <- paste(url, paste("sha", sha, sep = "="), sep = "?")
renv_retrieve_package(record, url, path)
}
renv_retrieve_git <- function(record) {
# NOTE: This path will later be used during the install step, so we don't
# want to clean it up afterwards
path <- tempfile("renv-git-")
ensure_directory(path)
renv_retrieve_git_impl(record, path)
renv_retrieve_successful(record, path)
}
renv_retrieve_git_impl <- function(record, path) {
renv_git_preflight()
package <- record$Package
url <- record$RemoteUrl
ref <- record$RemoteRef
sha <- record$RemoteSha
# figure out the default ref
gitref <- case(
nzchar(sha %||% "") ~ sha,
nzchar(ref %||% "") ~ ref,
"HEAD"
)
# be quiet if requested
quiet <- getOption("renv.git.quiet", default = TRUE)
quiet <- if (quiet) "--quiet" else ""
template <- heredoc('
git init ${QUIET}
git remote add origin "${ORIGIN}"
git fetch ${QUIET} --depth=1 origin "${REF}"
git reset ${QUIET} --hard FETCH_HEAD
')
data <- list(
ORIGIN = url,
REF = gitref,
QUIET = quiet
)
commands <- renv_template_replace(template, data)
command <- gsub("\n", " && ", commands, fixed = TRUE)
if (renv_platform_windows())
command <- paste(comspec(), "/C", command)
printf("- Cloning '%s' ... ", url)
before <- Sys.time()
status <- local({
ensure_directory(path)
renv_scope_wd(path)
renv_scope_auth(record)
renv_scope_git_auth()
system(command)
})
after <- Sys.time()
if (status != 0L) {
fmt <- "error cloning '%s' from '%s' [status code %i]"
stopf(fmt, package, url, status)
}
fmt <- "OK [cloned repository in %s]"
elapsed <- difftime(after, before, units = "auto")
writef(fmt, renv_difftime_format(elapsed))
TRUE
}
renv_retrieve_cellar_find <- function(record, project = NULL) {
project <- renv_project_resolve(project)
# packages installed with 'remotes::install_local()' will
# have a RemoteUrl entry that we can use
url <- record$RemoteUrl %||% ""
if (file.exists(url)) {
path <- renv_path_normalize(url, mustWork = TRUE)
type <- if (fileext(path) %in% c(".tgz", ".zip")) "binary" else "source"
return(named(path, type))
}
# otherwise, look in the cellar
roots <- renv_cellar_roots(project)
for (type in c("binary", "source")) {
name <- renv_retrieve_name(record, type = type)
for (root in roots) {
package <- record$Package
paths <- c(
file.path(root, package, name),
file.path(root, name)
)
for (path in paths)
if (file.exists(path))
return(named(path, type))
}
}
fmt <- "%s [%s] is not available locally"
stopf(fmt, record$Package, record$Version)
}
renv_retrieve_cellar_report <- function(record) {
source <- renv_record_source(record)
if (source == "cellar")
return(record)
fmt <- "- Package %s [%s] will be installed from the cellar."
with(record, writef(fmt, Package, Version))
record
}
renv_retrieve_cellar <- function(record) {
source <- renv_retrieve_cellar_find(record)
record <- renv_retrieve_cellar_report(record)
renv_retrieve_successful(record, source)
}
renv_retrieve_libpaths <- function(record) {
libpaths <- c(renv_libpaths_user(), renv_libpaths_site())
for (libpath in libpaths)
if (renv_retrieve_libpaths_impl(record, libpath))
return(TRUE)
}
renv_retrieve_libpaths_impl <- function(record, libpath) {
# form path to installed package's DESCRIPTION
path <- file.path(libpath, record$Package)
if (!file.exists(path))
return(FALSE)
# read DESCRIPTION
desc <- renv_description_read(path = path)
# check if it's compatible with the requested record
fields <- c("Package", "Version", grep("^Remote", names(record), value = TRUE))
compatible <- identical(record[fields], desc[fields])
if (!compatible)
return(FALSE)
# check that it was built for a compatible version of R
built <- desc[["Built"]]
if (is.null(built))
return(FALSE)
ok <- catch(renv_description_built_version(desc))
if (!identical(ok, TRUE))
return(FALSE)
# check that this package has a known source
source <- renv_snapshot_description_source(desc)
if (identical(source$Source, "unknown"))
return(FALSE)
# OK: copy this package as-is
renv_retrieve_successful(record, path)
}
renv_retrieve_explicit <- function(record) {
# try parsing as a local remote
source <- record$Path %||% record$RemoteUrl %||% ""
if (nzchar(source)) {
resolved <- catch(renv_remotes_resolve_path(source))
if (inherits(resolved, "error"))
return(FALSE)
}
# treat as 'local' source but extract path
normalized <- renv_path_normalize(source, mustWork = TRUE)
resolved$Source <- "Local"
renv_retrieve_successful(resolved, normalized)
}
renv_retrieve_repos <- function(record) {
# if this record is tagged with a type + url, we can
# use that directly for retrieval
if (renv_record_tagged(record))
return(renv_retrieve_repos_impl(record))
# figure out what package sources are okay to use here
pkgtype <- getOption("pkgType", default = "source")
srcok <-
pkgtype %in% c("both", "source") ||
getOption("install.packages.check.source", default = "yes") %in% "yes"
binok <-
pkgtype %in% c("both", "binary") ||
grepl("binary", pkgtype, fixed = TRUE)
# collect list of 'methods' for retrieval
methods <- stack(mode = "list")
# add binary package methods
if (binok) {
# prefer repository binaries if available
methods$push(renv_retrieve_repos_binary)
# also try fallback binary locations (for Nexus)
methods$push(renv_retrieve_repos_binary_fallback)
# if MRAN is enabled, check those binaries as well
if (renv_p3m_enabled())
methods$push(renv_retrieve_repos_p3m)
}
# next, try to retrieve from sources
if (srcok) {
# retrieve from source repositories
methods$push(renv_retrieve_repos_source)
# also try fallback source locations (for Nexus)
methods$push(renv_retrieve_repos_source_fallback)
# if this is a package from r-universe, try restoring from github
# (currently inferred from presence for RemoteUrl field)
unifields <- c("RemoteUrl", "RemoteRef", "RemoteSha")
if (all(unifields %in% names(record)))
methods$push(renv_retrieve_git)
else
methods$push(renv_retrieve_repos_archive)
}
# capture errors for reporting
errors <- stack()
for (method in methods$data()) {
status <- catch(
withCallingHandlers(
method(record),
renv.retrieve.error = function(error) {
errors$push(error$data)
}
)
)
if (inherits(status, "error")) {
errors$push(status)
next
}
if (identical(status, TRUE))
return(TRUE)
if (!is.logical(status)) {
fmt <- "internal error: unexpected status code '%s'"
warningf(fmt, stringify(status))
}
}
# if we couldn't download the package, report the errors we saw
local({
renv_scope_options(warn = 1L)
for (error in errors$data())
warning(error)
})
stopf("failed to retrieve package '%s'", renv_record_format_remote(record))
}
renv_retrieve_repos_error_report <- function(record, errors) {
if (empty(errors))
return()
messages <- extract(errors, "message")
if (empty(messages))
return()
messages <- unlist(messages, recursive = TRUE, use.names = FALSE)
if (empty(messages))
return()
fmt <- "The following error(s) occurred while retrieving '%s':"
preamble <- sprintf(fmt, record$Package)
caution_bullets(
preamble = preamble,
values = paste("-", messages)
)
if (renv_verbose())
str(errors)
}
renv_retrieve_url <- function(record) {
if (is.null(record$RemoteUrl)) {
fmt <- "package '%s' has no recorded RemoteUrl"
stopf(fmt, record$Package)
}
resolved <- renv_remotes_resolve_url(record$RemoteUrl, quiet = FALSE)
renv_retrieve_successful(record, resolved$Path)
}
renv_retrieve_repos_archive_name <- function(record, type = "source") {
file <- record$File
if (length(file) && !is.na(file))
return(file)
ext <- renv_package_ext(type)
paste0(record$Package, "_", record$Version, ext)
}
renv_retrieve_repos_p3m <- function(record) {
# MRAN does not make binaries available on Linux
if (renv_platform_linux())
return(FALSE)
# ensure local MRAN database is up-to-date
renv_p3m_database_refresh(explicit = FALSE)
# check that we have an available database
path <- renv_p3m_database_path()
if (!file.exists(path))
return(FALSE)
# attempt to read it
database <- catch(renv_p3m_database_load())
if (inherits(database, "error")) {
warning(database)
return(FALSE)
}
# get entry for this version of R + platform
suffix <- contrib.url("", type = "binary")
entry <- database[[suffix]]
if (is.null(entry))
return(FALSE)
# check for known entry for this package + version
key <- paste(record$Package, record$Version)
idate <- entry[[key]]
if (is.null(idate))
return(FALSE)
# convert from integer to date
date <- as.Date(idate, origin = "1970-01-01")
# form url to binary package
base <- renv_p3m_url(date, suffix)
name <- renv_retrieve_name(record, type = "binary")
url <- file.path(base, name)
# form path to saved file
path <- renv_retrieve_path(record, "binary")
# tag record with repository name
record <- overlay(record, list(
Source = "Repository",
Repository = "P3M"
))
# attempt to retrieve
renv_retrieve_package(record, url, path)
}
renv_retrieve_repos_binary <- function(record) {
renv_retrieve_repos_impl(record, "binary")
}
renv_retrieve_repos_binary_fallback <- function(record) {
for (repo in getOption("repos")) {
if (renv_nexus_enabled(repo)) {
repourl <- contrib.url(repo, type = "binary")
status <- catch(renv_retrieve_repos_impl(record, "binary", repo = repourl))
if (!inherits(status, "error"))
return(status)
}
}
FALSE
}
renv_retrieve_repos_source <- function(record) {
renv_retrieve_repos_impl(record, "source")
}
renv_retrieve_repos_source_fallback <- function(record, repo) {
for (repo in getOption("repos")) {
if (renv_nexus_enabled(repo)) {
repourl <- contrib.url(repo, type = "source")
status <- catch(renv_retrieve_repos_impl(record, "source", repo = repourl))
if (!inherits(status, "error"))
return(status)
}
}
FALSE
}
renv_retrieve_repos_archive <- function(record) {
for (repo in getOption("repos")) {
# try to determine path to package in archive
url <- renv_retrieve_repos_archive_path(repo, record)
if (is.null(url))
next
# attempt download
name <- renv_retrieve_repos_archive_name(record, type = "source")
status <- catch(renv_retrieve_repos_impl(record, "source", name, url))
if (identical(status, TRUE))
return(TRUE)
}
return(FALSE)
}
renv_retrieve_repos_archive_path <- function(repo, record) {
# allow users to provide a custom archive path for a record,
# in case they're using a repository that happens to archive
# packages with a different format than regular CRAN network
# https://github.com/rstudio/renv/issues/602
override <- getOption("renv.retrieve.repos.archive.path")
if (is.function(override)) {
result <- override(repo, record)
if (!is.null(result))
return(result)
}
# if we already know the format of the repository, use that
if (exists(repo, envir = the$repos_archive)) {
formatter <- get(repo, envir = the$repos_archive)
root <- formatter(repo, record)
return(root)
}
# otherwise, try determining the archive paths with a couple
# custom locations, and cache the version that works for the
# associated repository
formatters <- list(
# default CRAN format
function(repo, record) {
with(record, file.path(repo, "src/contrib/Archive", Package))
},
# format used by Artifactory
# https://github.com/rstudio/renv/issues/602
function(repo, record) {
with(record, file.path(repo, "src/contrib/Archive", Package, Version))
},
# format used by Nexus
# https://github.com/rstudio/renv/issues/595
function(repo, record) {
with(record, file.path(repo, "src/contrib"))
}
)
name <- renv_retrieve_repos_archive_name(record, "source")
for (formatter in formatters) {
root <- formatter(repo, record)
url <- file.path(root, name)
if (renv_download_available(url)) {
assign(repo, formatter, envir = the$repos_archive)
return(root)
}
}
}
# NOTE: If 'repo' is provided, it should be the path to the appropriate 'arm'
# of a repository, which is normally generated from the repository URL via
# 'contrib.url()'.
renv_retrieve_repos_impl <- function(record,
type = NULL,
name = NULL,
repo = NULL)
{
package <- record$Package
version <- record$Version
type <- type %||% attr(record, "type", exact = TRUE)
name <- name %||% renv_retrieve_repos_archive_name(record, type)
repo <- repo %||% attr(record, "url", exact = TRUE)
# if we weren't provided a repository for this package, try to find it
if (is.null(repo)) {
entry <- catch(
renv_available_packages_entry(
package = package,
type = type,
filter = version,
prefer = record[["Repository"]]
)
)
if (inherits(entry, "error")) {
attr(entry, "record") <- record
renv_condition_signal("renv.retrieve.error", entry)
return(FALSE)
}
# get repository path
repo <- entry$Repository
# add in the path if available
path <- entry$Path
if (length(path) && !is.na(path))
repo <- file.path(repo, path)
# update the tarball name if it was declared
file <- entry$File
if (length(file) && !is.na(file))
name <- file
}
url <- file.path(repo, name)
path <- renv_retrieve_path(record, type)
renv_retrieve_package(record, url, path)
}
renv_retrieve_package <- function(record, url, path) {
ensure_parent_directory(path)
type <- renv_record_source(record)
status <- local({
renv_scope_auth(record)
preamble <- renv_retrieve_package_preamble(record, url)
catch(download(url, preamble = preamble, destfile = path, type = type))
})
# report error for logging upstream
if (inherits(status, "error")) {
attr(status, "record") <- record
renv_condition_signal("renv.retrieve.error", status)
}
# handle FALSE returns (shouldn't normally happen?)
if (identical(status, FALSE)) {
fmt <- "an unknown error occurred installing '%s' (%s)"
msg <- sprintf(fmt, record$Package, renv_record_format_remote(record))
status <- simpleError(msg)
}
# handle errors
if (inherits(status, "error"))
stop(status)
# handle success
renv_retrieve_successful(record, path)
}
renv_retrieve_package_preamble <- function(record, url) {
message <- sprintf(
"- Downloading %s from %s ... ",
record$Package,
record$Repository %||% record$Source
)
format(message, width = the$install_step_width)
}
renv_retrieve_successful_subdir <- function(record, path) {
# if it's a file, assume RemoteSubdir needs to be honored
info <- file.info(path, extra_cols = FALSE)
if (identical(info$isdir, FALSE))
return(record$RemoteSubdir)
# otherwise, respect RemoteSubdir only if it seems to
# point at a valid DESCRPITION file
if (!is.null(record$RemoteSubdir)) {
parts <- c(path, record$RemoteSubdir, "DESCRIPTION")
descpath <- paste(parts, collapse = "/")
if (file.exists(descpath))
return(record$RemoteSubdir)
}
}
renv_retrieve_successful <- function(record, path, install = TRUE) {
# if we downloaded an archive, adjust its permissions here
mode <- Sys.getenv("RENV_CACHE_MODE", unset = NA)
if (!is.na(mode)) {
info <- file.info(path, extra_cols = FALSE)
if (identical(info$isdir, FALSE)) {
parent <- dirname(path)
renv_system_exec(
command = "chmod",
args = c("-Rf", renv_shell_quote(mode), renv_shell_path(parent)),
action = "chmoding cached package",
quiet = TRUE,
success = NULL
)
}
}
# the handling of 'subdir' here is a little awkward, as this function
# can receive:
#
# - archives, whose package might live within a sub-directory;
# - folders, whose package might live within a sub-directory;
# - cache paths, for which the subdir is no longer relevant
#
# this warrants a proper cleanup, but for now we we use a hack
subdir <- renv_retrieve_successful_subdir(record, path)
# augment record with information from DESCRIPTION file
desc <- renv_description_read(path, subdir = subdir)
# update the record's package name, version
# TODO: should we warn if they didn't match for some reason?
package <- record$Package <- desc$Package
record$Version <- desc$Version
# add in path information to record (used later during install)
record$Path <- path
# add information on the retrieved record
state <- renv_restore_state()
state$retrieved[[package]] <- record
# record this package's requirements
requirements <- state$requirements
# figure out the dependency fields to use -- if the user explicitly requested
# this package be installed, but also provided a 'dependencies' argument in
# the call to 'install()', then we want to use those
fields <- if (package %in% state$packages) the$install_dependency_fields else "strong"
deps <- renv_dependencies_discover_description(path, subdir = subdir, fields = fields)
if (length(deps$Source))
deps$Source <- record$Package
rowapply(deps, function(dep) {
package <- dep[["Package"]]
requirements[[package]] <- requirements[[package]] %||% stack()
requirements[[package]]$push(dep)
})
# read and handle remotes declared by this package
remotes <- desc$Remotes
if (length(remotes) && config$install.remotes())
renv_retrieve_remotes(remotes)
# ensure its dependencies are retrieved as well
if (state$recursive) local({
repos <- if (is.null(desc$biocViews)) getOption("repos") else renv_bioconductor_repos()
renv_scope_options(repos = repos)
renv_retrieve_successful_recurse(deps)
})
# mark package as requiring install if needed
if (install && !state$install$contains(package))
state$install$insert(package, record)
TRUE
}
renv_retrieve_successful_recurse <- function(deps) {
remotes <- setdiff(unique(deps$Package), renv_packages_base())
for (remote in remotes)
renv_retrieve_successful_recurse_impl(remote)
}
renv_retrieve_successful_recurse_impl_check <- function(remote) {
# only done for package names
if (!grepl(renv_regexps_package_name(), remote))
return(FALSE)
# check whether this package has been retrieved yet
state <- renv_restore_state()
record <- state$retrieved[[remote]]
if (is.null(record))
return(FALSE)
# check the current requirements for this package
incompat <- renv_retrieve_incompatible(remote, record)
if (NROW(incompat) == 0L)
return(FALSE)
# we have an incompatible record; ensure it gets retrieved
state$retrieved[[remote]] <- NULL
TRUE
}
renv_retrieve_successful_recurse_impl <- function(remote) {
# if remote is a plain package name that we've already retrieved,
# we may need to retrieve it again if the version of that package
# required is greater than the previously-obtained version
#
# TODO: implement a proper solver so we can stop doing these hacks...
# if this is a 'plain' package remote, retrieve it
force <- renv_retrieve_successful_recurse_impl_check(remote)
dynamic(
key = list(remote = remote),
value = renv_retrieve_successful_recurse_impl_one(remote),
force = force
)
}
renv_retrieve_successful_recurse_impl_one <- function(remote) {
# ignore base packages
base <- renv_packages_base()
if (remote %in% base)
return(list())
# if this is a 'plain' package remote, retrieve it
if (grepl(renv_regexps_package_name(), remote)) {
renv_retrieve_impl(remote)
return(list())
}
# otherwise, handle custom remotes
record <- renv_retrieve_remotes_impl(remote)
if (length(record)) {
renv_retrieve_impl(record$Package)
return(list())
}
list()
}
renv_retrieve_unknown_source <- function(record) {
# try to find a matching local package
status <- catch(renv_retrieve_cellar(record))
if (!inherits(status, "error"))
return(status)
# failed; parse as though from R package repository
record$Source <- "Repository"
renv_retrieve_repos(record)
}
# TODO: what should we do if we detect incompatible remotes?
# e.g. if pkg A requests 'r-lib/rlang@0.3' but pkg B requests
# 'r-lib/rlang@0.2'.
renv_retrieve_remotes <- function(remotes) {
remotes <- strsplit(remotes, "\\s*,\\s*")[[1L]]
for (remote in remotes)
renv_retrieve_remotes_impl(remote)
}
renv_retrieve_remotes_impl <- function(remote) {
dynamic(
key = list(remote = remote),
value = renv_retrieve_remotes_impl_one(remote)
)
}
renv_retrieve_remotes_impl_one <- function(remote) {
# TODO: allow customization of behavior when remote parsing fails?
resolved <- catch(renv_remotes_resolve(remote))
if (inherits(resolved, "error")) {
warningf("failed to resolve remote '%s'; skipping", remote)
return(invisible(NULL))
}
# get the current package record
state <- renv_restore_state()
package <- resolved$Package
record <- state$records[[package]]
# if we already have a package record, and it's not a 'plain'
# repository record, skip
skip <-
!is.null(record) &&
!identical(record, list(Package = package, Source = "Repository"))
if (skip) {
dlog("retrieve", "skipping remote '%s'; it's already been declared", remote)
dlog("retrieve", "using existing remote '%s'", stringify(record))
return(invisible(NULL))
}
# update the requested record
dlog("retrieve", "using remote '%s'", remote)
state$records[[package]] <- resolved
# mark the record as needing retrieval
state$retrieved[[package]] <- NULL
# return new record
invisible(resolved)
}
renv_retrieve_resolve <- function(package) {
tryCatch(
renv_snapshot_description(package = package),
error = function(e) {
renv_retrieve_missing_record(package)
}
)
}
renv_retrieve_missing_record <- function(package) {
# TODO: allow users to configure the action to take here, e.g.
#
# 1. retrieve latest from R repositories (the default),
# 2. request a package + version to be retrieved,
# 3. hard error
#
record <- renv_available_packages_latest(package)
if (!is.null(record))
return(record)
fmt <- heredoc("
renv was unable to find a compatible version of package '%1$s'.
The latest-available version %1$s is '%2$s', but that version
does not appear to be compatible with this version of R.
You may need to manually re-install a different version of '%1$s'.
")
entry <- renv_available_packages_entry(package, type = "source")
version <- entry$Version %||% ""
writef(fmt, package, version)
stopf("failed to find a compatible version of the '%s' package", package)
}
# check to see if this requested record is incompatible
# with the set of required dependencies recorded thus far
# during the package retrieval process
renv_retrieve_incompatible <- function(package, record) {
state <- renv_restore_state()
record <- renv_record_validate(package, record)
# check and see if the installed version satisfies all requirements
requirements <- state$requirements[[package]]
if (is.null(requirements))
return(NULL)
data <- bind(requirements$data())
explicit <- data[nzchar(data$Require) & nzchar(data$Version), ]
if (nrow(explicit) == 0)
return(NULL)
# drop 'Dev' column
explicit$Dev <- NULL
# retrieve record version
version <- record$Version
if (is.null(version))
return(NULL)
# for each row, compute whether we're compatible
rversion <- numeric_version(version)
compatible <- map_lgl(seq_len(nrow(explicit)), function(i) {
expr <- call(explicit$Require[[i]], rversion, explicit$Version[[i]])
eval(expr, envir = baseenv())
})
# keep whatever wasn't compatible
explicit[!compatible, ]
}
renv_retrieve_incompatible_report <- function(package, record, replacement, compat) {
# only report if the user explicitly requesting installation of a particular
# version of a package, but that package isn't actually compatible
state <- renv_restore_state()
if (!package %in% state$packages)
return()
fmt <- "%s (requires %s %s %s)"
values <- with(compat, sprintf(fmt, Source, Package, Require, Version))
fmt <- "Installation of '%s %s' was requested, but the following constraints are not met:"
preamble <- with(record, sprintf(fmt, Package, Version))
fmt <- "renv will try to install '%s %s' instead."
postamble <- with(replacement, sprintf(fmt, Package, Version))
if (!renv_tests_running()) {
caution_bullets(
preamble = preamble,
values = values,
postamble = postamble
)
}
}
renv_retrieve_origin <- function(host) {
# NOTE: some host URLs may come with a protocol already formed;
# if we find a protocol, use it as-is
if (grepl("://", host, fixed = TRUE))
return(host)
# otherwise, prepend protocol (assume https)
paste("https", host, sep = "://")
}
renv/R/packages.R 0000644 0001762 0000144 00000000716 14464550375 013347 0 ustar ligges users
the$packages_base <- NULL
the$packages_recommended <- NULL
renv_packages_base <- function() {
the$packages_base <- the$packages_base %||% {
db <- installed_packages(lib.loc = .Library, priority = "base")
c("R", db$Package, "translations")
}
}
renv_packages_recommended <- function() {
the$packages_recommended <- the$packages_recommended %||% {
db <- installed_packages(lib.loc = .Library, priority = "recommended")
db$Package
}
}
renv/R/python.R 0000644 0001762 0000144 00000025112 14533701145 013075 0 ustar ligges users
renv_python_resolve <- function(python = NULL) {
# if Python was explicitly supplied, use it
if (!is.null(python)) {
resolved <- Sys.which(renv_path_canonicalize(python))
if (nzchar(resolved))
return(resolved)
stopf("'%s' does not refer to a valid python interpreter", python)
}
# in interactive sessions, ask user what version of python they'd like to use
if (interactive()) {
python <- renv_python_select()
fmt <- "- Selected %s [Python %s]."
writef(fmt, renv_path_pretty(python), renv_python_version(python))
return(path.expand(python))
}
# check environment variables
envvars <- c("RETICULATE_PYTHON", "RETICULATE_PYTHON_ENV")
for (envvar in envvars) {
val <- Sys.getenv(envvar, unset = NA)
if (!is.na(val) && file.exists(val))
return(val)
}
# check on the PATH (prefer Python 3)
for (binary in c("python3", "python")) {
python <- Sys.which(binary)
if (nzchar(python))
return(python)
}
stopf("could not locate Python (not available on the PATH)")
}
renv_python_find <- function(version, path = NULL) {
renv_python_find_impl(version, path)
}
renv_python_find_impl <- function(version, path = NULL) {
# if we've been given the name of an environment,
# check to see if it's already been initialized
# and use the associated copy of Python if possible
if (!is.null(path) && file.exists(path)) {
python <- catch(renv_python_exe(path))
if (!inherits(python, "error"))
return(python)
}
# try to find a compatible version of python
pythons <- renv_python_discover()
if (length(pythons) == 0) {
fmt <- lines(
"project requested Python %s, but no compatible Python installation could be found.",
"renv's Python integration will be disabled in this session.",
"See `?renv::use_python` for more details."
)
stopf(fmt, version)
}
# read python versions
pyversions <- map_chr(pythons, function(python) {
tryCatch(
renv_python_version(python),
error = function(e) "0.0.0"
)
})
# try to find a compatible version
renv_version_match(pyversions, version)
}
renv_python_exe <- function(path) {
# if this already looks like a Python executable, use it directly
info <- renv_file_info(path)
if (identical(info$isdir, FALSE) && startswith(basename(path), "python"))
return(renv_path_canonicalize(path))
# otherwise, attempt to infer the Python executable type
info <- renv_python_info(path)
if (!is.null(info$python))
return(renv_path_canonicalize(info$python))
fmt <- "failed to find Python executable associated with path %s"
stopf(fmt, renv_path_pretty(path))
}
renv_python_version <- function(python) {
filebacked(
context = "renv_python_version",
path = renv_path_normalize(python),
callback = renv_python_version_impl
)
}
renv_python_version_impl <- function(python) {
python <- renv_path_canonicalize(python)
code <- "from platform import python_version; print(python_version())"
args <- c("-c", shQuote(code))
action <- "reading Python version"
renv_system_exec(python, args, action)
}
renv_python_info <- function(python) {
found <- renv_file_find(python, function(path) {
# check for virtual environment files
virtualenv <-
file.exists(file.path(path, "pyvenv.cfg")) ||
file.exists(file.path(path, ".Python")) ||
file.exists(file.path(path, "bin/activate_this.py"))
if (virtualenv) {
suffix <- if (renv_platform_windows()) "Scripts/python.exe" else "bin/python"
python <- file.path(path, suffix)
return(list(python = python, type = "virtualenv", root = path))
}
# check for conda-meta
condaenv <-
file.exists(file.path(path, "conda-meta")) &&
!file.exists(file.path(path, "condabin"))
if (condaenv) {
suffix <- if (renv_platform_windows()) "python.exe" else "bin/python"
python <- file.path(path, suffix)
return(list(python = python, type = "conda", root = path))
}
})
if (!is.null(found))
return(found)
if (file.exists(python))
list(python = python, type = "system", root = python)
}
renv_python_type <- function(python) {
info <- renv_python_info(python)
info$type
}
renv_python_action <- function(action, prompt, project) {
python <- Sys.getenv("RENV_PYTHON", unset = NA)
if (is.na(python) || !file.exists(python))
return(NULL)
type <- renv_python_type(python)
if (is.null(type))
return(NULL)
if (type == "conda" && !requireNamespace("reticulate", quietly = TRUE))
return(NULL)
action(python, type, prompt, project)
}
renv_python_snapshot <- function(project, prompt) {
renv_python_action(
renv_python_snapshot_impl,
prompt = prompt,
project = project
)
}
renv_python_snapshot_impl <- function(python, type, prompt, project) {
switch(type,
virtualenv = renv_python_virtualenv_snapshot(project, prompt, python),
conda = renv_python_conda_snapshot(project, prompt, python)
)
}
renv_python_restore <- function(project, prompt) {
renv_python_action(
renv_python_restore_impl,
prompt = prompt,
project = project
)
}
renv_python_restore_impl <- function(python, type, prompt, project) {
case(
type == "virtualenv" ~ renv_python_virtualenv_restore(project, prompt, python),
type == "conda" ~ renv_python_conda_restore(project, prompt, python)
)
}
renv_python_envpath_virtualenv <- function(version) {
sprintf("python/virtualenvs/renv-python-%s", renv_version_maj_min(version))
}
renv_python_envpath_condaenv <- function(version) {
"python/condaenvs/renv-python"
}
renv_python_envpath <- function(project, type, version = NULL) {
suffix <- case(
type == "virtualenv" ~ renv_python_envpath_virtualenv(version),
type == "conda" ~ renv_python_envpath_condaenv(version),
~ stopf("internal error: unrecognized environment type '%s'", type)
)
renv_paths_renv(suffix, project = project)
}
renv_python_envname <- function(project, path, type) {
# check for a project-local environment
if (renv_path_within(path, project)) {
stem <- substring(path, nchar(project) + 2L)
path <- paste(".", stem, sep = "/")
return(path)
}
bn <- basename(path)
# check for file within virtualenv
ok <-
type == "virtualenv" &&
identical(renv_python_virtualenv_path(bn), path)
if (ok)
return(bn)
# check for named conda environment
ok <-
type == "conda" &&
bn %in% reticulate::conda_list()$name
if (ok)
return(bn)
# doesn't match any known named environments; return full path
path
}
renv_python_discover <- function() {
all <- stack()
# find python in some pre-determined root directories
roots <- c(
getOption("renv.python.root"),
Sys.getenv("WORKON_HOME", "~/.virtualenvs"),
"/opt/python",
"/opt/local/python",
"~/opt/python",
file.path(renv_pyenv_root(), "versions")
)
for (root in roots) {
versions <- sort(list.files(root, full.names = TRUE), decreasing = TRUE)
exts <- if (renv_platform_windows()) "Scripts/python.exe" else "bin/python"
pythons <- file.path(versions, exts)
all$push(pythons)
}
# find Homebrew python
if (renv_platform_macos()) {
homebrew <- renv_homebrew_root()
roots <- sort(list.files(
path = file.path(homebrew, "opt"),
pattern = "^python@[[:digit:]]+[.][[:digit:]]+$",
full.names = TRUE
), decreasing = TRUE)
for (root in roots) {
# homebrew python doesn't install bin/python, so we need
# to be a little bit more clever here
exes <- list.files(
path = file.path(root, "bin"),
pattern = "^python[[:digit:]]+[.][[:digit:]]+$",
full.names = TRUE
)
if (length(exes))
all$push(exes[[1L]])
}
}
# find Windows python installations
if (renv_platform_windows()) {
sd <- Sys.getenv("SYSTEMDRIVE", unset = "C:")
roots <- file.path(sd, c("", "Program Files"))
lad <- Sys.getenv("LOCALAPPDATA", unset = NA)
if (!is.na(lad))
roots <- c(roots, file.path(lad, "Programs/Python"))
dirs <- list.files(
path = roots,
pattern = "^Python",
full.names = TRUE
)
if (length(dirs)) {
exes <- file.path(dirs, "python.exe")
pythons <- renv_path_normalize(exes)
all$push(pythons)
}
}
# find Python installations on the PATH
path <- Sys.getenv("PATH", unset = "")
splat <- strsplit(path, .Platform$path.sep, fixed = TRUE)[[1L]]
for (entry in splat) {
for (exe in c("python3", "python")) {
python <- Sys.which(file.path(entry, exe))
if (nzchar(python))
all$push(python)
}
}
# collect discovered pythons as vector
pythons <- unlist(all$data(), recursive = FALSE, use.names = TRUE)
# don't include /usr/bin/python on macOS (too old)
if (renv_platform_macos())
pythons <- setdiff(pythons, "/usr/bin/python")
# get list of pythons
pythons <- renv_path_canonicalize(pythons[file.exists(pythons)])
# don't include WindowsApps
if (renv_platform_windows())
pythons <- grep("/WindowsApps/", pythons, invert = TRUE, value = TRUE)
unique(pythons)
}
renv_python_select_error <- function() {
lines <- c(
"renv was unable to find any Python installations on your machine.",
if (renv_platform_windows())
"Consider installing Python from https://www.python.org/downloads/windows/.",
if (renv_platform_macos())
"Consider installing Python from https://www.python.org/downloads/mac-osx/."
)
stop(paste(lines, collapse = "\n"))
}
renv_python_select <- function(candidates = NULL) {
candidates <- renv_path_aliased(candidates %||% renv_python_discover())
if (empty(candidates))
return(renv_python_select_error())
title <- "Please select a version of Python to use with this project:"
selection <- tryCatch(
utils::select.list(candidates, title = title, graphics = FALSE),
interrupt = identity
)
if (selection %in% "" || inherits(selection, "interrupt"))
stop("operation canceled by user")
return(path.expand(selection))
}
renv_python_module_available <- function(python, module) {
python <- renv_path_canonicalize(python)
command <- paste("import", module)
args <- c("-c", shQuote(command))
status <- system2(python, args, stdout = FALSE, stderr = FALSE)
identical(status, 0L)
}
renv_python_active <- function() {
python <- Sys.getenv("RENV_PYTHON", unset = NA)
if (is.na(python))
stop("internal error: RENV_PYTHON is not set")
renv_python_validate(python)
}
renv_python_validate <- function(python) {
if (!file.exists(python)) {
fmt <- "python %s does not exist"
stopf(fmt, renv_path_pretty(python))
}
invisible(python)
}
renv/R/tests.R 0000644 0001762 0000144 00000007417 14466465760 012745 0 ustar ligges users
the$tests_root <- NULL
# NOTE: Prefer using 'testing()' to 'renv_tests_running()' for behavior
# that should apply regardless of the package currently being tested.
#
# renv_tests_running() is appropriate when running renv's own tests.
renv_tests_running <- function() {
getOption("renv.tests.running", default = FALSE)
}
renv_test_code <- function(code, data = list(), fileext = ".R", scope = parent.frame()) {
code <- do.call(substitute, list(substitute(code), data))
file <- renv_scope_tempfile("renv-code-", fileext = fileext, scope = scope)
writeLines(deparse(code), con = file)
file
}
renv_test_retrieve <- function(record) {
renv_scope_error_handler()
# avoid using cache
cache <- renv_scope_tempfile()
renv_scope_envvars(RENV_PATHS_CACHE = cache)
# construct records
package <- record$Package
records <- list(record)
names(records) <- package
# prepare dummy library
templib <- renv_scope_tempfile("renv-library-")
ensure_directory(templib)
renv_scope_libpaths(c(templib, .libPaths()))
# attempt a restore into that library
renv_scope_restore(
project = getwd(),
library = templib,
records = records,
packages = package,
recursive = TRUE
)
records <- retrieve(record$Package)
renv_install_impl(records)
descpath <- file.path(templib, package)
if (!file.exists(descpath))
stopf("failed to retrieve package '%s'", package)
desc <- renv_description_read(descpath)
fields <- grep("^Remote", names(record), value = TRUE)
testthat::expect_identical(
as.list(desc[fields]),
as.list(record[fields])
)
}
renv_tests_diagnostics <- function() {
# print library paths
caution_bullets(
"The following R libraries are set:",
paste("-", .libPaths())
)
# print repositories
repos <- getOption("repos")
caution_bullets(
"The following repositories are set:",
paste(names(repos), repos, sep = ": ")
)
# print renv root
caution_bullets(
"The following renv root directory is being used:",
paste("-", paths$root())
)
# print cache root
caution_bullets(
"The following renv cache directory is being used:",
paste("-", paths$cache())
)
writeLines("The following packages are available in the test repositories:")
dbs <-
available_packages(type = "source", quiet = TRUE) %>%
map(function(db) {
rownames(db) <- NULL
db[c("Package", "Version", "File")]
})
print(dbs)
path <- Sys.getenv("PATH")
splat <- strsplit(path, .Platform$path.sep, fixed = TRUE)[[1]]
caution_bullets(
"The following PATH is set:",
paste("-", splat)
)
envvars <- c(
grep("^_R_", names(Sys.getenv()), value = TRUE),
"HOME",
"R_ARCH", "R_HOME",
"R_LIBS", "R_LIBS_SITE", "R_LIBS_USER", "R_USER",
"R_ZIPCMD",
"TAR", "TEMP", "TMP", "TMPDIR"
)
keys <- format(envvars)
vals <- Sys.getenv(envvars, unset = "")
vals[vals != ""] <- renv_json_quote(vals[vals != ""])
caution_bullets(
"The following environment variables of interest are set:",
paste(keys, vals, sep = " : ")
)
}
renv_tests_root <- function() {
the$tests_root <- the$tests_root %||% {
renv_path_normalize(testthat::test_path("."))
}
}
renv_tests_path <- function(path = NULL) {
# special case for NULL path
if (is.null(path))
return(renv_tests_root())
# otherwise, form path from root
file.path(renv_tests_root(), path)
}
renv_tests_supported <- function() {
# supported when running locally + on CI
for (envvar in c("NOT_CRAN", "CI"))
if (renv_envvar_exists(envvar))
return(TRUE)
# disabled on older macOS releases (credentials fails to load)
if (renv_platform_macos() && getRversion() < "4.0.0")
return(FALSE)
# disabled on Windows
if (renv_platform_windows())
return(FALSE)
# true otherwise
TRUE
}
renv/R/shell.R 0000644 0001762 0000144 00000000226 14257631444 012671 0 ustar ligges users
renv_shell_quote <- function(x) {
if (length(x))
shQuote(x)
}
renv_shell_path <- function(x) {
if (length(x))
shQuote(path.expand(x))
}
renv/R/options.R 0000644 0001762 0000144 00000001450 14547051446 013255 0 ustar ligges users
renv_options_set <- function(key, value) {
data <- list(value)
names(data) <- key
do.call(base::options, data)
}
renv_options_resolve <- function(value, arguments) {
if (is.function(value))
return(do.call(value, arguments))
value
}
renv_options_override <- function(scope, key, default = NULL, extra = NULL) {
# first, check for scoped option
value <- getOption(paste(scope, key, sep = "."))
if (!is.null(value))
return(renv_options_resolve(value, list(extra)))
# next, check for unscoped option
value <- getOption(scope)
if (key %in% names(value))
return(renv_options_resolve(value[[key]], list(extra)))
# check for functional value
if (is.function(value))
return(renv_options_resolve(value, list(key, extra)))
# nothing found; use default
default
}
renv/R/report.R 0000644 0001762 0000144 00000000723 14563502050 013065 0 ustar ligges users
renv_report_ok <- function(message, elapsed = 0, verbose = FALSE) {
# handle verbose printing first
if (verbose) {
fmt <- "- OK [%s in %s]"
return(writef(fmt, message, renv_difftime_format_short(elapsed)))
}
# treat 'quick' times specially
if (!testing() && elapsed < 0.1)
return(writef("OK [%s]", message))
# otherwise, report step with elapsed time
fmt <- "OK [%s in %s]"
writef(fmt, message, renv_difftime_format_short(elapsed))
}
renv/R/version.R 0000644 0001762 0000144 00000004260 14447410053 013241 0 ustar ligges users
renv_version_compare <- function(lhs, rhs, n = NULL) {
# retrieve versions as integer vector
lhs <- unlist(unclass(numeric_version(lhs)))
rhs <- unlist(unclass(numeric_version(rhs)))
# compute number of components to compare
n <- n %||% max(length(lhs), length(rhs))
# pad each vector with zeroes up to the requested length
lhs <- c(lhs, rep.int(0L, max(0L, n - length(lhs))))
rhs <- c(rhs, rep.int(0L, max(0L, n - length(rhs))))
# iterate through each component and compare
for (i in seq_len(n)) {
if (lhs[[i]] < rhs[[i]])
return(-1L)
else if (lhs[[i]] > rhs[[i]])
return(+1L)
}
# if we got here, then all components compared equal
0L
}
renv_version_le <- function(lhs, rhs, n = NULL) {
renv_version_compare(lhs, rhs, n) <= 0L
}
renv_version_lt <- function(lhs, rhs, n = NULL) {
renv_version_compare(lhs, rhs, n) < 0L
}
renv_version_eq <- function(lhs, rhs, n = NULL) {
renv_version_compare(lhs, rhs, n) == 0L
}
renv_version_gt <- function(lhs, rhs, n = NULL) {
renv_version_compare(lhs, rhs, n) > 0L
}
renv_version_ge <- function(lhs, rhs, n = NULL) {
renv_version_compare(lhs, rhs, n) >= 0L
}
renv_version_match <- function(versions, request) {
nrequest <- unclass(numeric_version(request))[[1L]]
for (i in rev(seq_along(nrequest))) {
matches <- which(map_lgl(versions, function(version) {
renv_version_eq(version, request, n = i)
}))
if (!length(matches))
next
# TODO: should '3.1' match the closest match (e.g. '3.2') or
# highest match (e.g. '3.6')?
sorted <- matches[sort(names(matches), decreasing = TRUE)]
return(names(sorted)[[1L]])
}
versions[[1L]]
}
renv_version_parts <- function(version, n) {
# split version into parts
parts <- unclass(as.numeric_version(version))[[1L]]
# extend parts to size of n
diff <- max(n) - length(parts)
if (diff > 0)
parts <- c(parts, rep.int(0L, diff))
# retrieve possibly-extended parts
parts[1:n]
}
renv_version_maj_min <- function(version) {
parts <- renv_version_parts(version, 2L)
paste(parts, collapse = ".")
}
renv_version_length <- function(version) {
nv <- as.numeric_version(version)
length(unclass(nv)[[1L]])
}
renv/R/abort.R 0000644 0001762 0000144 00000002504 14464550375 012675 0 ustar ligges users
abort <- function(message, ..., body = NULL, class = NULL) {
# create condition object
cnd <- if (is.character(message)) {
structure(class = c(class, "error", "condition"), list(
message = paste(c(message, body), collapse = "\n"),
meta = list(message = message, body = body),
...
))
} else if (inherits(message, "condition")) {
message
} else {
stop("internal error: abort called with unexpected message")
}
# if we were called with a custom condition object not having our meta,
# just throw it as-is
if (is.null(cnd$meta))
stop(cnd)
# signal the condition, giving calling handlers a chance to run first
signalCondition(cnd)
# if we got here, then there wasn't any tryCatch() handler on the stack.
# handle printing of the error ourselves, and then stop with fallback.
all <- c(
cnd$meta$body, if (length(cnd$meta$body)) "",
paste("Error:", paste(cnd$meta$message, collapse = "\n"))
)
# write error message to stderr, as errors might normally do
writeLines(all, con = stderr())
# create the fallback, but 'dodge' the existing error handlers
fallback <- cnd
fallback$message <- ""
class(fallback) <- "condition"
# disable error printing for the empty error
renv_scope_options(show.error.messages = FALSE)
# now throw the error
stop(fallback)
}
renv/R/robocopy.R 0000644 0001762 0000144 00000001426 14257631444 013421 0 ustar ligges users
renv_robocopy_exec <- function(source, target, flags = NULL) {
source <- path.expand(source)
target <- path.expand(target)
# add other flags
flags <- c(flags, "/E", "/Z", "/R:5", "/W:10")
# https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/robocopy
# > Any value greater than 8 indicates that there was at least one failure
# > during the copy operation.
renv_system_exec(
command = "robocopy",
args = c(flags, renv_shell_path(source), renv_shell_path(target)),
action = "copying directory",
success = 0:8,
quiet = TRUE
)
}
renv_robocopy_copy <- function(source, target) {
renv_robocopy_exec(source, target)
}
renv_robocopy_move <- function(source, target) {
renv_robocopy_exec(source, target, "/MOVE")
}
renv/R/record.R 0000644 0001762 0000144 00000006553 14603027616 013044 0 ustar ligges users
#' Update package records in a lockfile
#'
#' Use `record()` to record a new entry within an existing renv lockfile.
#'
#' This function can be useful when you need to change one or more of the
#' package records within an renv lockfile -- for example, because a recorded
#' package cannot be restored in a particular environment, and you know of a
#' suitable alternative.
#'
#' # Records
#'
#' Records can be provided either using the **remotes** short-hand syntax,
#' or by using an \R list of entries to record within the lockfile. See
#' `?lockfiles` for more information on the structure of a package record.
#'
#' @inheritParams renv-params
#'
#' @param records A list of named records, mapping package names to a definition
#' of their source. See **Records** for more details.
#'
#' @example examples/examples-record.R
#' @export
record <- function(records,
lockfile = NULL,
project = NULL)
{
renv_scope_error_handler()
project <- renv_project_resolve(project)
renv_project_lock(project = project)
lockfile <- lockfile %||% renv_lockfile_path(project)
records <- case(
is.character(records) ~ lapply(records, renv_remotes_resolve, latest = TRUE),
is.list(records) ~ renv_records_resolve(records, latest = TRUE),
~ stopf("unexpected records format '%s'", typeof(records))
)
names(records) <- enum_chr(records, function(package, record) {
if (is.null(package) || is.na(package) || !nzchar(package))
record[["Package"]]
else
package
})
if (is.list(lockfile))
return(renv_lockfile_modify(lockfile, records))
if (!file.exists(lockfile)) {
fmt <- "no lockfile exists at path %s"
stopf(fmt, renv_path_pretty(lockfile))
}
old <- renv_lockfile_read(lockfile)
new <- renv_lockfile_modify(old, records)
local({
renv_scope_options(renv.verbose = FALSE)
renv_lockfile_write(new, lockfile)
})
n <- length(records)
fmt <- "- Updated %s in %s."
writef(fmt, nplural("record", n), renv_path_pretty(lockfile))
renv <- records[["renv"]]
if (!is.null(renv) && !is.null(renv[["Version"]])) {
renv_infrastructure_write_activate(
project = project,
version = renv[["Version"]]
)
}
invisible(lockfile)
}
renv_record_normalize <- function(record) {
# normalize source
source <- record$Source %||% "unknown"
if (source %in% c("CRAN", "P3M", "PPM", "RSPM"))
record$Source <- "Repository"
# drop remotes from records with a repository source
if (renv_record_cranlike(record))
record <- record[grep("^Remote", names(record), invert = TRUE)]
# keep only specific records for comparison
remotes <- grep("^Remote", names(record), value = TRUE)
keep <- c("Package", "Version", "Source", remotes)
record <- record[intersect(names(record), keep)]
# return normalized record
record
}
renv_record_tag <- function(record, type, url, name) {
attr(record, "url") <- url
attr(record, "type") <- type
attr(record, "name") <- name
record
}
renv_record_tagged <- function(record) {
attrs <- attributes(record)
all(c("url", "type") %in% names(attrs))
}
# abstracted out in case we want to use a different sigil in the future,
# like `_`, ``, or something else
renv_record_placeholder <- function() {
"*"
}
renv_record_cranlike <- function(record) {
type <- record[["RemoteType"]]
is.null(type) || type %in% c("cran", "standard")
}
renv/R/rehash.R 0000644 0001762 0000144 00000004664 14500176536 013043 0 ustar ligges users
#' Re-hash packages in the renv cache
#'
#' Re-hash packages in the renv cache, ensuring that any previously-cached
#' packages are copied to a new cache location appropriate for this version of
#' renv. This can be useful if the cache scheme has changed in a new version
#' of renv, but you'd like to preserve your previously-cached packages.
#'
#' Any packages which are re-hashed will retain links to the location of the
#' newly-hashed package, ensuring that prior installations of renv can still
#' function as expected.
#'
#' @inheritParams renv-params
#'
#' @export
rehash <- function(prompt = interactive(), ...) {
renv_scope_error_handler()
renv_dots_check(...)
renv_scope_verbose_if(prompt)
invisible(renv_rehash_impl(prompt))
}
renv_rehash_impl <- function(prompt) {
# check for cache migration
oldcache <- renv_paths_cache(version = renv_cache_version_previous())[[1L]]
newcache <- renv_paths_cache(version = renv_cache_version())[[1L]]
if (file.exists(oldcache) && !file.exists(newcache))
renv_rehash_cache(oldcache, prompt, renv_file_copy, "copied")
# re-cache packages as necessary
renv_rehash_cache(newcache, prompt, renv_file_move, "moved")
}
renv_rehash_cache <- function(cache, prompt, action, label) {
# re-compute package hashes
old <- renv_cache_list(cache = cache)
printf("- Re-computing package hashes ... ")
new <- map_chr(old, renv_progress_callback(renv_cache_path, length(old)))
writef("Done!")
changed <- which(old != new & file.exists(old) & !file.exists(new))
if (empty(changed)) {
writef("- Your cache is already up-to-date -- nothing to do.")
return(TRUE)
}
if (prompt) {
fmt <- "%s [%s -> %s]"
packages <- basename(old)[changed]
oldhash <- renv_path_component(old[changed], 2L)
newhash <- renv_path_component(new[changed], 2L)
caution_bullets(
"The following packages will be re-cached:",
sprintf(fmt, format(packages), format(oldhash), format(newhash)),
sprintf("Packages will be %s to their new locations in the cache.", label)
)
cancel_if(prompt && !proceed())
}
sources <- old[changed]
targets <- new[changed]
names(sources) <- targets
names(targets) <- sources
printf("- Re-caching packages ... ")
enumerate(targets, renv_progress_callback(action, length(targets)))
writef("Done!")
n <- length(targets)
fmt <- "Successfully re-cached %s."
writef(fmt, nplural("package", n))
renv_cache_clean_empty()
TRUE
}
renv/R/files.R 0000644 0001762 0000144 00000041274 14567713007 012674 0 ustar ligges users
# NOTE: all methods here should either return TRUE if they were able to
# operate successfully, or throw an error if not
#
# TODO: some of these operations are a bit racy
renv_file_preface <- function(source, target, overwrite) {
callback <- function() {}
if (!renv_file_exists(source))
stopf("source file '%s' does not exist", source)
if (overwrite)
callback <- renv_file_backup(target)
if (renv_file_exists(target))
stopf("target file '%s' already exists", target)
callback
}
renv_file_copy <- function(source, target, overwrite = FALSE) {
if (renv_file_same(source, target))
return(TRUE)
callback <- renv_file_preface(source, target, overwrite)
defer(callback())
# check to see if we're copying a plain file -- if so, things are simpler
if (dir.exists(source))
renv_file_copy_dir(source, target)
else
renv_file_copy_file(source, target)
}
renv_file_copy_file <- function(source, target) {
# copy to temporary path
tmpfile <- renv_scope_tempfile(".renv-copy-", tmpdir = dirname(target))
status <- catchall(file.copy(source, tmpfile))
if (inherits(status, "condition"))
stop(status)
# move from temporary path to final target
status <- catchall(renv_file_move(tmpfile, target))
if (inherits(status, "condition"))
stop(status)
# validate that the target file exists
if (!renv_file_exists(target)) {
fmt <- "attempt to copy file %s to %s failed (unknown reason)"
stopf(fmt, renv_path_pretty(source), renv_path_pretty(target))
}
invisible(TRUE)
}
renv_file_copy_dir_robocopy <- function(source, target) {
renv_robocopy_copy(source, target)
}
# TODO: the version of rsync distributed with macOS
# does not reliably copy file modified times, etc.
renv_file_copy_dir_rsync <- function(source, target) {
source <- sub("/*$", "/", source)
flags <- if (renv_platform_macos()) "-aAX" else "-a"
args <- c(flags, renv_shell_path(source), renv_shell_path(target))
renv_system_exec("rsync", args, action = "copying directory")
}
renv_file_copy_dir_cp <- function(source, target) {
# ensure 'source' ends with a single trailing slash
source <- sub("/*$", "/", source)
# ensure tildes are path-expanded
source <- path.expand(source)
target <- path.expand(target)
# build 'cp' arguments
args <- c("-PR", renv_shell_path(source), renv_shell_path(target))
# execute command
renv_system_exec("cp", args, action = "copying directory")
}
renv_file_copy_dir_r <- function(source, target) {
# create sub-directory to host copy attempt
tempdir <- renv_scope_tempfile(".renv-copy-", tmpdir = dirname(target))
ensure_directory(tempdir)
# attempt to copy to generated folder
status <- catchall(
file.copy(
source,
tempdir,
recursive = TRUE,
copy.mode = TRUE,
copy.date = TRUE
)
)
if (inherits(status, "error"))
stop(status)
# R will copy the directory to a sub-directory in the
# requested folder with the same filename as the source
# folder, so peek into that folder to grab it and rename
tempfile <- file.path(tempdir, basename(source))
status <- catchall(renv_file_move(tempfile, target))
if (inherits(status, "condition"))
stop(status)
}
renv_file_copy_dir_impl <- function(source, target) {
methods <- list(
cp = renv_file_copy_dir_cp,
r = renv_file_copy_dir_r,
robocopy = renv_file_copy_dir_robocopy,
rsync = renv_file_copy_dir_rsync
)
copy <- config$copy.method()
if (is.function(copy))
return(copy(source, target))
method <- methods[[tolower(copy)]]
if (!is.null(method))
return(method(source, target))
if (renv_platform_windows())
renv_file_copy_dir_robocopy(source, target)
else if (renv_platform_unix())
renv_file_copy_dir_cp(source, target)
else
renv_file_copy_dir_r(source, target)
file.exists(target)
}
renv_file_copy_dir <- function(source, target) {
# create temporary sub-directory
tmpdir <- dirname(target)
ensure_directory(tmpdir)
tempdir <- renv_scope_tempfile(".renv-copy-", tmpdir = tmpdir)
# copy to that directory
status <- catchall(renv_file_copy_dir_impl(source, tempdir))
if (inherits(status, "condition"))
stop(status)
# move directory to final location
status <- catchall(renv_file_move(tempdir, target))
if (inherits(status, "condition"))
stop(status)
# validate that the target file exists
if (!renv_file_exists(target)) {
fmt <- "attempt to copy directory %s to %s failed (unknown reason)"
stopf(fmt, renv_path_pretty(source), renv_path_pretty(target))
}
invisible(TRUE)
}
renv_file_move <- function(source, target, overwrite = FALSE) {
if (renv_file_same(source, target))
return(TRUE)
callback <- renv_file_preface(source, target, overwrite)
defer(callback())
# first, attempt to do a plain rename
# use catchall since this might fail for e.g. cross-device links
# (note that junction points on Windows will be copies as-is)
move <- catchall(file.rename(source, target))
if (renv_file_exists(target))
return(TRUE)
# expand tildes
source <- path.expand(source)
target <- path.expand(target)
# on unix, try using 'mv' command directly
# (can handle cross-device copies / moves a bit more efficiently)
if (renv_platform_unix()) {
args <- c(renv_shell_path(source), renv_shell_path(target))
status <- catchall(system2("mv", args, stdout = FALSE, stderr = FALSE))
if (renv_file_exists(target))
return(TRUE)
}
# on Windows, similarly try 'robocopy' command
# (should be faster than 'move' for large directories)
if (renv_platform_windows()) {
status <- catchall(renv_robocopy_move(source, target))
if (renv_file_exists(target))
return(TRUE)
}
# nocov start
# rename failed; fall back to copying
# (and be sure to remove the source file / directory on success)
copy <- catchall(renv_file_copy(source, target, overwrite = overwrite))
if (identical(copy, TRUE) && file.exists(target)) {
unlink(source, recursive = TRUE)
return(TRUE)
}
# rename and copy both failed: inform the user
fmt <- stack()
fmt$push("could not copy / move file '%s' to '%s'")
if (inherits(move, "condition"))
fmt$push(paste("move:", conditionMessage(move)))
if (inherits(copy, "condition"))
fmt$push(paste("copy:", conditionMessage(copy)))
text <- paste(fmt$data(), collapse = "\n")
stopf(text, source, target)
# nocov end
}
renv_file_link <- function(source, target, overwrite = FALSE) {
if (renv_file_same(source, target))
return(TRUE)
callback <- renv_file_preface(source, target, overwrite)
defer(callback())
if (renv_platform_windows()) {
# use junction points on Windows by default as symlinks
# are unreliable / un-deletable in some circumstances
status <- catchall(Sys.junction(source, target))
if (identical(status, TRUE))
return(TRUE)
# if Sys.junction() fails, it may leave behind an empty
# directory. this may occur if the source and target files
# reside on different volumes. either way, remove an empty
# left-behind directory on failure
unlink(target, recursive = TRUE, force = TRUE)
} else {
# on non-Windows, we can try to create a symlink
status <- catchall(file.symlink(source, target))
if (identical(status, TRUE))
return(TRUE)
}
# all else fails, just perform a copy
renv_file_copy(source, target, overwrite = overwrite)
}
renv_file_junction <- function(source, target) {
if (!renv_platform_windows())
stopf("'renv_file_junction()' is only available on Windows")
if (renv_file_exists(target))
stopf("file '%s' already exists")
status <- catchall(Sys.junction(source, target))
if (inherits(status, "condition")) {
unlink(target, recursive = TRUE, force = TRUE)
stop(status)
}
TRUE
}
renv_file_same <- function(source, target) {
# if the paths are the same, we can return early
if (identical(source, target))
return(TRUE)
# check to see if they're equal after normalization
# (e.g. for symlinks pointing to same file)
source <- renv_path_normalize(source)
target <- renv_path_normalize(target)
if (identical(source, target))
return(TRUE)
# for hard links + junction points, it's difficult to detect
# whether the two files point to the same object; use some
# heuristics to guess (note that these aren't perfect)
sinfo <- renv_file_info(source)
if (is.na(sinfo$isdir))
return(FALSE)
tinfo <- renv_file_info(target)
if (is.na(tinfo$isdir))
return(FALSE)
# NOTE: we intentionally exclude 'size' for directories, as
# on Windows the 'size' field might be reported as 0 for
# junction points?
if (renv_platform_windows()) {
if (sinfo$isdir || tinfo$isdir)
sinfo$size <- tinfo$size <- 0L
}
identical(c(sinfo), c(tinfo))
}
# NOTE: returns a callback which should be used in e.g. an defer handler
# to restore the file if the attempt to update the file failed
renv_file_backup <- function(path) {
# if no file exists then nothing to backup
if (!renv_file_exists(path))
return(function() {})
# normalize the path (since the working directory could change
# by the time the callback is invoked). note that the file may
# be a broken symlink so construct the path by normalizing the
# parent directory and building path relative to that
parent <- renv_path_normalize(dirname(path), mustWork = TRUE)
path <- file.path(parent, basename(path))
# attempt to rename the file
pattern <- sprintf(".renv-backup-%i-%s", Sys.getpid(), basename(path))
tempfile <- tempfile(pattern, tmpdir = dirname(path))
if (!renv_file_move(path, tempfile))
stopf("couldn't rename '%s' prior to transaction", renv_path_pretty(path))
# return callback that will restore if needed
function() {
if (!renv_file_exists(path))
renv_file_move(tempfile, path)
else
unlink(tempfile, recursive = TRUE)
}
}
renv_file_info <- function(paths, extra_cols = FALSE) {
suppressWarnings(file.info(paths, extra_cols = extra_cols))
}
renv_file_mode <- function(paths) {
suppressWarnings(file.mode(paths))
}
# NOTE: returns true for files that are broken symlinks
renv_file_exists <- function(path) {
if (renv_platform_windows())
renv_file_exists_win32(path)
else
renv_file_exists_unix(path)
}
renv_file_exists_win32 <- function(path) {
file.exists(path)
}
renv_file_exists_unix <- function(path) {
!is.na(Sys.readlink(path)) | file.exists(path)
}
renv_file_list <- function(path, full.names = TRUE) {
# list files
files <- renv_file_list_impl(path)
# NOTE: paths may be marked with UTF-8 encoding;
# if that's the case we need to use paste rather
# than file.path to preserve the encoding
if (full.names && length(files))
files <- paste(path, files, sep = "/")
files
}
renv_file_list_impl <- function(path) {
if (renv_platform_unix())
renv_file_list_impl_unix(path)
else
renv_file_list_impl_win32(path)
}
renv_file_list_impl_unix <- function(path) {
list.files(path, all.files = TRUE, no.. = TRUE)
}
# nocov start
renv_file_list_impl_win32 <- function(path) {
# first, try a plain list.files to see if we can get away with that
files <- list.files(path, all.files = TRUE, no.. = TRUE)
if (!any(grepl("?", files, fixed = TRUE)))
return(files)
# otherwise, try some madness ...
#
# change working directory (done just to avoid encoding issues
# when submitting path to cmd shell)
renv_scope_wd(path)
# NOTE: a sub-shell is required here in some contexts; e.g. when running
# tests non-interactively or building in the RStudio pane
command <- paste(comspec(), "/U /C dir /B")
conn <- pipe(command, open = "rb", encoding = "native.enc")
defer(close(conn))
# read binary output from connection
output <- stack()
while (TRUE) {
data <- readBin(conn, what = "raw", n = 1024L)
if (empty(data))
break
output$push(data)
}
# join into single raw vector
encoded <- unlist(output$data(), recursive = FALSE, use.names = FALSE)
# convert raw data (encoded as UTF-16LE) to UTF-8
converted <- iconv(list(encoded), from = "UTF-16LE", to = "UTF-8")
# split on (Windows) newlines
paths <- strsplit(converted, "\r\n", fixed = TRUE)[[1]]
# just in case?
paths[nzchar(paths)]
}
# nocov end
renv_file_type <- function(paths, symlinks = TRUE) {
info <- renv_file_info(paths)
types <- character(length(paths))
types[info$isdir %in% FALSE] <- "file"
types[info$isdir %in% TRUE ] <- "directory"
if (symlinks && !renv_platform_windows()) {
links <- Sys.readlink(paths)
types[!is.na(links) & nzchar(links)] <- "symlink"
}
types
}
# nocov start
renv_file_edit <- function(path) {
# https://github.com/rstudio/renv/issues/44
dlls <- getLoadedDLLs()
if (is.null(dlls[["(embedding)"]]))
return(utils::file.edit(path))
routines <- getDLLRegisteredRoutines("(embedding)")
routine <- routines[[".Call"]][["rs_editFile"]]
if (is.null(routine))
return(utils::file.edit(path))
do.call(.Call, list(routine, path, PACKAGE = "(embedding)"))
}
# nocov end
renv_file_find <- function(path, predicate) {
# canonicalize path
# (note: don't normalize as we don't want to follow symlinks)
path <- renv_path_canonicalize(path)
parent <- dirname(path)
# compute number of slashes
# (avoid searching beyond home directory, unless we're virtualized)
virtualized <- renv_virtualization_type() != "native"
slashes <- gregexpr("/", path, fixed = TRUE)[[1L]]
n <- length(slashes) - if (virtualized) 0L else 2L
for (i in 1:n) {
if (file.exists(path)) {
status <- predicate(path)
if (!is.null(status))
return(status)
}
path <- parent
parent <- dirname(path)
}
predicate(path)
}
renv_file_read <- function(path) {
renv_scope_options(warn = -1L)
contents <- readLines(path, warn = FALSE, encoding = "UTF-8")
paste(contents, collapse = "\n")
}
renv_file_shebang <- function(path) {
# NOTE: we use 'condition' as a cheap way to capture both errors and warnings
# since 'file()' may just report a warning rather than an error if it fails
# to open a file due to inadequate permissions
tryCatch(
renv_file_shebang_impl(path),
condition = function(e) ""
)
}
renv_file_shebang_impl <- function(path) {
renv_scope_options(warn = -1L)
# open connection to file
con <- file(path, open = "rb", encoding = "native.enc")
defer(close(con))
# validate file starts with '#!' -- read using 'raw' vector to avoid
# issues which files that might start with null bytes
bytes <- readBin(con, what = "raw", n = 2L)
expected <- as.raw(c(0x23L, 0x21L))
if (!identical(bytes, expected))
return("")
# read a single line from the connection
readLines(con, n = 1L, warn = FALSE)
}
# here, 'broken' implies a file which is a link pointing to a file that
# doesn't exist, so only returns true if the file is "link"-y and the
# file it points to doesn't exist
renv_file_broken <- function(paths) {
if (renv_platform_unix())
renv_file_broken_unix(paths)
else
renv_file_broken_win32(paths)
}
renv_file_broken_unix <- function(paths) {
# a symlink is broken if:
# - the file is a symlink (tested via Sys.readlink)
# - the file it points to does not exist (tested via file.exists)
!is.na(Sys.readlink(paths)) & !file.exists(paths)
}
renv_file_broken_win32 <- function(paths) {
# TODO: the behavior of file.exists() for a broken junction point
# appears to have changed in the development version of R;
# we have to be extra careful here...
if (getRversion() < "4.2.0") {
info <- renv_file_info(paths)
(info$isdir %in% TRUE) & is.na(info$mtime)
} else {
file.access(paths, mode = 0L) == 0L & !file.exists(paths)
}
}
renv_file_size <- function(path) {
file.info(path, extra_cols = FALSE)$size
}
renv_file_remove <- function(paths) {
if (renv_platform_windows())
renv_file_remove_win32(paths)
else
renv_file_remove_unix(paths)
}
renv_file_remove_win32 <- function(paths) {
for (path in paths) {
command <- paste("rmdir /S /Q", renv_shell_path(path))
shell(command)
}
}
renv_file_remove_unix <- function(paths) {
unlink(paths, recursive = TRUE, force = TRUE)
}
renv_file_writable <- function(path) {
# allow users to opt-out just in case
override <- getOption("renv.download.check_writable", default = TRUE)
if (!identical(override, TRUE))
return(TRUE)
# if we're given the path to a file, use the parent directory instead
info <- renv_file_info(path)
if (!identical(info$isdir, TRUE))
path <- dirname(path)
# if we still don't have a directory, bail
info <- renv_file_info(path)
if (!identical(info$isdir, TRUE))
return(FALSE)
# try creating and removing a temporary file in this directory
tempfile <- renv_scope_tempfile(".renv-write-test-", tmpdir = path)
ok <- dir.create(tempfile, showWarnings = FALSE)
# return ok if we succeeded
ok
}
renv/R/use-python.R 0000644 0001762 0000144 00000035074 14577403316 013706 0 ustar ligges users
#' Use python
#'
#' Associate a version of Python with your project.
#'
#' When Python integration is active, renv will:
#'
#' - Save metadata about the requested version of Python in `renv.lock` -- in
#' particular, the Python version, and the Python type ("virtualenv", "conda",
#' "system"),
#'
#' - Capture the set of installed Python packages during `renv::snapshot()`,
#'
#' - Re-install the set of recorded Python packages during `renv::restore()`.
#'
#' In addition, when the project is loaded, the following actions will be taken:
#'
#' - The `RENV_PYTHON` environment variable will be set, indicating the version
#' of Python currently active for this sessions,
#'
#' - The `RETICULATE_PYTHON` environment variable will be set, so that the
#' reticulate package can automatically use the requested copy of Python
#' as appropriate,
#'
#' - The requested version of Python will be placed on the `PATH`, so that
#' attempts to invoke Python will resolve to the expected version of Python.
#'
#' You can override the version of Python used in a particular project by
#' setting the `RENV_PYTHON` environment variable; e.g. as part of the
#' project's `.Renviron` file. This can be useful if you find that renv
#' is unable to automatically discover a compatible version of Python to
#' be used in the project.
#'
#' @inherit renv-params
#'
#' @param ... Optional arguments; currently unused.
#'
#' @param python
#' The path to the version of Python to be used with this project. See
#' **Finding Python** for more details.
#'
#' @param type
#' The type of Python environment to use. When `"auto"` (the default),
#' virtual environments will be used.
#'
#' @param name
#' The name or path that should be used for the associated Python environment.
#' If `NULL` and `python` points to a Python executable living within a
#' pre-existing virtual environment, that environment will be used. Otherwise,
#' a project-local environment will be created instead, using a name
#' generated from the associated version of Python.
#'
#' @details
#' # Finding Python
#'
#' In interactive sessions, when `python = NULL`, renv will prompt for an
#' appropriate version of Python. renv will search a pre-defined set of
#' locations when attempting to find Python installations on the system:
#'
#' - `getOption("renv.python.root")`,
#' - `/opt/python`,
#' - `/opt/local/python`,
#' - `~/opt/python`,
#' - `/usr/local/opt` (for macOS Homebrew-installed copies of Python),
#' - `/opt/homebrew/opt` (for M1 macOS Homebrew-installed copies of Python),
#' - `~/.pyenv/versions`,
#' - Python instances available on the `PATH`.
#'
#' In non-interactive sessions, renv will first check the `RETICULATE_PYTHON`
#' environment variable; if that is unset, renv will look for Python on the
#' `PATH`. It is recommended that the version of Python to be used is explicitly
#' supplied for non-interactive usages of `use_python()`.
#'
#'
#' # Warning
#'
#' We strongly recommend using Python virtual environments, for a few reasons:
#'
#' 1. If something goes wrong with a local virtual environment, you can safely
#' delete that virtual environment, and then re-initialize it later, without
#' worry that doing so might impact other software on your system.
#'
#' 2. If you choose to use a "system" installation of Python, then any packages
#' you install or upgrade will be visible to any other application that
#' wants to use that same Python installation. Using a virtual environment
#' ensures that any changes made are isolated to that environment only.
#'
#' 3. Choosing to use Anaconda will likely invite extra frustration in the
#' future, as you may be required to upgrade and manage your Anaconda
#' installation as new versions of Anaconda are released. In addition,
#' Anaconda installations tend to work poorly with software not specifically
#' installed as part of that same Anaconda installation.
#'
#' In other words, we recommend selecting "system" or "conda" only if you are an
#' expert Python user who is already accustomed to managing Python / Anaconda
#' installations on your own.
#'
#'
#' @return
#' `TRUE`, indicating that the requested version of Python has been
#' successfully activated. Note that this function is normally called for its
#' side effects.
#'
#'
#' @export
#'
#' @examples
#' \dontrun{
#'
#' # use python with a project
#' renv::use_python()
#'
#' # use python with a project; create the environment
#' # within the project directory in the '.venv' folder
#' renv::use_python(name = ".venv")
#'
#' # use python with a pre-existing virtual environment located elsewhere
#' renv::use_python(name = "~/.virtualenvs/env")
#'
#' # use virtualenv python with a project
#' renv::use_python(type = "virtualenv")
#'
#' # use conda python with a project
#' renv::use_python(type = "conda")
#'
#' }
use_python <- function(python = NULL,
...,
type = c("auto", "virtualenv", "conda", "system"),
name = NULL,
project = NULL)
{
renv_scope_error_handler()
renv_dots_check(...)
project <- renv_project_resolve(project)
# deactivate python integration when FALSE
if (identical(python, FALSE))
return(renv_python_deactivate(project))
# handle 'auto' type
type <- match.arg(type)
if (identical(type, "auto"))
type <- "virtualenv"
case(
type == "system" ~ renv_use_python_system(python, name, project),
type == "virtualenv" ~ renv_use_python_virtualenv(python, name, project),
type == "conda" ~ renv_use_python_condaenv(python, name, project)
)
}
renv_use_python_system <- function(python,
name,
project)
{
# retrieve python information
python <- renv_python_resolve(python)
version <- renv_python_version(python)
info <- renv_python_info(python)
# if the user ended up selecting a virtualenv or conda python, then
# just activate those and ignore the 'system' request
if (identical(info$type, "virtualenv"))
return(renv_use_python_virtualenv(info$python, name, project))
if (identical(info$type, "conda"))
return(renv_use_python_condaenv(info$python, name, project))
# for 'system' python usages, we just use the path to python
# (note that this may not be portable or useful for other machines)
renv_use_python_fini(info, python, version, project)
}
renv_use_python_virtualenv <- function(python,
name,
project)
{
# if name has been set, check and see if it refers to an already-existing
# virtual environment; if that exists, use it
if (is.null(python) && !is.null(name)) {
path <- renv_python_virtualenv_path(name)
if (file.exists(path))
python <- renv_python_exe(name)
}
python <- renv_python_resolve(python)
version <- renv_python_version(python)
info <- renv_python_info(python)
# if name is unset, and 'python' doesn't already refer to an existing
# virtual environment, then we'll use a local virtual environment
local <- is.null(name) && identical(info$type, "virtualenv")
if (local) {
name <- renv_path_aliased(info$root)
if (renv_path_same(dirname(name), renv_python_virtualenv_home()))
name <- basename(name)
} else {
name <- name %||% renv_python_envpath(project, "virtualenv", version)
if (grepl("/", name, fixed = TRUE))
name <- renv_path_canonicalize(name)
}
# now, check to see if the python environment exists;
# if it does not exist, we'll create it now
vpython <- renv_use_python_virtualenv_impl(project, name, version, python)
vinfo <- renv_python_info(vpython)
# finish up now
renv_use_python_fini(vinfo, name, version, project)
}
renv_use_python_condaenv <- function(python,
name,
project)
{
# if python is set, see if it's already the path to a python interpreter
# living within a conda environment
while (!is.null(python)) {
if (!is.null(name)) {
fmt <- "ignoring value of name %s as python was already set"
warningf(fmt, renv_path_pretty(name))
}
# validate that this is a conda python
info <- renv_python_info(python)
if (!identical(info$type, "conda")) {
fmt <- "%s does not appear to refer to a Conda instance of Python; ignoring"
warningf(fmt, renv_path_pretty(python))
break
}
# use this edition of python without further adieu
version <- renv_python_version(python)
return(renv_use_python_fini(info, name, version, project))
}
# TODO: how do we select which version of python we want to use?
name <- name %||% renv_python_envpath(project, "conda")
python <- renv_use_python_condaenv_impl(project, name)
info <- renv_python_info(python)
version <- renv_python_version(python)
renv_use_python_fini(info, name, version, project)
}
renv_use_python_fini <- function(info, name, version, project) {
# normalize project path for later comparison
project <- renv_path_normalize(project)
# handle 'name' -- treat values containing slashes specially, and
# check if those paths are project-relative environments
if (!is.null(name) && grepl("/", name, fixed = TRUE)) {
name <- renv_path_normalize(name)
if (startswith(name, project)) {
base <- substring(name, nchar(project) + 2L)
name <- if (grepl("^[.][^/]+$", base)) base else file.path(".", base)
}
}
# form the lockfile fields we'll want to write
fields <- as.list(c(Version = version, Type = info$type, Name = name))
# update the lockfile
lockfile <- renv_lockfile_load(project)
if (!identical(fields, lockfile$Python)) {
lockfile$Python <- fields
renv_lockfile_save(lockfile, project)
}
# re-initialize with these settings
renv_load_python(project, fields)
# notify user
if (!renv_tests_running()) {
if (is.null(info$type)) {
fmt <- "- Activated Python %s (%s)."
writef(fmt, version, renv_path_aliased(info$python))
} else {
fmt <- "- Activated Python %s [%s; %s]"
writef(fmt, version, info$type, renv_path_aliased(name))
}
}
# report to user
setwd(project)
activate(project = project)
invisible(info$python)
}
# return the path to an existing python binary associated with the virtual
# environment having name 'name' and version 'version', or "" if no such
# python instance exists
renv_use_python_virtualenv_impl_existing <- function(project,
name = NULL,
version = NULL)
{
# resolve environment path from name
name <- name %||% renv_python_envpath(project, "virtualenv", version)
path <- renv_python_virtualenv_path(name)
if (!file.exists(path))
return("")
# check that this appears to have a valid python executable
info <- catch(renv_python_info(path))
if (inherits(info, "error")) {
warning(info)
return("")
}
# validate version and return
renv_python_virtualenv_validate(path, version)
}
# Internal helper for activating a Python virtual environment
#
# @param project
# The project directory.
#
# @param name
# The environment name, if any. If unset, it should be constructed
# based on the Python executable used (note: _not_ the version parameter)
#
# @param version
# The _requested_ version of Python (which may not be the actual version!)
# This version should be used as a hint for finding an appropriate version
# of Python, if the environment needs to be re-created.
#
# @param python
# The copy of Python to be used. When unset, an appropriate version of Python
# should be discovered based on the `version` parameter.
#
# @return
# The path to the Python binary in the associated virtual environment.
#
renv_use_python_virtualenv_impl <- function(project,
name = NULL,
version = NULL,
python = NULL)
{
# first, look for an already-existing python installation
# associated with the requested version of python
exe <- renv_use_python_virtualenv_impl_existing(project, name, version)
if (file.exists(exe))
return(exe)
# couldn't resolve environment from requested version; try to find
# a compatible version of python and re-create that environment
python <- python %||% renv_python_find(version)
pyversion <- renv_python_version(python)
name <- name %||% renv_python_envpath(project, "virtualenv", pyversion)
path <- renv_python_virtualenv_path(name)
# if the environment already exists, but is associated with a different
# version of Python, prompt the user to re-create that environment
if (file.exists(path)) {
exe <- renv_python_virtualenv_validate(path, version)
if (file.exists(exe))
return(exe)
}
printf("- Creating virtual environment '%s' ... ", basename(name))
vpython <- renv_python_virtualenv_create(python, path)
writef("Done!")
printf("- Updating Python packages ... ")
renv_python_virtualenv_update(vpython)
writef("Done!")
renv_python_virtualenv_validate(path, version)
}
renv_use_python_condaenv_impl <- function(project,
name = NULL,
version = NULL,
python = NULL)
{
# if we can't load reticulate, try installing if there is a version
# recorded in the lockfile
if (!requireNamespace("reticulate", quietly = TRUE)) {
# retrieve reticulate record
lockfile <- renv_lockfile_load(project = project)
records <- renv_lockfile_records(lockfile)
reticulate <- records[["reticulate"]]
# if we have a reticulate record, then attempt to restore
if (!is.null(reticulate)) {
restore(packages = "reticulate",
prompt = FALSE,
project = project)
} else {
install(packages = "reticulate",
prompt = FALSE,
project = project)
}
}
# try once more to load reticulate
if (!requireNamespace("reticulate", quietly = TRUE))
stopf("use of conda environments requires the 'reticulate' package")
# TODO: how to handle things like a requested Python version here?
name <- name %||% renv_python_envpath(project, "conda", version)
renv_python_conda_select(name, version)
}
renv_python_deactivate <- function(project) {
file <- renv_lockfile_path(project)
if (!file.exists(file))
return(TRUE)
lockfile <- renv_lockfile_read(file)
if (is.null(lockfile$Python))
return(TRUE)
lockfile$Python <- NULL
renv_lockfile_write(lockfile, file = file)
writef("- Deactived Python -- the lockfile has been updated.")
TRUE
}
renv/R/dynamic.R 0000644 0001762 0000144 00000005071 14547051446 013211 0 ustar ligges users
#
# Tools for so-called 'dynamic' values. These are values which are computed
# once, and then memoized for the rest of the currently-executing call.
#
# An exit handler placed in the top-most (renv) environment is then responsible
# for cleaning up any objects cached for the duration of that frame.
#
# This is a useful way to cache results for repeatedly-computed values
# that one can reasonably expect not to change in the duration of a
# particular call.
#
the$dynamic_envir <- NULL
the$dynamic_objects <- new.env(parent = emptyenv())
dynamic <- function(key, value, envir = NULL, force = FALSE) {
# allow opt-out just in case
enabled <- getOption("renv.dynamic.enabled", default = TRUE)
if (!enabled)
return(value)
# get a unique id for the scope where this function was invoked
caller <- sys.call(sys.parent())[[1L]]
if (renv_call_matches(caller, name = ":::"))
caller <- caller[[3L]]
# handle cases like FUN
if (is.null(the$envir_self[[as.character(caller)]])) {
if (!renv_tests_running()) {
fmt <- "internal error: dynamic() received unexpected call '%s'"
stopf(fmt, stringify(sys.call(sys.parent())))
}
}
# just return value if this isn't a valid dynamic scope
if (!is.symbol(caller)) {
dlog("dynamic", "invalid dynamic scope '%s'", stringify(sys.call(sys.parent())))
return(value)
}
# make sure we have a dynamic scope active
the$dynamic_envir <- the$dynamic_envir %||% renv_dynamic_envir(envir)
# resolve key from variables in the parent frame
key <- paste(names(key), map_chr(key, stringify), sep = " = ", collapse = ", ")
# put it together
id <- sprintf("%s(%s)", as.character(caller), key)
# if we're forcing, clear the memoized value
if (force)
the$dynamic_objects[[id]] <- NULL
# memoize the result of the expression
the$dynamic_objects[[id]] <- the$dynamic_objects[[id]] %||% {
dlog("dynamic", "memoizing dynamic value for '%s'", id)
value
}
}
renv_dynamic_envir <- function(envir = NULL) {
envir <- envir %||% renv_dynamic_envir_impl()
defer(renv_dynamic_reset(), scope = envir)
dlog("dynamic", "using dynamic environment '%s'", format(envir))
envir
}
renv_dynamic_envir_impl <- function() {
frames <- sys.frames()
for (i in seq_along(frames)) {
envir <- frames[[i]]
if (identical(parent.env(envir), the$envir_self))
return(envir)
}
stop("internal error: no renv frame available for dynamic call")
}
renv_dynamic_reset <- function() {
dlog("dynamic", "resetting dynamic objects")
the$dynamic_envir <- NULL
renv_envir_clear(the$dynamic_objects)
}
renv/R/diagnostics.R 0000644 0001762 0000144 00000015616 14571655673 014113 0 ustar ligges users
#' Print a diagnostics report
#'
#' Print a diagnostics report, summarizing the state of a project using renv.
#' This report can occasionally be useful when diagnosing issues with renv.
#'
#' @inheritParams renv-params
#'
#' @return This function is normally called for its side effects.
#'
#' @export
diagnostics <- function(project = NULL) {
renv_scope_error_handler()
project <- renv_project_resolve(project)
renv_project_lock(project = project)
if (renv_file_type(project, symlinks = FALSE) != "directory") {
fmt <- "project %s is not a directory"
stopf(fmt, renv_path_pretty(project))
}
renv_scope_options(renv.verbose = TRUE)
reporters <- list(
renv_diagnostics_session,
renv_diagnostics_project,
renv_diagnostics_status,
renv_diagnostics_packages,
renv_diagnostics_abi,
renv_diagnostics_profile,
renv_diagnostics_settings,
renv_diagnostics_options,
renv_diagnostics_envvars,
renv_diagnostics_path,
renv_diagnostics_cache
)
fmt <- "Diagnostics Report [renv %s]"
title <- sprintf(fmt, renv_metadata_version_friendly())
lines <- paste(rep.int("=", nchar(title)), collapse = "")
writef(c(title, lines, ""))
for (reporter in reporters) {
tryCatch(reporter(project), error = renv_error_handler)
writef()
}
}
renv_diagnostics_session <- function(project) {
writef(header("Session Info"))
renv_scope_options(width = 80)
print(sessionInfo())
}
renv_diagnostics_project <- function(project) {
writef(header("Project"))
writef("Project path: %s", renv_path_pretty(project))
}
renv_diagnostics_status <- function(project) {
writef(header("Status"))
status(project = project)
}
renv_diagnostics_packages <- function(project) {
writef(header("Packages"))
# collect state of lockfile, library, dependencies
lockfile <- renv_diagnostics_packages_lockfile(project)
libstate <- renv_diagnostics_packages_library(project)
used <- unique(renv_diagnostics_packages_dependencies(project)$Package)
# collect recursive package dependencies
recdeps <- renv_package_dependencies(
packages = used,
project = project
)
# bundle together
all <- c(
names(lockfile$Packages),
names(libstate$Packages),
names(recdeps),
used
)
# sort
all <- csort(unique(all))
# check which packages are direct, indirect requirements
deps <- rep.int(NA_character_, length(all))
names(deps) <- all
deps[names(recdeps)] <- "indirect"
deps[used] <- "direct"
# build libpaths for installed packages
libpaths <- dirname(map_chr(all, renv_package_find))
# use short form
flibpaths <- factor(libpaths, levels = .libPaths())
# construct integer codes (to be reported in data output)
libcodes <- as.integer(flibpaths)
libcodes[!is.na(libcodes)] <- sprintf("[%i]", libcodes[!is.na(libcodes)])
# add in packages in library
data <- data_frame(
Library = renv_diagnostics_packages_version(libstate, all),
Source = renv_diagnostics_packages_sources(libstate, all),
Lockfile = renv_diagnostics_packages_version(lockfile, all),
Source = renv_diagnostics_packages_sources(lockfile, all),
Path = libcodes,
Dependency = deps
)
# we explicitly want to use rownames here
row.names(data) <- names(deps)
# print it out
renv_scope_options(width = 9000)
print(data, max = 10000)
# print library codes
fmt <- "[%s]: %s"
writef()
writef(fmt, format(seq_along(levels(flibpaths))), format(levels(flibpaths)))
}
renv_diagnostics_packages_version <- function(lockfile, all) {
data <- rep.int(NA_character_, length(all))
names(data) <- all
formatted <- map_chr(lockfile$Packages, `[[`, "Version")
data[names(formatted)] <- formatted
data
}
renv_diagnostics_packages_sources <- function(lockfile, all) {
data <- rep.int(NA_character_, length(all))
names(data) <- all
sources <- map_chr(lockfile$Packages, function(record) {
record$Repository %||% record$Source %||% ""
})
data[names(sources)] <- sources
data
}
renv_diagnostics_packages_lockfile <- function(project) {
lockpath <- renv_lockfile_path(project = project)
if (!file.exists(lockpath)) {
writef("This project has not yet been snapshotted: 'renv.lock' does not exist.")
return(list())
}
renv_lockfile_read(lockpath)
}
renv_diagnostics_packages_library <- function(project) {
library <- renv_paths_library(project = project)
if (!file.exists(library)) {
fmt <- "The project library %s does not exist."
writef(fmt, renv_path_pretty(library))
}
snapshot(project = project, lockfile = NULL, type = "all")
}
renv_diagnostics_packages_dependencies <- function(project) {
renv_dependencies_impl(
project,
errors = "reported",
dev = TRUE
)
}
renv_diagnostics_abi <- function(project) {
writef(header("ABI"))
tryCatch(
renv_abi_check(),
error = function(e) {
writef(conditionMessage(e))
}
)
}
renv_diagnostics_profile <- function(project) {
writef(header("User Profile"))
userprofile <- "~/.Rprofile"
if (!file.exists(userprofile))
return(writef("[no user profile detected]"))
deps <- renv_dependencies_impl(
userprofile,
errors = "reported",
dev = TRUE
)
if (empty(deps))
return(writef("[no R packages referenced in user profile"))
renv_scope_options(width = 200)
print(deps)
}
renv_diagnostics_settings <- function(project) {
writef(header("Settings"))
str(renv_settings_get(project))
}
renv_diagnostics_options <- function(project) {
writef(header("Options"))
keys <- c(
"defaultPackages",
"download.file.method",
"download.file.extra",
"install.packages.compile.from.source",
"pkgType",
"repos",
grep("^renv[.]", names(.Options), value = TRUE)
)
vals <- .Options[keys]
names(vals) <- keys
str(vals)
}
renv_diagnostics_envvars <- function(project) {
writef(header("Environment Variables"))
envvars <- convert(as.list(Sys.getenv()), "character")
useful <- c(
"R_LIBS_USER", "R_LIBS_SITE", "R_LIBS",
"HOME", "LANG", "MAKE",
grep("_proxy", names(envvars), ignore.case = TRUE, value = TRUE),
grep("^RENV_", names(envvars), value = TRUE)
)
matches <- envvars[useful]
if (empty(matches))
return(writef("[no renv environment variables available]"))
names(matches) <- useful
matches[is.na(matches)] <- ""
matches <- matches[order(names(matches))]
keys <- names(matches)
vals <- matches
formatted <- paste(format(keys), vals, sep = " = ")
writef(formatted)
}
renv_diagnostics_path <- function(project) {
writef(header("PATH"))
path <- strsplit(Sys.getenv("PATH"), .Platform$path.sep, fixed = TRUE)[[1]]
writef(paste("-", path))
}
renv_diagnostics_cache <- function(project) {
writef(header("Cache"))
fmt <- "There are a total of %s installed in the renv cache."
cachelist <- renv_cache_list()
writef(fmt, nplural("package", length(cachelist)))
writef("Cache path: %s", renv_path_pretty(renv_paths_cache()))
}
renv/R/preflight.R 0000644 0001762 0000144 00000004575 14464550375 013564 0 ustar ligges users
# returns TRUE if problems detected
renv_preflight <- function(lockfile) {
problems <- stack()
# check that we can compile C programs
renv_preflight_compiler(problems)
# if rJava is being used, ensure that Java is properly configured
renv_preflight_java(lockfile, problems)
data <- problems$data()
if (length(data)) {
feedback <- lines(
"The following problems were detected in your environment:",
"",
paste(data, collapse = "\n\n"),
"",
"The environment may not be restored correctly."
)
caution(feedback)
}
length(data) == 0
}
renv_preflight_compiler <- function(problems) {
# try to compile a simple program
program <- "void test() {}"
file <- renv_scope_tempfile("renv-test-compile-", fileext = ".c")
writeLines(program, con = file)
args <- c("CMD", "SHLIB", renv_shell_path(file))
status <- system2(R(), args, stdout = FALSE, stderr = FALSE)
if (!identical(status, 0L)) {
feedback <- lines(
"- Cannot compile C / C++ files from source.",
" Please ensure you have a compiler toolchain installed."
)
problems$push(feedback)
}
}
renv_preflight_java <- function(lockfile, problems) {
# no need to check if we're not using rJava
records <- renv_lockfile_records(lockfile)
if (is.null(records[["rJava"]]))
return(TRUE)
# TODO: no need to do anything if we're only installing binaries?
switch(
Sys.info()[["sysname"]],
Windows = renv_preflight_java_windows(problems),
renv_preflight_java_unix(problems)
)
}
renv_preflight_java_windows <- function(problems) {
home <- Sys.getenv("JAVA_HOME", unset = NA)
feedback <- case(
is.na(home) ~ lines(
"- JAVA_HOME is not set.",
" Please ensure you have a Java Development Kit (JDK) installed."
),
!file.exists(home) ~ lines(
"- JAVA_HOME is set to a non-existent directory.",
" Please ensure you have a Java Development Kit (JDK) installed."
)
)
if (!is.null(feedback))
problems$push(feedback)
}
renv_preflight_java_unix <- function(problems) {
args <- c("CMD", "javareconf", "--dry-run")
status <- system2(R(), args, stdout = FALSE, stderr = FALSE)
if (!identical(status, 0L)) {
feedback <- lines(
"- Cannot compile Java files from source.",
" Please ensure you have a Java Development Kit (JDK) installed."
)
problems$push(feedback)
}
}
renv/R/tar.R 0000644 0001762 0000144 00000002021 14547051446 012343 0 ustar ligges users
renv_tar_exe <- function(default = "") {
# allow override
tar <- getOption("renv.tar.exe")
if (!is.null(tar))
return(tar)
# on unix, just use default
if (renv_platform_unix()) {
tar <- Sys.which("tar")
if (nzchar(tar))
return(tar)
}
# on Windows, use system tar.exe if available
root <- Sys.getenv("SystemRoot", unset = NA)
if (is.na(root))
root <- "C:/Windows"
# use tar if it exists
tarpath <- file.path(root, "System32/tar.exe")
if (file.exists(tarpath))
return(tarpath)
# otherwise, give up (don't trust the arbitrary tar on PATH)
default
}
renv_tar_decompress <- function(tar, archive, files = NULL, exdir = ".", ...) {
# build argument list
args <- c(
"xf", renv_shell_path(archive),
if (!identical(exdir, "."))
c("-C", renv_shell_path(exdir)),
if (length(files))
renv_shell_path(files)
)
# make sure exdir exists
ensure_directory(exdir)
# perform decompress
return(renv_system_exec(tar, args, action = "decompressing archive"))
}
renv/R/pak.R 0000644 0001762 0000144 00000007650 14556504232 012341 0 ustar ligges users
# the minimum-required version of 'pak' for renv integration
the$pak_minver <- numeric_version("0.7.0")
renv_pak_init <- function(stream = NULL, force = FALSE) {
stream <- stream %||% renv_pak_stream()
if (force || !renv_pak_available())
renv_pak_init_impl(stream)
renv_namespace_load("pak")
}
renv_pak_stream <- function() {
# check if stable is new enough
streams <- c("stable", "rc", "devel")
for (stream in streams) {
repos <- renv_pak_repos(stream)
latest <- renv_available_packages_latest("pak", repos = repos)
version <- numeric_version(latest$Version)
if (version >= the$pak_minver)
return(stream)
}
fmt <- "internal error: pak (>= %s) is not available"
stopf(fmt, format(the$pak_minver))
}
renv_pak_available <- function() {
tryCatch(
packageVersion("pak") >= the$pak_minver,
error = function(e) FALSE
)
}
renv_pak_repos <- function(stream) {
# on macOS, we can only use pak binaries with CRAN R
if (renv_platform_macos() && .Platform$pkgType == "source")
return(getOption("repos"))
# otherwise, use pre-built pak binaries
fmt <- "https://r-lib.github.io/p/pak/%s/%s/%s/%s"
sprintf(fmt, stream, .Platform$pkgType, version$os, version$arch)
}
renv_pak_init_impl <- function(stream) {
repos <- c("r-lib" = renv_pak_repos(stream))
renv_scope_options(renv.config.pak.enabled = FALSE, repos = repos)
library <- renv_libpaths_active()
install("pak", library = library)
loadNamespace("pak", lib.loc = library)
}
renv_pak_install <- function(packages, library, project) {
pak <- renv_namespace_load("pak")
lib <- library[[1L]]
# transform repositories
if (renv_ppm_enabled()) {
repos <- getOption("repos")
renv_scope_options(repos = renv_ppm_transform(repos))
}
# make sure pak::pkg_install() still works even if we're
# running in renv with devtools::load_all()
name <- Sys.getenv("_R_CHECK_PACKAGE_NAME_", unset = NA)
if (identical(name, "renv"))
renv_scope_envvars("_R_CHECK_PACKAGE_NAME_" = NULL)
# if we received a named list of remotes, use the names
packages <- if (any(nzchar(names(packages))))
names(packages)
else
as.character(packages)
if (length(packages) == 0L)
return(pak$local_install_dev_deps(root = project, lib = lib))
pak$pkg_install(
pkg = packages,
lib = lib,
upgrade = TRUE
)
}
renv_pak_restore <- function(lockfile,
packages = NULL,
exclude = NULL,
project = NULL)
{
pak <- renv_namespace_load("pak")
# transform repositories
if (renv_ppm_enabled()) {
repos <- getOption("repos")
renv_scope_options(repos = renv_ppm_transform(repos))
}
# make sure pak::pkg_install() still works even if we're
# running in renv with devtools::load_all()
name <- Sys.getenv("_R_CHECK_PACKAGE_NAME_", unset = NA)
if (identical(name, "renv"))
renv_scope_envvars("_R_CHECK_PACKAGE_NAME_" = NULL)
# get records to install
records <- renv_lockfile_records(lockfile)
packages <- setdiff(packages %||% names(records), c(exclude, "pak", "renv"))
records <- records[packages]
# attempt to link packages that have cache entries
if (renv_cache_config_enabled(project = project)) {
linked <- map_lgl(records, renv_cache_synchronize)
records <- records[!linked]
}
# convert into specs compatible with pak, and install
remotes <- map_chr(records, renv_record_format_remote)
# TODO: We previously tried converting version-ed remotes into "plain" remotes
# if the package version happened to be current, but then 'pak' would choose
# not to install the package if a newer version was available. Hence, we need
# to preserve the exact remote we wish to install here.
# return early if there are zero remotes to restore
if (length(remotes) == 0L) {
return(invisible(TRUE))
}
# perform installation
pak$pkg_install(remotes)
# return installed records
records
}
renv/R/aaa.R 0000644 0001762 0000144 00000001451 14500443513 012272 0 ustar ligges users
# global variables
the <- new.env(parent = emptyenv())
# detect if we're running on CI
ci <- function() {
!is.na(Sys.getenv("CI", unset = NA))
}
# detect if we're running within R CMD build
building <- function() {
nzchar(Sys.getenv("R_CMD")) &&
grepl("Rbuild", basename(dirname(getwd())), fixed = TRUE)
}
# are we running code within R CMD check?
checking <- function() {
"CheckExEnv" %in% search() ||
renv_envvar_exists("_R_CHECK_PACKAGE_NAME_") ||
renv_envvar_exists("_R_CHECK_SIZE_OF_TARBALL_")
}
# NOTE: Prefer using 'testing()' to 'renv_tests_running()' for behavior
# that should apply regardless of the package currently being tested.
#
# 'renv_tests_running()' is appropriate when running renv's own tests.
testing <- function() {
identical(Sys.getenv("TESTTHAT"), "true")
}
renv/R/task.R 0000644 0001762 0000144 00000001734 14464550375 012534 0 ustar ligges users
renv_task_create <- function(callback, name = NULL) {
# create name for task callback
name <- name %||% as.character(substitute(callback))
name <- paste("renv", name, sep = ":::")
# remove an already-existing task of the same name
removeTaskCallback(name)
# otherwise, add our new task
addTaskCallback(
renv_task_callback(callback, name),
name = name
)
}
renv_task_callback <- function(callback, name) {
force(callback)
force(name)
function(...) {
status <- tryCatch(callback(), error = identity)
if (inherits(status, "error")) {
caution("Error in background task '%s': %s", name, conditionMessage(status))
caution("Background task '%s' will be stopped.", name)
return(FALSE)
}
TRUE
}
}
renv_task_unload <- function() {
callbacks <- getTaskCallbackNames()
for (callback in callbacks)
for (prefix in c("renv_", "renv:::"))
if (startswith(callback, prefix))
removeTaskCallback(callback)
}
renv/R/purge.R 0000644 0001762 0000144 00000006464 14464550375 012721 0 ustar ligges users
#' Purge packages from the cache
#'
#' Purge packages from the cache. This can be useful if a package which had
#' previously been installed in the cache has become corrupted or unusable,
#' and needs to be reinstalled.
#'
#' `purge()` is an inherently destructive option. It removes packages from the
#' cache, and so any project which had symlinked that package into its own
#' project library would find that package now unavailable. These projects would
#' hence need to reinstall any purged packages. Take heed of this in case you're
#' looking to purge the cache of a package which is difficult to install, or
#' if the original sources for that package are no longer available!
#'
#' @inherit renv-params
#'
#' @param package A single package to be removed from the cache.
#' @param version The package version to be removed. When `NULL`, all versions
#' of the requested package will be removed.
#' @param hash The specific hashes to be removed. When `NULL`, all hashes
#' associated with a particular package's version will be removed.
#'
#' @return The set of packages removed from the renv global cache,
#' as a character vector of file paths.
#'
#' @export
#'
#' @examples
#' \dontrun{
#'
#' # remove all versions of 'digest' from the cache
#' renv::purge("digest")
#'
#' # remove only a particular version of 'digest' from the cache
#' renv::purge("digest", version = "0.6.19")
#'
#' }
purge <- function(package,
...,
version = NULL,
hash = NULL,
prompt = interactive())
{
renv_scope_error_handler()
renv_dots_check(...)
renv_scope_verbose_if(prompt)
invisible(renv_purge_impl(package, version, hash, prompt))
}
renv_purge_impl <- function(package,
version = NULL,
hash = NULL,
prompt = interactive())
{
if (length(package) != 1)
stop("argument 'package' is not of length one", call. = FALSE)
bail <- function() {
writef("- The requested package is not installed in the cache -- nothing to do.")
character()
}
# get root cache path entry for package
paths <- renv_paths_cache(package)
if (!any(file.exists(paths)))
return(bail())
# construct versioned path
paths <- if (is.null(version))
list.files(paths, full.names = TRUE)
else
file.path(paths, version)
if (!any(file.exists(paths)))
return(bail())
# construct hashed path
paths <- if (is.null(hash))
list.files(paths, full.names = TRUE)
else
file.path(paths, hash)
if (all(!file.exists(paths)))
return(bail())
# now add package name
paths <- file.path(paths, renv_path_component(paths, 3))
# check that these entries exist
missing <- !file.exists(paths)
if (any(missing)) {
caution_bullets(
"The following entries were not found in the cache:",
paths[missing],
"They will be ignored."
)
paths <- paths[!missing]
}
# nocov start
if (prompt || renv_verbose()) {
caution_bullets(
"The following packages will be purged from the cache:",
renv_cache_format_path(paths)
)
cancel_if(prompt && !proceed())
}
# nocov end
unlink(paths, recursive = TRUE)
renv_cache_clean_empty()
n <- length(paths)
writef("- Removed %s from the cache.", nplural("package", n))
invisible(paths)
}
renv/R/defer.R 0000644 0001762 0000144 00000003676 14547051446 012663 0 ustar ligges users
# environment hosting exit callbacks
the$defer_callbacks <- new.env(parent = emptyenv())
renv_defer_init <- function() {
# make sure we run callbacks set on the global environment on exit
# but only in non-interactive sessions, just to be safe
if (interactive())
return()
reg.finalizer(.GlobalEnv, renv_defer_execute, onexit = TRUE)
}
defer <- function(expr, scope = parent.frame()) {
handler <- renv_defer_add(
list(expr = substitute(expr), envir = parent.frame()),
envir = scope
)
invisible(handler)
}
renv_defer_id <- function(envir) {
format.default(envir)
}
renv_defer_get <- function(envir) {
id <- renv_defer_id(envir)
the$defer_callbacks[[id]]
}
renv_defer_set <- function(envir, handlers) {
# get any previously-set handlers. if we don't see any handlers registered,
# this must be our first time registering exit handlers on the environment,
# and so we'll want to register an on.exit handler to call our handlers
oldhandlers <- renv_defer_get(envir)
if (is.null(oldhandlers)) {
call <- as.call(list(renv_defer_execute, envir))
do.call(base::on.exit, list(substitute(call), TRUE), envir = envir)
}
# register the newly-set handlers
id <- renv_defer_id(envir)
the$defer_callbacks[[id]] <- handlers
}
renv_defer_remove <- function(envir) {
id <- renv_defer_id(envir)
rm(list = id, envir = the$defer_callbacks)
}
renv_defer_execute <- function(envir = parent.frame()) {
# check for handlers -- may be NULL if they were intentionally executed
# early via a call to `renv_defer_execute()`
handlers <- renv_defer_get(envir)
if (is.null(handlers))
return()
# execute the existing handlers
for (handler in handlers)
tryCatch(eval(handler$expr, handler$envir), error = identity)
# remove the handlers
renv_defer_remove(envir)
}
renv_defer_add <- function(envir, handler) {
handlers <- c(list(handler), renv_defer_get(envir))
renv_defer_set(envir, handlers)
handler
}
renv/R/paths.R 0000644 0001762 0000144 00000031126 14570426544 012705 0 ustar ligges users
the$root <- NULL
renv_paths_override <- function(name) {
# # check for value from option
# optname <- paste("renv.paths", name, sep = ".")
# optval <- getOption(optname)
# if (!is.null(optval))
# return(optval)
# check for value from envvar
envname <- paste("RENV_PATHS", toupper(name), sep = "_")
envval <- Sys.getenv(envname, unset = NA)
if (!is.na(envval))
return(envval)
}
renv_paths_common <- function(name, prefixes = NULL, ...) {
# check for single absolute path supplied by user
# TODO: handle multiple?
end <- file.path(...)
if (length(end) == 1 && renv_path_absolute(end))
return(end)
# check for path provided via option
root <- renv_paths_override(name) %||% renv_paths_root(name)
# split path entries containing a separator
if (name %in% c("cache", "local", "cellar")) {
pattern <- if (renv_platform_windows()) "[;]" else "[;:]"
root <- strsplit(root, pattern)[[1L]]
}
# form rest of path
prefixed <- if (length(prefixes))
file.path(root, paste(prefixes, collapse = "/"))
else
root
path <- file.path(prefixed, ...)
if (length(path)) path else ""
}
renv_paths_library_root <- function(project) {
renv_bootstrap_library_root(project)
}
renv_paths_library <- function(..., project = NULL) {
project <- renv_project_resolve(project)
root <- renv_paths_library_root(project)
file.path(root, renv_platform_prefix(), ...) %||% ""
}
renv_paths_lockfile <- function(project = NULL) {
# allow override
# TODO: profiles?
override <- Sys.getenv("RENV_PATHS_LOCKFILE", unset = NA)
if (!is.na(override)) {
last <- substr(override, nchar(override), nchar(override))
if (last %in% c("/", "\\"))
override <- paste0(override, "renv.lock")
return(override)
}
# otherwise, use default location (location location relative to renv folder)
project <- renv_project_resolve(project)
renv <- renv_paths_renv(project = project)
file.path(dirname(renv), "renv.lock")
}
renv_paths_settings <- function(project = NULL) {
renv_paths_renv("settings.json", project = project)
}
renv_paths_activate <- function(project = NULL) {
renv_paths_renv("activate.R", profile = FALSE, project = project)
}
renv_paths_sandbox <- function(project = NULL) {
# construct a platform prefix
path <- R()
hash <- memoize(path, renv_hash_text(path), scope = "renv_paths_sandbox")
parts <- c(renv_platform_prefix(), substring(hash, 1L, 8L))
prefix <- paste(parts, collapse = "/")
# check for override
root <- Sys.getenv("RENV_PATHS_SANDBOX", unset = NA)
if (!is.na(root))
return(paste(c(root, prefix), collapse = "/"))
# otherwise, build path in user data directory
userdir <- renv_bootstrap_user_dir()
paste(c(userdir, "sandbox", prefix), collapse = "/")
}
renv_paths_renv <- function(..., profile = TRUE, project = NULL) {
renv_bootstrap_paths_renv(..., profile = profile, project = project)
}
renv_paths_cellar <- function(...) {
renv_paths_common("cellar", c(), ...)
}
renv_paths_local <- function(...) {
renv_paths_common("local", c(), ...)
}
renv_paths_source <- function(...) {
renv_paths_common("source", c(), ...)
}
renv_paths_binary <- function(...) {
renv_paths_common("binary", c(renv_platform_prefix()), ...)
}
renv_paths_cache <- function(..., version = NULL) {
platform <- renv_platform_prefix()
version <- version %||% renv_cache_version()
renv_paths_common("cache", c(version, platform), ...)
}
renv_paths_rtools <- function() {
root <- renv_paths_override("rtools")
if (is.null(root)) {
spec <- renv_rtools_find()
root <- spec$root
}
root %||% ""
}
renv_paths_extsoft <- function(...) {
renv_paths_common("extsoft", c(), ...)
}
renv_paths_p3m <- function(...) {
renv_paths_common("p3m", c(), ...)
}
renv_paths_index <- function(...) {
renv_paths_common("index", c(renv_platform_prefix()), ...)
}
renv_paths_root <- function(...) {
root <- renv_paths_override("root") %||% renv_paths_root_default()
file.path(root, ...) %||% ""
}
# nocov start
renv_paths_root_default <- function() {
the$root <- the$root %||% {
# use tempdir for cache when running tests
# this check is necessary here to support packages which might use renv
# during testing (and we don't want those to try to use the user dir)
if (checking())
renv_paths_root_default_tempdir()
else
renv_paths_root_default_impl()
}
}
renv_paths_root_default_impl <- function() {
# compute known root directories
roots <- c(
renv_paths_root_default_impl_v2(),
renv_paths_root_default_impl_v1()
)
# iterate through those roots, finding the first existing
for (root in roots)
if (file.exists(root))
return(root)
# if none exist, choose the most recent definition
roots[[1L]]
}
renv_paths_root_default_impl_v2 <- function() {
# try using tools to get the user directory
tools <- renv_namespace_load("tools")
if (is.function(tools$R_user_dir))
return(tools$R_user_dir("renv", "cache"))
renv_paths_root_default_impl_v2_fallback()
}
renv_paths_root_default_impl_v2_fallback <- function() {
# try using our own backfill for older versions of R
envvars <- c("R_USER_CACHE_DIR", "XDG_CACHE_HOME")
for (envvar in envvars) {
root <- Sys.getenv(envvar, unset = NA)
if (!is.na(root)) {
path <- file.path(root, "R/renv")
return(path)
}
}
# use platform-specific default fallbacks
if (renv_platform_windows())
file.path(Sys.getenv("LOCALAPPDATA"), "R/cache/R/renv")
else if (renv_platform_macos())
"~/Library/Caches/org.R-project.R/R/renv"
else
"~/.cache/R/renv"
}
renv_paths_root_default_impl_v1 <- function() {
base <- switch(
Sys.info()[["sysname"]],
Darwin = Sys.getenv("XDG_DATA_HOME", "~/Library/Application Support"),
Windows = Sys.getenv("LOCALAPPDATA", Sys.getenv("APPDATA")),
Sys.getenv("XDG_DATA_HOME", "~/.local/share")
)
file.path(base, "renv")
}
renv_paths_root_default_tempdir <- function() {
temp <- file.path(tempdir(), "renv")
ensure_directory(temp)
return(temp)
}
# nocov end
#' Path for storing global state
#'
#' @description
#' By default, renv stores global state in the following OS-specific folders:
#'
#' \tabular{ll}{
#' **Platform** \tab **Location** \cr
#' Linux \tab `~/.cache/R/renv` \cr
#' macOS \tab `~/Library/Caches/org.R-project.R/R/renv` \cr
#' Windows \tab `%LOCALAPPDATA%/R/cache/R/renv` \cr
#' }
#'
#' If desired, this path can be customized by setting the `RENV_PATHS_ROOT`
#' environment variable. This can be useful if you'd like, for example, multiple
#' users to be able to share a single global cache.
#'
#' # Customising individual paths
#'
#' The various state sub-directories can also be individually adjusted, if so
#' desired (e.g. you'd prefer to keep the cache of package installations on a
#' separate volume). The various environment variables that can be set are
#' enumerated below:
#'
#' \tabular{ll}{
#' \strong{Environment Variable} \tab \strong{Description} \cr
#' \code{RENV_PATHS_ROOT} \tab The root path used for global state storage. \cr
#' \code{RENV_PATHS_LIBRARY} \tab The path to the project library. \cr
#' \code{RENV_PATHS_LIBRARY_ROOT} \tab The parent path for project libraries. \cr
#' \code{RENV_PATHS_LIBRARY_STAGING} \tab The parent path used for staged package installs. \cr
#' \code{RENV_PATHS_SANDBOX} \tab The path to the sandboxed \R system library. \cr
#' \code{RENV_PATHS_LOCKFILE} \tab The path to the [lockfile]. \cr
#' \code{RENV_PATHS_CELLAR} \tab The path to the cellar, containing local package binaries and sources. \cr
#' \code{RENV_PATHS_SOURCE} \tab The path containing downloaded package sources. \cr
#' \code{RENV_PATHS_BINARY} \tab The path containing downloaded package binaries. \cr
#' \code{RENV_PATHS_CACHE} \tab The path containing cached package installations. \cr
#' \code{RENV_PATHS_PREFIX} \tab An optional prefix to prepend to the constructed library / cache paths. \cr
#' \code{RENV_PATHS_RENV} \tab The path to the project's renv folder. For advanced users only. \cr
#' \code{RENV_PATHS_RTOOLS} \tab (Windows only) The path to [Rtools](https://cran.r-project.org/bin/windows/Rtools/). \cr
#' \code{RENV_PATHS_EXTSOFT} \tab (Windows only) The path containing external software needed for compilation of Windows source packages. \cr
#' }
#'
#' (If you want these settings to persist in your project, it is recommended that
#' you add these to an appropriate \R startup file. For example, these could be
#' set in: a project-local `.Renviron`, the user-level `.Renviron`, or a
#' site-wide file at `file.path(R.home("etc"), "Renviron.site")`. See
#' [Startup] for more details).
#'
#' Note that renv will append platform-specific and version-specific entries
#' to the set paths as appropriate. For example, if you have set:
#'
#' ```
#' Sys.setenv(RENV_PATHS_CACHE = "/mnt/shared/renv/cache")
#' ```
#'
#' then the directory used for the cache will still depend on the renv cache
#' version (e.g. `v2`), the \R version (e.g. `3.5`) and the platform (e.g.
#' `x86_64-pc-linux-gnu`). For example:
#'
#' ```
#' /mnt/shared/renv/cache/v2/R-3.5/x86_64-pc-linux-gnu
#' ```
#'
#' This ensures that you can set a single `RENV_PATHS_CACHE` environment variable
#' globally without worry that it may cause collisions or errors if multiple
#' versions of \R needed to interact with the same cache.
#'
#' If reproducibility of a project is desired on a particular machine, it is
#' highly recommended that the renv cache of installed packages + binary
#' packages is backed up and persisted, so that packages can be easily restored
#' in the future -- installation of packages from source can often be arduous.
#'
#' # Sharing state across operating systems
#'
#' If you need to share the same cache with multiple different Linux operating
#' systems, you may want to set the `RENV_PATHS_PREFIX` environment variable
#' to help disambiguate the paths used on Linux. For example, setting
#' `RENV_PATHS_PREFIX = "ubuntu-bionic"` would instruct renv to construct a
#' cache path like:
#'
#' ```
#' /mnt/shared/renv/cache/v2/ubuntu-bionic/R-3.5/x86_64-pc-linux-gnu
#' ```
#'
#' If this is required, it's strongly recommended that this environment
#' variable is set in your \R installation's `Renviron.site` file, typically
#' located at `file.path(R.home("etc"), "Renviron.site")`, so that it can be
#' active for any \R sessions launched on that machine.
#'
#' Starting from `renv 0.13.0`, you can also instruct renv to auto-generate
#' an OS-specific component to include as part of library and cache paths,
#' by setting the environment variable:
#'
#' ```
#' RENV_PATHS_PREFIX_AUTO = TRUE
#' ```
#'
#' The prefix will be constructed based on fields within the system's
#' `/etc/os-release` file. Note that this is the default behavior with
#' `renv 1.0.6` when using R 4.4.0 or later.
#'
#' # Package cellar
#'
#' If your project depends on one or \R packages that are not available in any
#' remote location, you can still provide a locally-available tarball for renv
#' to use during restore. By default, these packages should be made available in
#' the folder as specified by the `RENV_PATHS_CELLAR` environment variable. The
#' package sources should be placed in a file at one of these locations:
#'
#' - `${RENV_PATHS_CELLAR}/_.`
#' - `${RENV_PATHS_CELLAR}//_.`
#' - `/renv/cellar/_.`
#' - `/renv/cellar//_
[](https://lifecycle.r-lib.org/articles/stages.html)
[](https://CRAN.R-project.org/package=renv)
[](https://github.com/rstudio/renv/actions)
## Overview
The renv package[^1] helps you create **r**eproducible **env**ironments
for your R projects. Use renv to make your R projects more isolated,
portable and reproducible.
- **Isolated**: Installing a new or updated package for one project
won’t break your other projects, and vice versa. That’s because renv
gives each project its own private library.
- **Portable**: Easily transport your projects from one computer to
another, even across different platforms. renv makes it easy to
install the packages your project depends on.
- **Reproducible**: renv records the exact package versions you depend
on, and ensures those exact versions are the ones that get installed
wherever you go.
## Installation
Install the latest version of renv from CRAN with:
``` r
install.packages("renv")
```
## Workflow
Use `renv::init()` to initialize renv in a new or existing project. This
will set up a **project library**, containing all the packages you’re
currently using. The packages (and all the metadata needed to reinstall
them) are recorded into a **lockfile**, `renv.lock`, and a `.Rprofile`
ensures that the library is used every time you open that project.
As you continue to work on your project, you will install and upgrade
packages, either using `install.packages()` and `update.packages` or
`renv::install()` and `renv::update()`. After you’ve confirmed your code
works as expected, use `renv::snapshot()` to record the packages and
their sources in the lockfile.
Later, if you need to share your code with someone else or run your code
on new machine, your collaborator (or you) can call `renv::restore()` to
reinstall the specific package versions recorded in the lockfile.
## Learning more
If this is your first time using renv, we strongly recommend starting
with the [Introduction to
renv](https://rstudio.github.io/renv/articles/renv.html) vignette: this
will help you understand the most important verbs and nouns of renv.
If you have a question about renv, please first check the
[FAQ](https://rstudio.github.io/renv/articles/faq.html) to see whether
your question has already been addressed. If it hasn’t, please feel free
to ask on the [Posit Forum](https://forum.posit.co).
If you believe you’ve found a bug in renv, please file a bug (and, if
possible, a [reproducible example](https://reprex.tidyverse.org)) at