Invoking R from the command line
When working in UNIX or at a command line in Windows, the command ‘R’ can be used both for starting the main R program in the form
R [options] [<infile] [>outfile],
or, via the R CMD interface, as a wrapper to various R tools (e.g., for processing files in R documentation format or manipulating add-on packages) which are not intended to be called “directly”. Under UNIX you do need to ensure that either the environment variable TMPDIR is unset or it points to a valid place to create temporary files and directories. Most options control what happens at the beginning and at the end of an R session. The startup mechanism is as follows (see also the on-line help for topic ‘Startup’ for more information, and the section below for some Windows-specific details).
• Unless ‘--no-environ’ was given, 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, ‘$R_HOME/etc/Renviron.site’ is used (if it exists). The user file searched for is ‘.Renviron’ in the current or in the user’s home directory (in that order). These files should contain lines of the form ‘name=value’. (See help(Startup) for a precise description.) Variables you might want to set include R_PAPERSIZE (the default paper size), R_PRINTCMD (the default print command) and R_LIBS (specifies the list of R library trees searched for add-on packages).
• 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 that variable is unset, the default ‘$R_HOME/etc/Rprofile.site’ is used if this exists.
• 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.
• It also loads a saved image from ‘.RData’ if there is one (unless ‘--no-restore’ or ‘--no-restore-data’ was specified).
• Finally, if a function .First exists, it is executed. This function (as well as .Last which is executed at the end of the R session) can be defined in the appropriate startup profiles, or reside in ‘.RData’.
In addition, there are options for controlling the memory available to the R process (see the on-line help for topic ‘Memory’ for more information). Users will not normally need to use these unless they are trying to limit the amount of memory used by R. R accepts the following command-line options.
‘--help’
‘-h’ Print short help message to standard output and exit successfully.
‘--version’ Print version information to standard output and exit successfully.
‘RHOME’ Print the path to the R “home directory” to standard output and exit successfully.
Apart from the front-end shell script and the man page, R installation puts everything (executables, packages, etc.) into this directory.
‘--save’
‘--no-save’ Control whether data sets should be saved or not at the end of the R session. If neither is given in an interactive session, the user is asked for the desired behavior when ending the session with q(); in non-interactive use one of these must be specified.
‘--no-environ’ Do not read any user file to set environment variables.
‘--no-site-file’ Do not read the site-wide profile at startup.
‘--no-init-file’ Do not read the user’s profile at startup.
‘--restore’
‘--no-restore’
‘--no-restore-data’ Control whether saved images (file ‘.RData’ in the directory where R was started) should be restored at startup or not. The default is to restore. (‘--no-restore’ implies all the specific ‘--no-restore-*’ options.)
‘--no-restore-history’ Control whether the history file (normally file ‘.Rhistory’ in the directory where R was started, but can be set by the environment variable R_HISTFILE) should be restored at startup or not. The default is to restore.
‘--vanilla’ Combine ‘--no-save’, ‘--no-environ’ ‘--no-site-file’, ‘--no-init-file’ and
‘--no-restore’.
‘--no-readline’ (UNIX only) Turn off command-line editing via readline. This is useful when running R from within Emacs using the ESS (“Emacs Speaks Statistics”) package.
‘--ess’ (Windows only) Set Rterm up for use by R-inferior-mode in ESS.
‘--min-vsize=N’
‘--max-vsize=N’ Specify the minimum or maximum amount of memory used for variable size objects by setting the “vector heap” size to N bytes. Here, N must either be an integer or an integer ending with ‘G’, ‘M’, ‘K’, or ‘k’, meaning ‘Giga’ (2^30), ‘Mega’ (2^20), (computer) ‘Kilo’ (2^10), or regular ‘kilo’ (1000).
‘--min-nsize=N’
‘--max-nsize=N’ Specify the amount of memory used for fixed size objects by setting the number of “cons cells” to N. See the previous option for details on N. A cons cell takes 28 bytes on a 32-bit machine, and usually 56 bytes on a 64-bit machine.
‘--max-ppsize=N’ Specify the maximum size of the pointer protection stack as N locations. This defaults to 10000, but can be increased to allow large and complicated calculations to be done. Currently the maximum value accepted is 100000.
‘--max-mem-size=N’ (Windows only) Specify a limit for the amount of memory to be used both for R objects and working areas. This is set by default to the smaller of 1024Mb and the amount of physical RAM in the machine, and must be at least 16Mb.
‘--quiet’
‘--silent’
‘-q’ Do not print out the initial copyright and welcome messages.
‘--slave’ Make R run as quietly as possible. This option is intended to support programs which use R to compute results for them.
‘--verbose’ Print more information about progress, and in particular set R’s option verbose to TRUE. R code uses this option to control the printing of diagnostic messages.
‘--debugger=name’
‘-d name’ (UNIX only) Run R through debugger name. Note that in this case, further command line options are disregarded, and should instead be given when starting the R executable from inside the debugger.
‘--gui=type’
‘-g type’ (UNIX only) Use type as graphical user interface (note that this also includes interactive graphics). Currently, possible values for type are ‘X11’ (the default), provided that ‘Tcl/Tk’ support is available, ‘Tk’, ‘gnome’ provided that GNOME support is available, and ‘none’.
‘--args’ This flag does nothing except cause the rest of the command line to be skipped: this can be useful to retrieve values from it with commandArgs(). Note that input and output can be redirected in the usual way (using ‘<’ and ‘>’). Warning and error messages are sent to the error channel (stderr) except on Windows 9X/ME. The command R CMD allows the invocation of various tools which are useful in conjunction with R, but not intended to be called “directly”. The general form is R CMD command args where command is the name of the tool and args the arguments passed on to it. Currently, the following tools are available.
BATCH Run R in batch mode.
COMPILE (UNIX only) Compile files for use with R.
SHLIB Build shared library for dynamic loading.
INSTALL Install add-on packages.
REMOVE Remove add-on packages.
build Build add-on packages.
check Check add-on packages.
LINK (UNIX only) Front-end for creating executable programs.
Rprof Post-process R profiling files.
Rdconv Convert Rd format to various other formats, including HTML, Nroff, LaTEX, plain text, and S documentation format.
Rd2dvi Convert Rd format to DVI/PDF.
Rd2txt Convert Rd format to text.
Sd2Rd Convert S documentation to Rd format.
config (UNIX only) Obtain configuration information. Use R CMD command --help to obtain usage information for each of the tools accessible via the R CMD interface.
Invoking R under Windows
There are two ways to run R under Windows. Within a terminal window (e.g. cmd.exe or command.com or a more capable shell), the methods described in the previous section may be used, invoking by R.exe or more directly by Rterm.exe. (These are principally intended for batch use.) For interactive use, there is a console-based GUI (Rgui.exe). The startup procedure under Windows is very similar to that under UNIX, but references to the ‘home directory’ need to be clarified, as this is not always defined on Windows.
If the environment variable R_USER is defined, that gives the home directory. Next, if the environment variable HOME is defined, that gives the home directory. After those two user-controllable settings, R tries to find system defined home directories. It first tries to use the Windows "personal" directory (typically C:\Documents and Settings\username\My Documents in Windows XP). If that fails, and environment variables HOMEDRIVE and HOMEPATH are defined (and they normally are under Windows NT/2000/XP) these define the home directory. Failing all those, the home directory is taken to be the starting directory. Environment variables can be supplied as ‘name=value’ pairs at the end of the command line. The following additional command-line options are available when invoking RGui.exe.
‘--mdi’
‘--sdi’
‘--no-mdi’ Control whether Rgui will operate as an MDI program (the default, with multiple child windows within one main window) or an SDI application (with multiple toplevel windows for the console, graphics and pager).
‘--debug’ Enable the “Break to debugger” menu item in Rgui, and trigger a break to the debugger during command line processing.
In Windows with R CMD you may also specify your own *.bat or *.exe file instead of one of the built-in commands. It will be run with the following environment variables set appropriately: R_HOME, R_VERSION, R_CMD, R_OSTYPE, PATH, PERL5LIB, and TEXINPUTS. For example, if you already have latex.exe on your path, then R CMD latex.exe mydoc will run LaTeX on mydoc.tex, with the path to R’s share/texmf macros added to TEXINPUTS.
Invoking R under Mac OS X
There are two ways to run R under Mac OS X. Within a Terminal.app window by invoking R, the methods described in the previous sections apply. There is also console-based GUI (R.app) that by default is installed in the Applications folder on your system. It is a standard doubleclickable Mac OS X application. The startup procedure under Mac OS X is very similar to that under UNIX. The ‘home directory’ is the one inside the R.framework, but the startup and current working directory are set as the user’s home directory unless a different startup directory is given in the Preferences window accessible from within the GUI.
Next: Appendix C The command-line editor
Summary: Index