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”.
You 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 informa-tion, 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 is the one pointed to by the environment variable R_ENVIRON_USER if this is set; otherwise, files ‘.Renviron’ in the current or in the user’s home directory (in that order) are searched for. 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 user profile and sources it. The name of this file is taken from the environment variable R_PROFILE_USER; if unset, a file called ‘.Rprofile’ in the current directory or in the user’s home directory (in that order) is searched for.
• 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.
‘--encoding=enc ’
Specify the encoding to be assumed for input from the console or stdin. This needs to be an encoding known to iconv: see its help page.
‘RHOME’ Print the path to the R “home directory” to standard output and exit success-fully. 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 or implied by some other option (see below).
‘--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.
‘--no-Rconsole’
(Windows only) Prevent loading the ‘Rconsole’ file at startup.
‘--vanilla’
Combine ‘--no-save’, ‘--no-environ’, ‘--no-site-file’, ‘--no-init-file’ and
‘--no-restore’. Under Windows, this also includes ‘--no-Rconsole’.
‘-f file ’
‘--file=file ’
Take input from file: ‘-’ means stdin. Implies ‘--no-save’ unless ‘--save’ has been set.
‘-e expression ’
Use expression as an input line. One or more ‘-e’ options can be used, but not together with ‘-f’ or ‘--file’. Implies ‘--no-save’ unless ‘--save’ has been set.
(There is a limit of 10,000 bytes on the total length of expressions used in this way.)
‘--no-readline’
(UNIX only) Turn off command-line editing via readline. This is useful when run-ning R from within Emacs using theESS(“Emacs Speaks Statistics”) package. See Appendix C [The command-line editor], page 87, for more information.
‘--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 1.5Gb1 and the amount of physical RAM in the machine, and must be between 32Mb and the maximum allowed on that version of Windows.
‘--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. It implies ‘--quiet’ and ‘--no-save’.
‘--interactive’
(UNIX only) Assert that R really is being run interactively even if input has been redirected: use if input is from a FIFO or pipe and fed from an interactive program.
‘--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. For most debuggers (the exceptions are valgrind and recent versions of gdb), 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 in-teractive graphics). Currently, possible values for type are ‘X11’ (the default), pro-vided that ‘Tcl/Tk’ support is available, ‘Tk’ and ‘gnome’ propro-vided that package gnomeGUI is installed. (For back-compatibility, ‘x11’, ‘tk’ and ‘GNOME’ are ac-cepted.)
‘--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(TRUE).
Note that input and output can be redirected in the usual way (using ‘<’ and ‘>’), but the line length limit of 4095 bytes still applies. Warning and error messages are sent to the error channel (stderr).
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
1 2.5Gb on versions of Windows that support 3Gb per process and have the support enabled: see the ‘rw-FAQ’
Q2.9; 3.5Gb on some 64-bit versions of Windows.
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 (that is, package) 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 Obtain configuration information.
Use
R CMD command --help
to obtain usage information for each of the tools accessible via the R CMD interface.