Give Consent to Use Package Cache

These functions explicitly gives sandpaper permission to use renv to create a package cache for this and future lessons. There are two states that you can use:

use_package_cache(): Gives explicit permission to set up and use the package cache with your lesson.
no_package_cache(): Temporarily suspends permission to use the package cache with your lesson, regardless if it was previously given.

Once you have a package cache defined, you can use changes in the lockfile to trigger rebuilds of the lesson. To do this, you can use:

package_cache_trigger(TRUE)

The above function is best used in conjunction with update_cache()

Usage

use_package_cache(prompt = interactive(), quiet = !prompt)

no_package_cache()

package_cache_trigger(rebuild = NULL)

Arguments

prompt: if TRUE (default when interactive), a prompt for consent giving information about the proposed modifications will appear on the screen asking for the user to choose to apply the changes or not.
quiet: if TRUE, messages will not be issued unless prompt = TRUE. This defaults to the opposite of prompt.
rebuild: The new value of the sandpaper.package_cache_trigger global option. Setting this to TRUE will result in all materials being rebuilt when new records enter the package cache lockfile even if no source files have changed. Setting this to FALSE will return this to the default state, which is to rebuld only if the source files have changed. The default is NULL, which does nothing.

Value

nothing. this is used for its side-effect

the value of getOption("sandpaper.package_cache_trigger") or FALSE, if it is unset.

Details

Background

By default, sandpaper will happily build your lesson using the packages available in your default R library, but this can be undesirable for a couple of reasons:

You may have a different version of a lesson package that is used on the lesson website, which may result in strange errors, warnings, or incorrect output.
You might be very cautious about updating any components of your current R infrastructure because your work depends on you having the correct package versions installed.

To alleviate these concerns, sandpaper uses the renv package to generate a lesson-specific library that has package versions pinned until the lesson authors choose to update them. This is designed to be minimally-invasive, using the packages you already have and downloading from external repositories only when necessary.

What if I have used renv before?

If you have used renv in the past, then there is no need to give consent to use the cache.

How do I turn off the feature temporarily?

To turn off the feature you can use no_package_cache(). sandpaper will respect this option when building your lesson and will use your global library instead.

I have used renv before; how do I turn it off before sandpaper loads?

You can set options(sandpaper.use_renv = FALSE) before loading {sandpaper}.

Examples

if (!getOption("sandpaper.use_renv") && interactive()) {
  # The first time you set up `{renv}`, you will need permission
  use_package_cache(prompt = TRUE)
  # The package cache trigger is FALSE, by default
  default <- package_cache_trigger()
  # You can set this to `TRUE` when you update packages with `update_cache()`
  package_cache_trigger(TRUE)
  # set the trigger back to its former state
  package_cache_trigger(default)
}

if (getOption("sandpaper.use_renv") && interactive()) {
  # If you have previously used `{renv}`, permission is implied
  use_package_cache(prompt = TRUE)

  # You can temporarily turn this off
  no_package_cache()
  getOption("sandpaper.use_renv") # should be FALSE
  use_package_cache(prompt = TRUE)
}