Initialization at Start of an R Session

Description

In R, the startup mechanism is as follows.

Unless --no-environ was given on the command line, R searches for user and site files to process for setting environment variables. The name of the site file is the one pointed to by the environment variable R_ENVIRON; if this is unset or empty, ‘$R_HOME/etc/Renviron.site’ is used (if it exists, which it does not in a “factory-fresh” installation). The user files searched for are ‘.Renviron’ in the current or in the user's home directory (in that order). (See ‘See also’ for how the home directory is found on Windows. See Details for how the files are read.

Then R searches for the site-wide startup profile unless the command line option --no-site-file was given. The name of this file is taken from the value of the R_PROFILE environment variable. If this variable is unset, the default is ‘$R_HOME/etc/Rprofile.site’, which is used if it exists (which it does not in a “factory-fresh” installation). This code is loaded into package base. Users need to be careful not to unintentionally overwrite objects in base, and it is normally advisable to use local if code needs to be executed: see the examples.

Then, unless --no-init-file was given, R searches for a file called ‘.Rprofile’ in the current directory or in the user's home directory (in that order) and sources it into the user workspace.

It then loads a saved image of the user workspace from ‘.RData’ if there is one (unless --no-restore-data was specified, or --no-restore, on the command line).

Next, if a function .First is found on the search path, it is executed as .First(). Finally, function .First.sys() in the base package is run. This calls require to attach the default packages specified by options("defaultPackages"). If the methods package is included, this will have been attached earlier, by function .OptRequireMethods(), so that namespace initializations such as those from the user workspace will proceed correctly.

A function .First (and .Last) can be defined in appropriate ‘.Rprofile’ or ‘Rprofile.site’ files or have been saved in ‘.RData’. If you want a different set of packages than the default ones when you start, insert a call to options in the ‘.Rprofile’ or ‘Rprofile.site’ file. For example, options(defaultPackages = character()) will attach no extra packages on startup. Alternatively, set R_DEFAULT_PACKAGES=NULL as an environment variable before running R. Using options(defaultPackages = "") or R_DEFAULT_PACKAGES="" enforces the R system default.

The commands history is read from the file specified by the environment variable R_HISTFILE (default ‘.Rhistory’) unless --no-restore-history was specified (or --no-restore).

The command-line flag --vanilla implies --no-site-file, --no-init-file, --no-restore and --no-environ. In Windows, it also implies --no-Rconsole, which prevents loading the Rconsole file.

Usage

.First <- function() { ...... }

.Rprofile <startup file>

Details

Note that there are two sorts of files used in startup: environment files which contain lists of environment variables to be set, and profile files which contain R code.

Lines in a site or user environment file should be either comment lines starting with #, or lines of the form name=value. The latter sets the environmental variable name to value, overriding an existing value. If value contains an expression of the form ${foo-bar}, the value is that of the environmental variable foo if that exists and is set to a non-empty value, otherwise bar. (If it is of the form ${foo}, the default is "".) This construction can be nested, so bar can be of the same form (as in ${foo-${bar-blah}}). Note that the braces are essential: $HOME will not be interpreted.

Leading and trailing white space in value are stripped. value is processed in a similar way to a Unix shell. In particular the outermost level of (single or double) quotes is stripped, and backslashes are removed except inside quotes.

Note

Unix versions of R have a file ‘$R_HOME/etc/Renviron’ which is read very early in the start-up processing. It contains environment variables set by R in the configure process, and is not used on R for Windows.

See Also

For the definition of the home directory see the rw-FAQ. It can be found from a running R by Sys.getenv("R_USER").

.Last for final actions before termination. commandArgs for accessing the command line arguments.

An Introduction to R for more command-line options: those affecting memory management are covered in the help file for Memory.

For profiling code, see Rprof.

Examples

## Not run: 
# Example ~/.Renviron on Unix
R_LIBS=~/R/library
PAGER=/usr/local/bin/less

# Example .Renviron on Windows
R_LIBS=C:/R/library
MY_TCLTK=yes
TCL_LIBRARY=c:/packages/Tcl/lib/tcl8.4

# Example of .Rprofile
options(width=65, digits=5)
options(show.signif.stars=FALSE)
ps.options(horizontal=FALSE)
set.seed(1234)
.First <- function() cat("\n   Welcome to R!\n\n")
.Last <- function()  cat("\n   Goodbye!\n\n")

# Example of Rprofile.site
local({
  old <- getOption("defaultPackages")
  options(defaultPackages = c(old, "MASS"))
})

## if .Renviron contains
FOOBAR="coo\bar"doh\ex"abc\"def'"

## then we get
> cat(Sys.getenv("FOOBAR"), "\n")
coo\bardoh\exabc"def'
## End(Not run)