1% File src/library/utils/man/Rscript.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2017 R Core Team
4% Distributed under GPL 2 or later
5
6\name{Rscript}
7\alias{Rscript}
8\title{Scripting Front-End for R}
9\description{
10  This is an alternative front end for use in \samp{#!} scripts and
11  other scripting applications.
12}
13\usage{
14\special{Rscript [options] [-e expr [-e expr2 ...] | file] [args]}
15}
16\arguments{
17  \item{options}{a list of options, all beginning with \samp{--}.  These
18    can be any of the options of the standard \R front-end, and also those
19    described in the details.}
20  \item{expr, expr2}{\R expression(s), properly quoted.}
21  \item{file}{the name of a file containing \R commands.  \samp{-}
22    indicates \file{stdin}.}
23  \item{args}{arguments to be passed to the script in \code{file}.}
24}
25\details{
26  \command{Rscript --help} gives details of usage, and
27  \command{Rscript --version} gives the version of \command{Rscript}.
28
29  Other invocations invoke the \R front-end with selected options.  This
30  front-end is convenient for writing \samp{#!} scripts since it is an
31  executable and takes \code{file} directly as an argument.  Options
32  \option{--no-echo --no-restore} are always supplied: these imply
33  \option{--no-save}. Arguments that contain spaces cannot be specified
34  directly on the \samp{#!} line, because spaces and tabs are interpreted as
35  delimiters and there is no way to protect them from this interpretation on
36  the \samp{#!} line. (The standard Windows command line has no concept
37  of \samp{#!} scripts, but Cygwin shells do.)
38
39  \emph{Either} one or more \option{-e} options or \code{file} should
40  be supplied.  When using \option{-e} options be aware of the quoting
41  rules in the shell used: see the examples.
42
43  Additional options accepted (before \code{file} or \code{args}) are
44  \describe{
45    \item{\option{--verbose}}{gives details of what \command{Rscript} is
46      doing.  Also passed on to \R.}
47    \item{\option{--default-packages=list}}{where \code{list} is a
48      comma-separated list of package names or \code{NULL}.  Sets the
49      environment variable \env{R_DEFAULT_PACKAGES} which determines the
50      packages loaded on startup.
51    }
52  }
53
54  Spaces are allowed in \code{expression} and \code{file} (but will need
55  to be protected from the shell in use, if any, for example by
56  enclosing the argument in quotes).
57
58  If \option{--default-packages} is not used, then \command{Rscript}
59  checks the environment variable \env{R_SCRIPT_DEFAULT_PACKAGES}. If
60  this is set, then it takes precedence over \env{R_DEFAULT_PACKAGES}.
61
62#ifdef unix
63  Normally the version of \R is determined at installation, but this can
64  be overridden by setting the environment variable \env{RHOME}.
65#endif
66#ifdef windows
67  The \R files are found from the location of the \file{Rscript.exe}
68  executable.   If this is copied elsewhere, the environment variable
69  \env{RHOME} should be set to the top directory of the \R installation.
70
71  Unlike Unix-alikes, this links directly to \file{R.dll} rather than
72  running a separate process.
73#endif
74
75  \code{\link{stdin}()} refers to the input file, and
76  \code{\link{file}("stdin")} to the \code{stdin} file stream of the
77  process.
78}
79#ifdef unix
80\note{
81  \command{Rscript} is only supported on systems with the \code{execv}
82  system call.
83}
84#endif
85\examples{\dontrun{
86#ifdef unix
87Rscript -e 'date()' -e 'format(Sys.time(), "\%a \%b \%d \%X \%Y")'
88#endif
89#ifdef windows
90# Note that Rscript is not by default in the PATH on Windows, so
91# either put it there or use an explicit path to Rscript.
92
93# at the standard Windows command line
94Rscript -e "date()" -e "format(Sys.time(), \\"\%a \%b \%d \%X \%Y\\")"
95# in other shells, e.g. bash or tcsh, prefer
96Rscript -e 'date()' -e 'format(Sys.time(), "\%a \%b \%d \%X \%Y")'
97#endif
98
99# Get the same initial packages in the same order as default R:
100Rscript --default-packages=methods,datasets,utils,grDevices,graphics,stats -e 'sessionInfo()'
101
102## example #! script for a Unix-alike
103
104#! /path/to/Rscript --vanilla --default-packages=utils
105args <- commandArgs(TRUE)
106res <- try(install.packages(args))
107if(inherits(res, "try-error")) q(status=1) else q()
108
109}}
110\keyword{utilities}
111