startup: Friendly R Startup Configuration

Introduction

When you start R, it will by default source a .Rprofile file if it exists. This allows you to automatically tweak your R settings to meet your everyday needs. For instance, you may want to set the default CRAN repository (options("repos")) so you don't have to choose one every time you install a package.

The startup package extends the default R startup process by allowing you to put multiple startup scripts in a common .Rprofile.d directory and have them all be sourced during the R startup process. This way you can have one file to configure the default CRAN repository and another one to configure your personal devtools settings. Similarly, you can use a .Renviron.d directory with multiple files defining different environment variables. For instance, one file may define environment variable LANGUAGE, whereas another file may contain your private GITHUB_PAT key. The advantages of this approach are that it gives a better overview when you list the files, makes it easier to share certain settings (= certain files) with other users, and enable you to keep specific files completely private (by setting the file privileges so only you can access those settings).

How the R startup process works

When R starts, the following user-specific setup takes place:

1. The first .Renviron file found on the R startup search path is processed. The search path is (in order): (i) Sys.getenv("R_ENVIRON_USER"), (ii) ./.Renviron, and (iii) ~/.Renviron. The format of this file is one ENV_VAR=VALUE statement per line, cf. ?.Renviron. NOTE: Some environment variables must be set already in this step in order to be acknowledged by R, i.e. it is too late to set some of them in Step 2 and Step 3 below.

2. The first .Rprofile file found on the R startup search path is processed. The search path is (in order): (i) Sys.getenv("R_PROFILE_USER"), (ii) ./.Rprofile, and (iii) ~/.Rprofile. The format of this file must be a valid R script (with a trailing newline), cf. ?.Rprofile.

3. If the .Rprofile file (in Step 2) calls startup::startup() then the following will also take place:

   a. The first .Renviron.d directory on the R startup search path is processed. The search path is (in order): (i) paste0(Sys.getenv("R_ENVIRON_USER"), ".d"), (ii) ./.Renviron.d, and (iii) ~/.Renviron.d. The format of these files should be the same as for .Renviron. NOTE: Some environment variables must be set already in Step 1 above in order to be acknowledged by R.

   b. A set of handy R options that can be use in Step 3c are set. Their names are prefixed startup.session. - see ?startup::startup_session_options for details.

   c. The first .Rprofile.d directory found on the R startup search path is processed. The search path is (in order): (i) paste0(Sys.getenv("R_PROFILE_USER"), ".d"), (ii) ./.Rprofile.d, and (iii) ~/.Rprofile.d. The format of these files should be the same as for .Rprofile, that is, they must be valid R scripts.

   d. If no errors occur above, the startup package will be unloaded, leaving no trace of itself behind, except for R options startup.session.* set in Step 3b - these will be erased if startup::startup() is called with keep = NULL.

All relevant files in directories .Renviron.d and .Rprofile.d, including those found recursively in subdirectories thereof, will be processed (in lexicographic order sorted under the C locale). There are no restrictions on what the file names should be (except for the ones ignored as explained below). However, for .Rprofile.d we recommend to use filename extension *.R to indicate that the files are regular R scripts. For .Renviron.d we recommend to use files without extensions (or *.Renviron for clarification). To avoid confusions, do not use an *.R extension for Renviron files because they are not R script per se (as some editors may warn you about).

Files with file extensions *.txt, *.md and *~ are ignored as well as any files named .Rhistory, .RData and .DS_Store. Directories named __MACOSX and their content are ignored. Files and directories with names starting with two periods (..) are ignored, e.g. ~/.Rprofile.d/..my-tests/.

Installation

After installing the startup packages (see instructions at the end), call

startup::install()

once. This will append

try(startup::startup())

to your ~/.Rprofile. The file will be created if missing. This will also create directories ~/.Renviron.d/ and ~/.Rprofile.d/ if missing. To find the location of these folder on Windows, use normalizePath("~") - it's often located under C:\Users\Alice\Documents\.

Alternatively to the above installation setup, you can just add try(startup::startup()) to your ~/.Rprofile file manually. The reason for using try() is for the case when startup is not installed and you try to install it, e.g. after upgrading R to a new major release. Without try(), R will fail to install the startup package (or any other package) because the R profile startup script produces an error complaining about startup not being available.

Usage

Just start R :)

To debug the startup process, use startup::startup(debug = TRUE) or set environment variable R_STARTUP_DEBUG=TRUE, e.g. on Linux you can do

$ R_STARTUP_DEBUG=TRUE R

This will produce time-stamped messages during startup specifying which files are included.

Conditional file and directory names

If the name of a file consists of a <key>=<value> specification, then that file will be included / used only if the specification is fulfilled (on the current system with the current R setup). For instance, a file ~/.Rprofile.d/os=windows.R will be ignored unless startup::sysinfo()$os == "windows", i.e. the R session is started on a Windows system.

The following startup::sysinfo() keys are available for conditional inclusion of files by their path names:

• Values:
  • gui - (character) the graphical user interface (= .Platform$GUI)
  • nodename - (character) the host name (= Sys.info()[["nodename"]])
  • machine - (character) the machine type (= Sys.info()[["machine"]])
  • os - (character) the operating system (= .Platform$OS.type)
  • sysname - (character) the system name (= Sys.info()[["sysname"]])
  • user - (character) the user name (= Sys.info()[["user"]])
• Flags:
  • interactive - (logical) whether running R interactively or not (= interactive())
  • ess - (logical) whether running R in Emacs Speaks Statistics (ESS) or not
  • rice - (logical) whether running R in rice or not
  • rstudio - (logical) whether running R in RStudio or not
  • wine - (logical) whether running R on Windows via Linux Wine or not

You can also include files conditionally on whether a package is installed or not:

• package - (character) whether a package is installed or not

In addition to checking the availability, having package=<name> in the filename makes it clear that the startup file concerns settings specific to that package.

Any further <key>=<value> specifications with keys matching none of the above known keys are interpreted as system environment variables and startup will test such conditions against their values. Note, if <key> does not correspond to a known environment variable, then the condition is ignored. For instance, a startup file or directory containing LANGUAGE=fr will be processed only if the environment variable LANGUAGE equals fr (or is not set).

To condition on more than one key, separate <key>=<value> pairs by commas, e.g. ~/.Rprofile.d/work,interactive=TRUE,os=windows.R. This also works for directory names. For instance, ~/.Rprofile.d/os=windows/work,interactive=TRUE.R will be processed if running on Windows and in interactive mode. Multiple packages may be specified. For instance, ~/.Rprofile.d/package=devtools,package=future.R will be used only if both the devtools and the future packages are installed.

It is also possible to negate a conditional filename test by using the <key>!=<value> specification. For instance, ~/.Rprofile.d/package=doMC,os!=windows.R will be processed if package doMC is installed and the operating system is not Windows.

Known limitations

Setting environment variables during startup

Renviron startup files is a convenient and cross-platform way of setting environment variables during the R startup process. However, for some of the environment variables that R consults must be set early on in the R startup process (immediately after Step 1), because R only consults them once. An example(*) of environment variables that need to be set no later than .Renviron (Step 1) are:

• LC_ALL - locale settings used by R, e.g. cf. ?locales
• R_DEFAULT_PACKAGES - default set of packages loaded when R starts, cf. ?Rscript
• R_LIBS_USER - user's library path, e.g. R_LIBS_USER=~/R/%p-library/%v is the folder specification used by default on all platforms and and R version. The folder must exist, otherwise it is ignored by R. The The %p and %v parts are R-specific conversion specifiers, cf. ?R_LIBS_USER
• R_MAX_NUM_DLLS, cf. ?dyn.load

Any changes to these done in an .Renviron.d/* file (Step 3a), or via Sys.setenv() in .Rprofile (Step 2) or .Rprofile.d/* files (Step 3c), will be ignored by R itself - despite being reflected by Sys.getenv().

Furthermore, some environment variables can not even be set in .Renviron (Step 1) but must be set prior to launching R. This is because those variables are consulted by R very early on (prior to Step 1). An example(*) of environment variables that need to be set prior to .Renviron (Step 1):

• HOME - the user's home directory
• TMPDIR, TMP, TEMP - the parent of R's temporary directory, cf. ?tempdir
• MKL_NUM_THREADS and OMP_NUM_THREADS - the default number of threads used by OpenMP etc, cf. R Installation and Administration

In other words, these variables have to be set using methods specific to the operating system or the calling shell, e.g. in Unix shells

$ export TMPDIR=/path/to/tmp
$ R

or per call as

TMPDIR=/path/to/tmp R

(*) For further details on which environment variables R consults and what they are used for by R, see the R documentation and help, e.g. ?"environment variables" and ?Startup.

Examples

Below is a list of "real-world" example files:

.Renviron.d/
  +-- lang
  +-- libs
  +-- r_cmd_check
  +-- secrets
 
.Rprofile.d/
  +-- interactive=TRUE/
      +-- help.start.R
      +-- misc.R
	  +-- package=fortunes.R
  +-- os=windows.R
  +-- repos.R

They are available as part of this package under system.file(package = "startup"), e.g.

> f <- system.file(".Rprofile.d", "repos.R", package = "startup")
> file.show(f, type = "text")

local({
  repos <- c(CRAN = "https://cloud.r-project.org")
  if (.Platform$OS.type == "windows") {
     repos["CRANextra"] <- "https://www.stats.ox.ac.uk/pub/RWin"
  }
  options(repos = c(repos, getOption("repos")))
})

Installation

R package startup is available on CRAN and can be installed in R as:

install.packages('startup')

Pre-release version

To install the pre-release version that is available in Git branch develop on GitHub, use:

source('http://callr.org/install#HenrikBengtsson/startup@develop')

This will install the package from source.

Contributions

This Git repository uses the Git Flow branching model (the git flow extension is useful for this). The develop branch contains the latest contributions and other code that will appear in the next release, and the master branch contains the code of the latest release, which is exactly what is currently on CRAN.

Contributing to this package is easy. Just send a pull request. When you send your PR, make sure develop is the destination branch on the startup repository. Your PR should pass R CMD check --as-cran, which will also be checked by Travis CI and AppVeyor CI when the PR is submitted.

Software status