Startup                 package:base                 R Documentation

_I_n_i_t_i_a_l_i_z_a_t_i_o_n _a_t _S_t_a_r_t _o_f _a_n _R _S_e_s_s_i_o_n

_D_e_s_c_r_i_p_t_i_o_n:

     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 except on Windows). The user
     files searched for are '.Renviron' in the current or in the user's
     home directory (in that order). 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")'.

     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'.

_U_s_a_g_e:

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

     .Rprofile <startup file>

_D_e_t_a_i_l_s:

     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.

_H_i_s_t_o_r_i_c_a_l _n_o_t_e_s:

     Prior to R version 1.4.0, the environment files searched were
     '.Renviron' in the current directory, the file pointed to by
     'R_ENVIRON' if set, and '.Renviron' in the user's home directory. 
     What is now 'Rprofile.site' was called 'Rprofile'.

     Prior to R version 1.2.1, '.Rprofile' was sourced after '.RData'
     was loaded, although the documented order was as here.

     The format for site and user environment files was changed in
     version 1.2.0.  Older files are quite likely to work but may
     generate warnings on startup if they contained unnecessary
     'export' statements.

     Values in environment files were not processed prior to version
     1.4.0.

_N_o_t_e:

     The file '$R_HOME/etc/Renviron' is always read very early in the
     start-up processing.  It contains environment variables set by R
     in the configure process.  Values in that file can be overriden in
     site or user environment files: do not change
     '$R_HOME/etc/Renviron' itself.  Note that this is distinct from
     '$R_HOME/etc/Renviron.site'.

_S_e_e _A_l_s_o:

     '.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'.

_E_x_a_m_p_l_e_s:

     ## 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)

