Lesson Runtime Dependency ManagementSource:
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.
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 = ".")
path to your lesson. Defaults to the current working directory.
default to the profile for the lesson. Defaults to
lesson-requirements. Only use this if you know what you are doing.
TRUE, packages from the cache are added to the lockfile (default). Setting this to
FALSEwill add packages to the cache and not snapshot them.
TRUE, output will be suppressed, defaults to
FALSE, providing output about different steps in the process of updating the local dependencies.
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.
a character vector or list of packages/resources to include in the lockfile. The most common way to do this is to use the
email@example.com), but there are other specifications where you can specify the remote repository. See
snapshot = TRUE, a nested list representing the lockfile will be
the contents of the lockfile, invisibly
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 needed
check if the profile has been created and create it if needed via
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
Record the state of the cache in a lockfile tracked by git. This will include adding new packages and removing old packages.
When the lockfile changes, you will see it in git and have the power to either commit or restore those changes.
no_package_cache() for turning on and
off the package cache, respectively.