Factor our configuration resolution mechanism to a separate package so others can use it

[lorenzwalthert]

In my limited understanding, {renv} has a sophisticated configuration resolution mechanism:

user-level configs

Uses R options in the form of renv.config.<name>, or RENV_CONFIG_<NAME>⁠ (with resolving conflicts), e.g. in .Rprofile or .Renviron. These can be accessed in session with renv::config.

project-local settings

Allows two ways of specifying option defaults with resolving conflicts (e.g. in .Rprofile):

options(renv.settings = list(snapshot.type = "all"))
options(renv.settings.snapshot.type = "all")

These can be accessed and changed in session with renv::settings and are persistent within renv/settings.json

The configuration options are well documented leveraging R's helpfile mechanism. I believe resolving project-local and user-level configurations is a very generic functionality for R packages, and many packages have opted to implement their own, using various file formats, heuristics and logic, creating friction for users and maintenance burden for developers. I myself have experimented before (since people have long asked to allow configuring {styler} with a config file), creating a prototype {fallback} that tackles the problem in an even more general way. However, I abandoned that approach due to a lack of time. But I don't think we need to re-invent the wheel for every package anew, it would be great to have a standard way of resolving configuration on a user and project level.

Hence, I was wondering if you'd consider exposing the config resolution mechanism of {renv} in a separate package so other package developers (or even just R users) could use it.

[salim-b]

it would be great to have a standard way of resolving configuration on a user and project level

I'm also interested in this topic. Mainly for my own use, I've added a bunch of functions around this to the pal package a while ago. It lacks a vignette or something similar, but you can read about the operation principle in pal::pkg_config_val()'s documentation. It lacks support for config files as config value resolution source, but that could easily be added (I'd rely on the config package for this under the hood, I guess).

pal is not on CRAN. But I was thinking about outsourcing the pkg_config_* functions into a separate package for a while now.

Would it be important to you to avoid dependencies as much as possible and only use base R in such a package?

[kevinushey]

I'm going to give a quick brain dump of some of my rationale for the design here...

Options and Environment Variables

Depending on how renv is used, it might be more ergonomic to set environment variables as opposed to R options (e.g. CI). That's why I wanted to support both for these options. The main downside is that encoding the "type" for environment variables is trickier; e.g. do we need a standard way to provide a vector of values (which might be numbers, strings, otherwise)? What should that be?

The main downside to the above approach is that it becomes much harder to trace the source of a particular option -- e.g. we don't know when or why a particular environment variable was set. (Compared to alternatives like requiring these be declared in a specific file.) It seems like this isn't usually a huge issue, though?

"Personal" vs. "Shared" Configurations

There's also options that are "personal" versus options that are "shared". For example, if multiple users are working with the same renv project, some users might prefer automatic snapshots, while others might not. I think it's okay if different users have different configurations in these scenarios.

Options that are "shared" are things that all collaborators on a project should be using. For example, I expect collaborators on a project are all going to want to use the same snapshot type. These sorts of "shared" options should typically be stored as project options. However, I can also imagine some users might have "personal" project options; that is, project-specific configurations that they only want to use locally, but are still compatible in collaborative environments.

In effect, the distinction between user-level and project-level configuration for renv is occasionally a bit blurry, but user-level configuration is normally "personal" options, whereas project-level configuration are "shared" options which should apply to all users / collaborators in a project.

Config API

The upside of having R functions for setting these options is that we can validate these when they're set; e.g. ensure that a snapshot type that's set is actually one of the supported fields. The downside is that, depending on your editor, it might be easier to just edit e.g. a JSON configuration file, assuming your editor can provide relevant help + autocompletions. (RStudio doesn't do this, but VSCode and other editors using JSON LSPs can do this.)

I also chose to hide the getters and setters for these functions in the lists config and settings for a few reasons:

• I didn't want autocompletion to get cluttered with a whole bunch of results config_snapshot_auto(), since these aren't used as part of day-to-day workflows.

• I still wanted autocompletion to be available, so that users can quickly scan and see all of the config / settings available just by typing config$ or settings$. I find APIs like config$get("name_of_option") are frustrating to use, since it's easy to forget the exact spelling of "name_of_option".

In hindsight, I think I would've mildly preferred something like config$option$get() and config$option$set(), as opposed to having config$option() be a function that either gets or sets based on the parameters provided.

All that said, I do sort of wonder if an API like config$user$<...> and config$project$<...> would have been better, since the words config and settings on their own don't really evoke the distinction of "user-specific" versus "project-specific".

Automatic Generation

In renv, the config getters and setters are all generated from https://github.com/rstudio/renv/blob/main/inst/config.yml, using code in

renv/R/zzz.R

Lines 156 to 219 in 6ac50e1

	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!")
	}

. I'm not totally sold on this being the best approach, but I really like being able to declaratively provide option names, types, descriptions, and so on. This isn't done for settings but I think it'd be worth doing.