A customized provisioner for Carpentries Lessons based on renv that will install and maintain the requirements for the lesson while respecting user environments. This setup leads to several advantages:
reliable setup: the version of the lesson built on the carpentries website will be the same as what you build on your computer because the packages will be identical
environmentally friendly: The lesson dependencies are NOT stored in your default R library and they will not alter your R environment.
transparent: any additions or deletions to the cache will be recorded in the lockfile, which is tracked by git.
The functions that control this cache are the following:
manage_deps()
: Creates and updates the dependencies in your lesson. If no lockfile exists in your lesson, this will create one for you.update_cache()
: fetches updates for the dependencies and applies them to your cache and lockfile.
This is a wrapper around renv::record()
, which helps you record a package
or set of packages in your lockfile. It can be useful when you want to
upgrade or downgrade a specific package.
Usage
manage_deps(
path = ".",
profile = "lesson-requirements",
snapshot = TRUE,
quiet = FALSE
)
update_cache(
path = ".",
profile = "lesson-requirements",
prompt = interactive(),
quiet = !prompt,
snapshot = TRUE
)
pin_version(records = NULL, profile = "lesson-requirements", path = ".")
Arguments
- path
path to your lesson. Defaults to the current working directory.
- profile
default to the profile for the lesson. Defaults to
lesson-requirements
. Only use this if you know what you are doing.- snapshot
if
TRUE
, packages from the cache are added to the lockfile (default). Setting this toFALSE
will add packages to the cache and not snapshot them.- quiet
if
TRUE
, output will be suppressed, defaults toFALSE
, providing output about different steps in the process of updating the local dependencies.- prompt
if
TRUE
, a message will show you the packages that will be updated in your lockfile and ask for your permission. This is the default if it's running in an interactive session.- records
a character vector or list of packages/resources to include in the lockfile. The most common way to do this is to use the
[package]@[version]
syntax (e.g.gert@0.1.3
), but there are other specifications where you can specify the remote repository. Seerenv::record()
for details.
Value
if snapshot = TRUE
, a nested list representing the lockfile will be
returned.
the contents of the lockfile, invisibly
Details
The renv package provides a very useful interface to bring one aspect of reproducibility to R projects. Because people working on Carpentries lessons are also working academics and will likely have projects on their computer where the package versions are necessary for their work, it's important that those environments are respected.
Our flavor of {renv}
applies a package cache explicitly to the content of
the lesson, but does not impose itself as the default {renv}
environment.
This provisioner will do the following steps:
check for consent to use the package cache via
use_package_cache()
and prompt for it if neededcheck if the profile has been created and create it if needed via
renv::init()
populate the cache with packages needed from the user's system and download any that are missing via
renv::hydrate()
. This includes all new packages that have been added to the lesson.If there is a lockfile already present, make sure the packages in the cache are aligned with the lockfile (downloading sources if needed) via
renv::restore()
.Record the state of the cache in a lockfile tracked by git. This will include adding new packages and removing old packages.
renv::snapshot()
When the lockfile changes, you will see it in git and have the power to either commit or restore those changes.
See also
use_package_cache()
and no_package_cache()
for turning on and
off the package cache, respectively.