Initialize a Project — init • renv

Discover packages used within the current project, and then initialize a project-local private R library with those packages. The currently-installed versions of any packages in use (as detected within the default R libraries) are then installed to the project's private library.

Usage

init(
  project = NULL,
  ...,
  profile = NULL,
  settings = NULL,
  bare = FALSE,
  force = FALSE,
  repos = NULL,
  bioconductor = NULL,
  restart = interactive()
)

Arguments

project: The project directory. The R working directory will be changed to match the requested project directory.
...: Unused arguments, reserved for future expansion. If any arguments are matched to ..., renv will signal an error.
profile: The profile to be activated. When NULL, the default profile is activated instead. See vignette("profiles", package = "renv") for more information.
settings: A list of settings to be used with the newly-initialized project.
bare: Boolean; initialize the project without attempting to discover and install R package dependencies?
force: Boolean; force initialization? By default, renv will refuse to initialize the home directory as a project, to defend against accidental mis-usages of init().
repos: The R repositories to be used in this project. By default, the active repositories (as determined by getOption("repos")) are used.
bioconductor: The version of Bioconductor to be used with this project. Setting this may be appropriate if renv is unable to determine that your project depends on a package normally available from Bioconductor. Set this to TRUE to use the default version of Bioconductor recommended by the BiocManager package.
restart: Boolean; attempt to restart the R session after initializing the project? A session restart will be attempted if the "restart" R option is set by the frontend embedding R.

Value

The project directory, invisibly. Note that this function is normally called for its side effects.

Details

The primary steps taken when initializing a new project are:

R package dependencies are discovered within the R files used within the project with dependencies();
Discovered packages are copied into the renv global package cache, so these packages can be re-used across future projects as necessary;
Any missing R package dependencies discovered are then installed into the project's private library;
A lockfile capturing the state of the project's library is created with snapshot();
The project is activated with activate().

If renv sees that the associated project has already been initialized and has a lockfile, then it will attempt to infer the appropriate action to take based on the presence of a private library. If no library is available, renv will restore the private library from the lockfile; if one is available, renv will ask if you want to perform a 'standard' init, restore from the lockfile, or activate the project without taking any further action.

Infrastructure

renv will write or amend the following files in the project:

.Rprofile: An auto-loader will be installed, so that new R sessions launched within the project are automatically loaded.
renv/activate.R: This script is run by the previously-mentioned .Rprofile to load the project.
renv/.gitignore: This is used to instruct Git to ignore the project's private library, as it should normally not be committed to a version control repository.
.Rbuildignore: to ensure that the renv directory is ignored during package development; e.g. when attempting to build or install a package using renv.

Examples


if (FALSE) {

# disable automatic snapshots
auto.snapshot <- getOption("renv.config.auto.snapshot")
options(renv.config.auto.snapshot = FALSE)

# initialize a new project (with an empty R library)
renv::init(bare = TRUE)

# install digest 0.6.19
renv::install("digest@0.6.19")

# save library state to lockfile
renv::snapshot()

# remove digest from library
renv::remove("digest")

# check library status
renv::status()

# restore lockfile, thereby reinstalling digest 0.6.19
renv::restore()

# restore automatic snapshots
options(renv.config.auto.snapshot = auto.snapshot)

}