\section{Windows Batch Files for R} G. Grothendieck Software and documentation is (c) 2013 GKX Associates Inc. and licensed under \href{http://www.gnu.org/licenses/gpl-2.0.html}{GPL 2.0}. \subsection{Introduction} This document describes a number of Windows batch, javascript and \texttt{.hta} files that may be used in conjunction with R. Each is self contained and independent of the others. Each requires no installation - just place it on the Windows path\footnote{To display the Windows path enter \texttt{path} at the Windows \texttt{cmd} line.}. \texttt{R.bat} and \texttt{Rpathset.bat} are alternatives to each other intended to facilitate the use of R without having to permanently modify the Windows system PATH or otherwise use the Windows control panel. \texttt{R.bat} uses heuristics to automatically locate \texttt{R}, \texttt{MiKTeX} and \texttt{Rtools} while \texttt{Rpathset.bat} takes a simpler approach of having the user manually edit the \texttt{set} statements in it to configure it. \texttt{R.bat} does not require changes when you install a new version of R but \texttt{Rpathset.bat} does. \texttt{R.bat help} gives a quick overview of that batch file. \texttt{movedir.bat} and \texttt{copydir.bat} are used for moving or copying packages from one library to another. \texttt{el.js} runs its arguments in elevated mode (i.e.~with Administrator privileges). \texttt{clip2r.js} copies the current clipboard into a running R instance. It can be used with vim or other text editor. \texttt{find-miktex.hta} displays a popup window showing where it found MiKTeX. \subsection{R.bat} \subsubsection{Purpose} The purpose of R.bat is to facilitiate the use of R from the Windows \texttt{cmd} line by eliminating the need to make any systems changes. There is no need to modify the Windows PATH or to set any environment variables for standard configurations of R. It will automatically locate R (and Rtools and MiKTeX if installed) and then run \texttt{R.exe}, \texttt{Rgui.exe} or other command. It is a self contained no-install script with no dependencies so just place it anywhere on your Windows path. \subsubsection{Typical Usage} Typical usage to launch R gui is the following: \begin{verbatim} R.bat gui \end{verbatim} If R.exe is not on the Windows path or is after R.bat on the path then the above can be shortened to: \begin{verbatim} R gui \end{verbatim} Either of these commands runs \texttt{Rgui.exe} along with further arguments, if any. For example, \begin{verbatim} R.bat gui --help \end{verbatim} will run: \begin{verbatim} Rgui.exe --help \end{verbatim} \subsubsection{Other R Executables} Other executable files that come with R (\texttt{R.exe}, \texttt{Rcmd.exe}, \texttt{Rscript.exe}) can be run in a similar way: \begin{verbatim} R.bat --help R.bat cmd --help R.bat script --help \end{verbatim} (\texttt{RSetReg.exe} is another executable that comes with R for Windows. It will be discussed later.) \subsubsection{Support Subcommands} There are also some support commands: \begin{verbatim} R.bat cd R.bat dir R.bat help R.bat show \end{verbatim} \texttt{R.bat cd} changes to the \texttt{R\_ROOT} directory (typically \texttt{C:\textbackslash{}\textbackslash{}Program Files\textbackslash{}\textbackslash{}R}). \texttt{R.bat dir} displays the contents of that directory. \texttt{R.bat show} shows the values of the \texttt{R\_} environment that \texttt{R.bat} uses. Here is a list with typical values. These values are determined by the script heuristically (or the user can set any before running \texttt{R.bat} or by customizing \texttt{R.bat} itself by setting any of them near top of the script). \begin{verbatim} R_ARCH=x64 R_CMD=RShow R_HOME=C:\\Program Files\\R\\R-2.15.2 R_MIKTEX_PATH=\\Program Files (x86)\\MiKTeX 2.9\\miktex\\bin R_PATH=C:\\Program Files\\R\\R-2.15.2\\bin\\x64 R_REGISTRY=1 R_ROOT=C:\\Program Files\\R R_TOOLS=C:\\Rtools R_TOOLS_PATH=C:\\Rtools\\bin;C:\\Rtools\\gcc-4.6.3\\bin; R_TOOLS_VERSION=3.0.0.1927 R_VER=R-2.15.2 \end{verbatim} \texttt{R\_PATH}, \texttt{R\_MIKTEX\_PATH} and \texttt{R\_TOOLS\_PATH} are the paths to the directories holding the \texttt{R}, \texttt{MiKTeX} and \texttt{Rtools} binaries. \texttt{R\_CMD} indicates the subcommand or if no subcommand specified then is derived from the name of the script. For example if the script were renamed \texttt{Rgui.bat} then if no subcommand were specified it would default to \texttt{gui}. \texttt{R\_ROOT} is the directory holding all the R installations. \texttt{R\_HOME} is the directory of the particular R installation. \texttt{R\_HOME} is made up of \texttt{R\_ROOT} and \texttt{R\_VER} so that \texttt{R\_VER} represents the directory that holds the particular R version used. \texttt{R\_ARCH} is \texttt{i386} or \texttt{x64} for 32 bit or 64 bit R respectively. It can also be specified as \texttt{32} or \texttt{64} in which case it will be translated automatically. \subsubsection{Path Setting Subcommands} The command \begin{verbatim} R.bat path \end{verbatim} adds \texttt{R\_PATH}, \texttt{R\_MIKTEX\_PATH} and \texttt{R\_TOOLS} to the Windows path for the current \texttt{cmd} line session. No other \texttt{cmd} line sessions are affected and there are no permanent changes to the system. Once this is run one no longer needs R.bat in the current session as the R binaries such as \texttt{R.exe}, \texttt{Rgui.exe} will be directly on the path. (An alternative to this is the \texttt{Rpathset.bat} utility which will be desribed later.) \begin{verbatim} R.bat tools \end{verbatim} is similar except only \texttt{R\_TOOLS\_PATH} and \texttt{R\_MIKTEX\_PATH} are added to the path. This might be useful if you need to use those utilities without R. \subsubsection{Selecting R Version} For R installations using the standard locations and not specifying any of the R\_ environment variables the registry will determine which version of R is used (assuming \texttt{R\_REGISTRY} is not 0). If R is not found in the registry the R installation in \texttt{R\_ROOT} which has the most recent date will be used. We can change which version of R is used like this: \begin{verbatim} set R_VER=R-2.14.0 \end{verbatim} and now for the remainder of this \texttt{cmd} line session that version will be used. If one wants to use two different R versions at once we could spawn a new \texttt{cmd} line session with the new version: \begin{verbatim} start \end{verbatim} and then enter the same set command into the new window. Now any use of R in the original window will use the default version and in the new version will use the specified version. One can change the registry entry permanently to refer to a particlar version like this: \begin{verbatim} cmd /c set R_VER=R-2.14.0 ^& R.bat SetReg \end{verbatim} This requires Administrator privileges so a window will pop up requesting permission to proceed. If the registry is empty or \texttt{R\_REGISTRY=0} then the default version is determined by which R install directory is the most recent. To make a particular R install directory the most recent run the following in a \texttt{cmd} line session with Administrator privileges: \begin{verbatim} cmd /c set R_VER=R-2.14.0 ^& R.bat touch \end{verbatim} The \texttt{el.js} command that comes with the batch utilities is one way to elevate the command to run with such privileges: \begin{verbatim} el cmd /c set R_VER=R-2.14.0 ^& R.bat touch \end{verbatim} Note that \texttt{R.bat SetReg} and \texttt{R.bat touch} make permanent changes to the system (namely installing or uninstalling the R key and updating the date on a particular R directory) but the other subcommands do not. \subsubsection{Heuristic to Locate R} \begin{enumerate} \def\labelenumi{\arabic{enumi}.} \item If \texttt{.\textbackslash{}\textbackslash{}R.exe} exists use implied \texttt{R\_PATH} and skip remaining points. \item If \texttt{.\textbackslash{}\textbackslash{}\{x64,i386\}\textbackslash{}\textbackslash{}R.exe} or \texttt{.\textbackslash{}\textbackslash{}bin\textbackslash{}\textbackslash{}\{x64,i386\}\textbackslash{}\textbackslash{}R.exe} exists use implied \texttt{R\_HOME}. \item If \texttt{R\_HOME} defined then derive any of \texttt{R\_ROOT} and \texttt{R\_VER} that are not already defined. \item If \texttt{R\_PATH} defined then derive any of \texttt{R\_ROOT}, \texttt{R\_HOME}, \texttt{R\_VER} and \texttt{R\_ARCH} that are not already defined. \item If \texttt{R\_REGISTRY=1} and R found in registry derive any of \texttt{R\_HOME}, \texttt{R\_ROOT} and \texttt{R\_VER} that are not already defined. \item If R\_ROOT not defined try \texttt{\%ProgramFiles\%\textbackslash{}\textbackslash{}R\textbackslash{}\textbackslash{}*}, \texttt{\%ProgramFiles(x86)\%\textbackslash{}\textbackslash{}R\textbackslash{}\textbackslash{}*} and then \texttt{\%SystemRoot\%\textbackslash{}\textbackslash{}R} else error. \item If \texttt{R\_VER} not defined use last directory in \texttt{cd \%R\_ROOT\% \& dir /od}. \item if \texttt{R\_ARCH} not defined try \texttt{\%R\_ROOT\%\textbackslash{}\textbackslash{}\%}R\_VER\texttt{\%\textbackslash{}\textbackslash{}bin\textbackslash{}\textbackslash{}x64\textbackslash{}\textbackslash{}R.exe} and then \texttt{\%R\_ROOT\%\textbackslash{}\textbackslash{}\%}R\_VER\texttt{\%\textbackslash{}\textbackslash{}bin\textbackslash{}\textbackslash{}i386\textbackslash{}\textbackslash{}R.exe} \item If \texttt{R\_ROOT}, \texttt{R\_VER} and \texttt{R\_ARCH} defined skip remaining points. \item If \texttt{R.exe} found on \texttt{PATH} use implied \texttt{R\_PATH}. \end{enumerate} \subsection{Rpathset.bat} An alternative to \begin{verbatim} R.bat path \end{verbatim} is the \texttt{Rpathset.bat}. Unlike \texttt{R.bat}, \texttt{Rpathset.bat} is not automatic but requires that the user modify the various set commands in it. Running \texttt{Rpathset.bat} then sets the path accordingly and from then on in the session one can access Rgui.exe, etc. on the path. Although \texttt{Rpathset.bat} involves manual editing it does have the advantage that as a consequence it is very simple -- not much more than a collection of Windows batch set commands. The set statements are documented in the source of the file itself. \subsection{movedir.bat and copydir.bat} \texttt{movedir.bat} and \texttt{copydir.bat} move or copy the packages from one library to another. If used to transfer packages from one version of R to another it is recommended that the user run \texttt{upgrade.packages()} in the target. For example, assuming the default location for the user libraries: \begin{verbatim} cd %userprofile%\\Documents\\win-library copydir 2.15\\library 3.0\\library R.bat gui ... now enter update.packages() into R... \end{verbatim} \subsection{el.js} \texttt{el.js} runs its arguments elevated (i.e.~with Adminstrator privileges). \subsection{clip2r.js} This program writes the clipboard into the running R session. It can be used with vim or other editor. See the source for additional instructions. \subsection{find-mixtex.hta} This program displays a window showing where MiKTeX was found. It uses the MiKTeX API. This API is not used by \texttt{R.bat} . It may be incorporated into \texttt{R.bat} in the future.