← Back to branch summary

~ubuntu-branches/ubuntu/vivid/grass/vivid-proposed

« back to all changes in this revision

Viewing changes to mswindows/external/rbatch/batchfiles.md

  • Committer: Package Import Robot
  • Author(s): Bas Couwenberg
  • Date: 2015-02-20 23:12:08 UTC
  • mfrom: (8.2.6 experimental)
  • Revision ID: package-import@ubuntu.com-20150220231208-1u6qvqm84v430b10
Tags: 7.0.0-1~exp1
* New upstream release.
* Update python-ctypes-ternary.patch to use if/else instead of and/or.
* Drop check4dev patch, rely on upstream check.
* Add build dependency on libpq-dev to grass-dev for libpq-fe.h.
* Drop patches applied upstream, refresh remaining patches.
* Update symlinks for images switched from jpg to png.

Show diffs side-by-side

added added

removed removed

Lines of Context:
mswindows/external/rbatch/batchfiles.md
 
1
# Windows Batch Files for R #
 
2
 
 
3
G. Grothendieck
 
4
 
 
5
Software and documentation is (c) 2013 GKX Associates Inc. and licensed under [GPL 2.0](http://www.gnu.org/licenses/gpl-2.0.html).
 
6
 
 
7
## Introduction ##
 
8
 
 
9
This document describes a number of Windows batch, javascript and `.hta` files
 
10
that may be used in conjunction with R.  Each is self contained and independent
 
11
of the others.  None requires installation - just place on the Windows path or
 
12
in current directory.  ^[To display the Windows path enter `path` without
 
13
arguments at the Windows `cmd` line.  To display the path to the current
 
14
directory enter `cd` without arguments at the Windows `cmd` line.]
 
15
 
 
16
`R.bat` and `Rpathset.bat` are alternatives to each other intended to
 
17
facilitate the use of R without permanently modifying the Windows
 
18
configuration.   They can also be useful on systems with
 
19
restricted access to the registry.
 
20
`R.bat` uses heuristics to automatically locate `R`, `MiKTeX` and `Rtools`.  In
 
21
contrast, `Rpathset.bat` takes a simpler approach of having the user manually
 
22
edit the `set` statements in it.  `R.bat` does not require changes when you
 
23
install a new version of R.  It will automatically detect this; however,
 
24
`Rpathset.bat` will require that the `set` statements be modified
 
25
appropriately.  `R.bat help` gives a quick overview and some examples.  Another
 
26
way to use `R.bat` is to copy it to `#Rscript.bat` in which case a call to
 
27
the new
 
28
version can be placed in the first line of any R script to turn it into a
 
29
Windows batch file (as described later).
 
30
 
 
31
`movedir.bat` and `copydir.bat` are used for moving or copying packages from
 
32
one library to another such as when R is upgraded to a new version.
 
33
 
 
34
`el.js` runs its arguments in elevated mode (i.e. with Administrator
 
35
privileges).
 
36
 
 
37
`clip2r.js` copies the current clipboard into a running R instance. It can be
 
38
used with `vim` or other text editor.
 
39
 
 
40
`find-miktex.hta` displays a popup window showing where it found MiKTeX. 
 
41
 
 
42
## R.bat ##
 
43
 
 
44
### Purpose ###
 
45
 
 
46
The purpose of `R.bat` is to facilitiate the use of R from the Windows `cmd` 
 
47
line by eliminating the need to make any system changes.  There is no need to
 
48
modify the Windows path or to set any environment variables for standard
 
49
configurations of R.  It will automatically locate R (and Rtools and
 
50
MiKTeX if installed) and then run `R.exe`, `Rgui.exe` or other command.
 
51
 
 
52
Another scenario for which it is useful is when there are only restricted
 
53
permissions available such as no ability to write to the registry.
 
54
Windows supports 4 sets of environment variables (system, user, volatile,
 
55
process) and the first three are stored in the registry but the last
 
56
is stored only in the local process.
 
57
`R.bat` can work with process environment variables so it can be used in
 
58
such situations where there are minimal permissions.
 
59
 
 
60
Like all the other utilities here, `R.bat` is a self contained no-install script
 
61
with no dependencies so just place it anywhere on your Windows path or in the 
 
62
current directory.
 
63
 
 
64
### Typical Usage ###
 
65
 
 
66
Typical usage of `R.bat` to launch R gui is the following ^[
 
67
If `R.exe` were on the Windows path and before `R.bat` then it would
 
68
have to be written as follows: `R.bat gui`]:
 
69
 
 
70
        R gui
 
71
 
 
72
 
 
73
This runs `Rgui.exe`.  If further arguments are specified they are passed on to
 
74
`Rgui.exe`.  For example,
 
75
 
 
76
        R gui --help
 
77
 
 
78
will run: 
 
79
 
 
80
        Rgui.exe --help
 
81
 
 
82
### Subcommands ###
 
83
 
 
84
If the first argument is optionally one of `cd`, `cmd`, `dir`, `gui`, `help`,
 
85
`path`, `R`, `script`, `show`, `SetReg`, `tools`, `touch` or the same except
 
86
for upper/lower case then that argument is referred to as the subcommand.  
 
87
 
 
88
If no subcommand is provided then the default subcommand is derived from the
 
89
name of the script.
 
90
 
 
91
If the script is named `R.bat` then the subcommand `R` is implied.  If the
 
92
script has been renamed then any leading `R` is removed from the name and the
 
93
remainder becomes the default subcommand.  For example, if `R.bat` were renamed
 
94
`Rgui.bat` then issuing `Rgui` would be the same as running `R gui` .
 
95
 
 
96
### Other R Executables ###
 
97
 
 
98
Other executable files that come with R (`R.exe`, `Rcmd.exe`, `Rscript.exe`)
 
99
can be run in a similar way:
 
100
 
 
101
        R --help
 
102
        R cmd --help
 
103
        R script --help
 
104
 
 
105
(`RSetReg.exe` is another executable that comes with R for Windows. It will be 
 
106
discussed later.)
 
107
 
 
108
### Support Subcommands ###
 
109
 
 
110
There are also some support commands:
 
111
 
 
112
        R cd
 
113
        R dir
 
114
        R ls
 
115
        R help
 
116
        R show
 
117
 
 
118
`R cd` changes directory to the `R_ROOT` directory (typically 
 
119
`C:\Program Files\R`).
 
120
 
 
121
`R dir` displays the contents of that directory in chronological order - oldest
 
122
first and most recent last.  `R ls` is the same as `R dir`.
 
123
 
 
124
`R show` shows the values of the `R_` environment variables used by `R.bat` .
 
125
Below is a list with typical values.  These values are determined by the script
 
126
heuristically (or the user can set any before running `R.bat` or 
 
127
`R.bat` itself can be customized by setting any of them near top of the script).
 
128
 
 
129
        R_ARCH=x64
 
130
        R_CMD=RShow
 
131
        R_HOME=C:\Program Files\R\R-2.15.3
 
132
        R_MIKTEX_PATH=\Program Files (x86)\MiKTeX 2.9\miktex\bin
 
133
        R_PATH=C:\Program Files\R\R-2.15.3\bin\x64
 
134
        R_REGISTRY=1
 
135
        R_ROOT=C:\Program Files\R
 
136
        R_TOOLS=C:\Rtools
 
137
        R_TOOLS_PATH=C:\Rtools\bin;C:\Rtools\gcc-4.6.3\bin;
 
138
        R_TOOLS_VERSION=3.0.0.1927
 
139
        R_VER=R-2.15.3
 
140
 
 
141
`R_PATH`, `R_MIKTEX_PATH` and `R_TOOLS_PATH` are the paths to the directories
 
142
holding the `R`, `MiKTeX` and `Rtools` binaries (i.e. `.exe` files).  
 
143
 
 
144
`R_CMD` indicates the subcommand or if no subcommand specified then it is
 
145
derived from the name of the script.  For example if the script were renamed
 
146
`Rgui.bat` then if no subcommand were specified it would default to `gui`.
 
147
 
 
148
`R_ROOT` is the directory holding all the R installations. `R_HOME` is the
 
149
directory of the particular R installation.  `R_HOME` is made up of `R_ROOT`
 
150
and `R_VER` so that `R_VER` represents the directory that holds the particular
 
151
R version used.  `R_ARCH` is `i386` or `x64` for 32 bit or 64 bit R
 
152
respectively.  It can also be specified as `32` or `64` in which case it will
 
153
be translated automatically.  See the `R show` output above for examples of
 
154
values for these variables.
 
155
 
 
156
### Path Setting Subcommands ###
 
157
 
 
158
The command 
 
159
 
 
160
        R path
 
161
 
 
162
adds `R_PATH`, `R_MIKTEX_PATH` and `R_TOOLS` to the Windows path for the
 
163
current `cmd` line session.  No other `cmd` line sessions are affected and
 
164
there are no permanent changes to the system.  Once this is run 
 
165
the R binaries will be on the path so they can be accessed directly without
 
166
`R.bat` within the same Windows cmd line session.
 
167
 
 
168
This mode of operation has the advantage that startup will be slightly faster
 
169
since  `R.bat` will not have to run each time that `R` is started. ^[On a 
 
170
1.9 GHz Windows 8 machine `R.bat show` runs in 0.75 seconds.]
 
171
 
 
172
Note that if both `R.bat` and `R.exe` exist on the Windows path then the first
 
173
on the path will be called if one uses:
 
174
 
 
175
        R ...arguments...
 
176
 
 
177
thus one may wish to enter `R.bat` or `R.exe` rather than just `R` for clarity. 
 
178
 
 
179
Alternately, rename `R.bat` to `Rpath.bat` in which case the command `R path`
 
180
becomes just `Rpath` and `R` becomes unambiguous.
 
181
 
 
182
(An alternative to `R path` is the `Rpathset.bat` utility which will be 
 
183
described later.)
 
184
 
 
185
The command
 
186
 
 
187
        R tools
 
188
 
 
189
is similar to `R path` except only `R_TOOLS_PATH` and `R_MIKTEX_PATH` are
 
190
added to the path (but not `R_PATH`).  This might be useful if you need to use
 
191
those utilities without R.
 
192
 
 
193
 
 
194
### Selecting R Version ###
 
195
 
 
196
For R installations using the standard locations and not specifying any of the
 
197
R_ environment variables the registry will determine which version of R is used
 
198
(assuming `R_REGISTRY` is not `0`).  If R is not found in the registry or if
 
199
`R_REGISTRY` is `0` then the R
 
200
installation in `R_ROOT` which has the most recent date will be used.
 
201
 
 
202
If we enter this at the `cmd` line:
 
203
 
 
204
        set R_VER=R-2.14.0
 
205
 
 
206
then for the remainder of this `cmd` line session that version will be used.
 
207
If one wishes to use two different R versions at once we could spawn a new `cmd`
 
208
line session:
 
209
 
 
210
        start
 
211
 
 
212
and then enter the same set command into the new window.  Now any use of R in
 
213
the original window will use the default version whereas in the new `cmd` line
 
214
window it will use the specified version.
 
215
 
 
216
One can change the registry entry permanently to refer to a particlar version
 
217
like this:
 
218
 
 
219
        cmd /c set R_VER=R-2.14.0 ^& R SetReg
 
220
 
 
221
This requires Administrator privileges. If not already running as 
 
222
Administrator a window will pop up requesting permission to proceed.
 
223
 
 
224
If the registry is empty or `R_REGISTRY=0` then the default version is not
 
225
determined by the registry but is
 
226
determined by which R install directory is the most recent.  To make a
 
227
particular R install directory the most recent run the following in a `cmd`
 
228
line session with Administrator privileges:
 
229
 
 
230
        R dir
 
231
        el cmd /c set R_VER=R-2.14.0 ^& R touch
 
232
 
 
233
The value of `R_VER` in the above line must be one of the directories listed 
 
234
by `R dir`.  The `el.js` command used in the above code comes with these batch 
 
235
files and provides one way to elevate commands to have Administrator 
 
236
privileges.
 
237
 
 
238
Note that `R SetReg` and `R touch` make permanent changes to the system
 
239
(namely installing or uninstalling the R key and updating the date on a
 
240
particular R directory, respectively) but the other subcommands make no
 
241
permanent changes.
 
242
 
 
243
### Heuristic to Locate R ###
 
244
 
 
245
1. If `.\Rgui.exe` exists use implied `R_PATH` and skip remaining points.
 
246
 
 
247
2. If `.\{x64,i386}\Rgui.exe` or `.\bin\{x64,i386}\Rgui.exe` exists use implied
 
248
`R_HOME`.
 
249
 
 
250
3. If `R_HOME` defined then derive any of `R_ROOT` and `R_VER` that are not
 
251
already defined.
 
252
 
 
253
4. If `R_PATH` defined then derive any of `R_ROOT`, `R_HOME`, `R_VER` and 
 
254
`R_ARCH` that are not already defined.
 
255
 
 
256
5. If `R_REGISTRY=1` and R found in registry derive any of `R_HOME`, `R_ROOT` 
 
257
and `R_VER` that are not already defined.
 
258
 
 
259
6. If R_ROOT not defined try `%ProgramFiles%\R\*`, `%ProgramFiles(x86)%\R\*`
 
260
    and then `%SystemRoot%\R` else error.
 
261
 
 
262
7. If `R_VER` not defined use last directory in `cd %R_ROOT% & dir /od`.
 
263
 
 
264
8. if `R_ARCH` not defined try `%R_ROOT%\%R_VER%\bin\x64\Rgui.exe` and then
 
265
    `%R_ROOT%\%R_VER%\bin\i386\Rgui.exe`
 
266
 
 
267
9. If `R_ROOT`, `R_VER` and `R_ARCH` defined skip remaining points.
 
268
 
 
269
10. If `Rgui.exe` found on `PATH` use implied `R_PATH`.
 
270
 
 
271
## #Rscript.bat ##
 
272
 
 
273
This is not a separate batch file but is yet another way to call `R.bat`.  
 
274
Its purpose is to turn an R script into a Windows batch file.  
 
275
 
 
276
1.  Copy `R.bat` to a file with the name `#Rscript.bat` like this 
 
277
(from the Windows cmd line):
 
278
 
 
279
        copy R.bat #Rscript.bat
 
280
 
 
281
2. Ensure that `#Rscript.bat` is on your windows path.  Then we can turn an
 
282
R script into a `.bat` file by 
 
283
(a) giving the R script a `.bat` extension and 
 
284
(b) putting this line as the 
 
285
first line in the script: `#Rscript %0 %*`
 
286
 
 
287
This makes the script both a Windows batch file and an R script at the same
 
288
time. When run as a batch file it will invoke `#Rscript.bat` which in turn
 
289
will self call the script as an R script.  (It would also be possible to
 
290
run the script directly as an R script.  In that case the #Rscript line would
 
291
be ignored since it would be regarded as a comment by R.)
 
292
 
 
293
For example, if we have a file `test.bat` with the following two lines:
 
294
 
 
295
        #Rscript %0 %*
 
296
        print(pi)
 
297
 
 
298
then we can invoke it from the Windows cmd line like this:
 
299
 
 
300
        test
 
301
 
 
302
## #Rscript2.bat ##
 
303
 
 
304
This batch file is used in exactly the same manner as #Rscript.bat .  The only
 
305
difference is that unlike #Rscript.bat which automatically finds R with this
 
306
script the user must edit it to indicate where R is located.  Although this
 
307
involves an extra installation step in return the script is very simple so
 
308
its less likely to go wrong and if something does go wrong then its relatively
 
309
simple to fix since the script itself is simple.
 
310
 
 
311
If you have a 64 bit system then the only part that needs to be changed is
 
312
changing the definition of R_HOME to point to your version of R.  If you
 
313
have a 32 bit system then you will also have to modify the definition of
 
314
R_ARCH on the appropriate line.  
 
315
 
 
316
There is more information on this in the comments at the top of the script.
 
317
 
 
318
## Rpathset.bat ##
 
319
 
 
320
The command 
 
321
 
 
322
        Rpathset
 
323
 
 
324
adds `R_PATH`, `R_MIKTEX_PATH` and `R_TOOLS` to the Windows path for the
 
325
current `cmd` line session.  No other `cmd` line sessions are affected and
 
326
there are no permanent changes to the system.  Once this is run 
 
327
the R binaries will be on the path so they can be accessed directly without
 
328
`R.bat` .   
 
329
 
 
330
`Rpathset` is an alternative to 
 
331
 
 
332
        R path 
 
333
 
 
334
but unlike `R.bat`, `Rpathset.bat` does not have any automatic heuristics.
 
335
Instead, it requires that the user manually set the relevant variables in its
 
336
source.  Running `Rpathset.bat` then sets the path accordingly and from then on
 
337
in the session one can access `Rgui.exe`, etc. on the path.  Although
 
338
`Rpathset.bat` involves manual editing it does have the advantage that as a
 
339
consequence it is very simple -- not much more than a collection of Windows
 
340
batch set commands. This makes it easy to customize, less fragile to 
 
341
changes in the install procedures of `R` itself and is also more liklely to
 
342
work on untested Windows configurations.
 
343
 
 
344
`Rpathset.bat` might be used like this:
 
345
 
 
346
        Rpathset
 
347
        Rgui
 
348
 
 
349
where `Rgui` is now directly accessing `Rgui.exe` as `Rpathset.bat` has added
 
350
`R_PATH` to the Windows path.
 
351
 
 
352
The set statements are documented in the source of the `Rpathset.bat` file 
 
353
itself.
 
354
 
 
355
## movedir.bat and copydir.bat ##
 
356
 
 
357
`movedir.bat` and `copydir.bat` move or copy the packages from one library to
 
358
another.  If used to transfer packages from one version of R to another it is
 
359
recommended that the user run `upgrade.packages()` in the target.  For example,
 
360
assuming the default location for the user libraries:
 
361
 
 
362
        cd %userprofile%\Documents\win-library
 
363
        copydir 2.15\library 3.0\library
 
364
 
 
365
        R.bat gui 
 
366
        ... now enter update.packages(checkBuilt=TRUE) into R...
 
367
 
 
368
(The `checkBuilt=TRUE` argument forces a rebuild and is normally not required
 
369
when upgrading to another version that differs only in the minor version
 
370
number, e.g. from 2.15.2 to 2.15.3.)
 
371
 
 
372
`movedir.bat` and `copydir.bat` will not overwrite any existing package in the 
 
373
target library so they are particularly safe to use.  (If you do wish to 
 
374
overwrite such packages delete them from the target first using the Windows
 
375
`del` command.)
 
376
 
 
377
 
 
378
## el.js ##
 
379
 
 
380
`el.js` runs its arguments elevated (i.e. with Adminstrator privileges).  For example,
 
381
 
 
382
        el R touch
 
383
 
 
384
The user will be prompted to allow elevation to proceed.
 
385
 
 
386
## clip2r.js ##
 
387
 
 
388
This program writes the clipboard into the running R session.  It can be used
 
389
with `vim` or other editor.  See the source for additional instructions.
 
390
 
 
391
## find-mixtex.hta ##
 
392
 
 
393
This program displays a window showing where MiKTeX was found. It uses the
 
394
MiKTeX API. This API is not used by `R.bat` .  Instead `R.bat` just looks in
 
395
common places.  (Using this API may be incorporated into the `R.bat` heuristic 
 
396
in the future.)
 
397
 
 
398
## make-batchfiles-pdf.bat ##
 
399
 
 
400
This batch file creates a pdf of this documentation from the markdown file
 
401
`batchfiles.md` .  `pandoc` must be installed for this to run.  `pandoc` can be
 
402
found [here](https://code.google.com/p/pandoc/downloads/list).  It is run
 
403
without arguments:
 
404
 
 
405
        make-batchfiles-pdf
 
406