rprofile (version 0.4.0)

load: Initialize an R session by loading the all relevant R profile configurations

Description

rprofile::load() attempts to load the global R profile configuration and any other common project configuration.

Usage

rprofile::load(..., isolate = FALSE, renv = TRUE, dotenv = TRUE, dev = TRUE)

Value

rprofile::load() will invisibly return whether loading the user R profile file succeeded: in case of an error, it returns FALSE and converts the error into a warning.

Arguments

...

ignored; forces named argument passing

isolate

[logical(1)] whether to isolate the project from the global configuration (default: FALSE)

renv

[logical(1)] whether to activate an renv, if present (default: TRUE)

dotenv

[logical(1)] whether to load environment variables defined in a local .env file (default: TRUE)

dev

[logical(1)|call] whether to run pkgload::load_all() if the current project is a development package (default: TRUE; see Details)

Details

This function should be the first thing that gets executed inside a project .Rprofile file, and it should usually be written exactly as follows: if (requireNamespace("rprofile", quietly = TRUE)) rprofile::load() (the if being present to ensure that R CMD can still run in the current directory when rprofile is not installed).

Unless isolate = TRUE is set, the user R profile configuration is preferentially looked up in the R_PROFILE_USER environment variable. If that is unset, it is instead loaded from ~/.Rprofile. It is loaded (mostly) as-if its code was directly copied into the project .Rprofile file. By contrast, if isolate = TRUE is set, no attempt to load any further .Rprofile files is made.

rprofile::load() will by default also activate the renv associated with the current project, if any, and will also load environment variables defined in a local .env file. These two actions will happen before the user profile is loaded. See the Note below.

Lastly, rprofile::load() will check if the code is being run from an interactive session. If so, and if the project contains a DESCRIPTION file, rprofile will attempt to load pkgload and then execute pkgload::load_all(export_all = FALSE). To avoid disrupting the regular package load order, this action will be deferred until after all default packages (given by getOption('defaultPackages')) have been loaded and attached. Users can customize which code should be run by passing an unevaluated expression (instead of TRUE) in the dev argument. Since this code will be evaluated after the remaining .Rprofile code has been run, the argument may refer to functions defined afterwards (see Examples).

Examples

# Each option is configurable; in the extreme case, the function does nothing:
rprofile::load(isolate = TRUE, renv = FALSE, dotenv = FALSE, dev = FALSE)

if (FALSE) {
# In general, the following code should be the first line of a project
# `.Rprofile` file, which first tests whether the package is installed, and then
# loads it and runs the chosen initializations:
if (requireNamespace("rprofile", quietly = TRUE)) rprofile::load()
}

if (FALSE) {
# We can customize how to load development packages:
if (requireNamespace("rprofile", quietly = TRUE)) rprofile::load(dev = quote(reload()))

reload = function () {
  devtools::document()
  devtools::load_all(quiet = TRUE)
}
}