WINDOWS BATCH FILES FOR R - VERSION 0.2-1

OVERVIEW

Easy Upgrades.
These batch files allow one to configure R on Windows XP
(maybe 2000/NT too but not tested there) so that
one does not have to reinstall and reconfigure libraries, 
*.site files, MiKTeX files and environment variables each 
time one installs a new version of R.  (Note that it
does not move already installed packages.)

Minimal configuration.
They require minimal configuration and, in particular, do
not require that any environment variables be set beyond
those required by any tools themselves (e.g. Perl, MiKTeX).  
However, if the user does want to use these environment 
variables they still can be used as the batch files
never set environment variables that have been set by the
user.  Also they clean up themselves so if they do set an
environment variable they do it only for the period of the
run.

INSTRUCTIONS

Perform the configuration steps described below and then
just run miktex-refresh.bat after each R upgrade (if you use
MiKTeX with R).  The batch files are independent except that 
Rcmd.bat is used by makepkg.bat.

CONFIGURATION

The minimal configuration is the first two steps although it
is recommended that you perform them all.

1. Unzip the batchfiles zip file to an empty directory and copy all .bat
   files there to any directory in your path.  e.g. the path command
   lists the possible places to copy them to and assuming that c:\bin
   is one of them:

	path  
	copy *.bat c:\bin

2. Create a library directory in R.  Assuming the R root directory
   is \Program Files\R (which we can verify by checking the output of 
   Rfind.bat and checking the R_ROOT line):

	Rfind
        cd \Program Files\R
        md library

   (Actually this step is optional too but if you don't do it then
   you won't automatically be able to use previously downloaded 
   packages when you upgrade to a new version.  You will still be
   able to use the capability of Rcmd.bat, Rgui.bat and R.bat to
   automatically detect which is the latest version.)

3. Optional. Copy the *.site files into your R tree and edit them 
   as desired: e.g. run Rfind and look at the R_ROOT line to verify 
   where R is and then copy the .site files there and edit them as 
   desired:

	Rfind
	copy *.site "C:\Program Files\R"

   After that change the default repository in Renviron.site to 
   the closest one.  A list is at: http://cran.r-project.org/mirrors.html
   If you don't do this step you will have to specify your repository
   in the popup window each time you access CRAN.  If that is not
   too onerous for you then skip this step.

4. Optional. Ensure MiKTeX is installed.  A plain vanilla MiKTeX install 
   without changing any MiKTeX configuration files is all that is required.
   MiKTeX is preferred over fptex as latter is missing tools needed to
   process vignettes.  After ensuring that MiKTeX is installed run:  

	miktex-update 

   with no arguments to copy the R MiKTeX files from R to MiKTeX and to
   update the MiKTeX file name data base.   If you don't intend to build
   your own packages then you don't need MiKTeX and can skip this step.

5. Optional.  Create a shortcut on the desktop to Rgui.bat, right 
   click on that desktop icon, choose properties and add a shortcut key 
   Alt+Ctrl+R so that that sequence runs R gui.  This is really 
   convenient but if you can do without a shortcut key you can skip this
   step.

NEW R VERSION

If you do not use MiKTeX there is nothing to do after each
new install of R.

If you use MiKTeX, each time a new version of R is installed run:

  miktex-refresh

with no arguments to copy the MiKTeX files from the new R version
to the appropriate MiKTeX directory and to refresh the MiKTeX
name data base.  Usually these files do not change from one version 
of R to another so if you skip this step on subsequent R upgrades 
it usually does not matter.

SHORT DESCRIPTIONS

Short descriptions for most common case (longer descriptions later):

Rfind.bat - will search system for various tools needed to make R packages.
  It also shows where the current R installation is (R_HOME line).
  It does not actually set or change any environment variables or any 
  other aspect of the system so it is always safe to run.  It takes no 
  arguments.

R.bat, Rcmd.bat, Rgui.bat - These files locate R via the registry
   so that R will still be found even after a new version of R is 
   installed.  These files look for the optional *.site files and 
   the package library in C:\Program Files\R (or wherever R is installed).  
   These files are actually all the same and they query their zeroth
   argument to determine which to run.   

miktex-refresh.bat - this copies the MiKTeX files from the R texmf
  directory to the appropriate MiKTeX directory and refreshes the
  MiKTeX name database.

makepkg.bat - run this as 'makepkg install mypkg' or 'makepkg check mypkg'
  where mypkg is the directory of a package you have created.  It will
  build the package (leaving a .tar.gz file) and then check the package 
  or install the package into ./library (i.e. into the library subdirectory
  of the current directory).  Typically its used like this:

	md \Rpkgs
	cd \Rpkgs
        md mypkg
	... create mypkg in this directory as per Writing Extensions manual

	cd \Rpkgs
	makepkg install mypkg
	... package is now installed in \Rpkgs\library
	rgui
	... in R run this to access the package:
		library(mypkg, lib = "/Rpkgs/library")
	... Once you are sure it runs check it like this:
	makepkg check mypkg

	... after a while you may wish to install it in your
	... permanent library in C:\Program Files\R\library
	... (or wherever R is installed).

	cd \Program Files\R
	makepkg install /Rpkgs/mypkg
	... package is now installed in \Program Files\library
	rgui
	... in R run this to access the package:
		library(mypkg)


LONGER DESCRIPTIONS

R.bat, Rcmd.bat, Rgui.bat - batch files which locate and run R.
  These files are identical.  They query their 0th argument to determine
  what to call.  The main differences are that Rgui.bat spawns Rgui.exe 
  as a separate process whereas the others run R in the same process.  
  Also Rcmd.bat sets R_LIBS if (1) it has not been set and 
  (2) ...\R\library exists.  These commands typically 
  locate R by finding it in the registry and typically set R_ENVIRON and 
  R_PROFILE to find the corresponding *.site files in ...\R.

  In detail, they locate R by 
  1. using the Rrw environment variable if that is defined, otherwise 
  2. they check if the current directory is an rw.... directory and if 
     so use the current directory otherwise 
  3. they check the registry for the most current version of R.

  This means that if you have multiple versions of R installed and want
  to use a non-current one you have three choices:
  1. set the Rrw environment variable to point to the rw... directory
     of the version of R you wish to use, or
  2. cd to the rw... directory of the version of R you wish to use, or
  3. go to the bin directory in the rw... directory of the version of R
     you wish to use and run RSetReg.exe .  Each version of R has 
     such a program.  Its effect is to the set registry to regard that
     version of R as current.

  In detail, if all three of the following are true:
  1. the R_ENVIRON environment variable is not set
  2. ...\R\rw...\etc\Rprofile.site is not present
  3. ...\R\Renviron.site file is present
  then the R_ENVIRON variable is set to ...\R\Renviron.site and the
  same algorithm is used to possibly set the R_PROFILE variable in the 
  same way.

Rrefresh.bat - DEPRECATED.  This copies the *.site files to the appropriate 
  place in the most current R version installed and the miktex files
  from that R version to the appropriate miktex folder.  No arguments
  are required.  It is normally run each time one installs a new version
  of R or modifies any of the *.site files.  Use the --no-miktex argument
  if MiKTeX was not installed; otherwise, use no arguments.  If 
  you would like each installed version of R to have its own
  *.site files then run this each time you install R and each
  time you update any of the *.site files.  Note that
  Rrefresh calls Rcmd.bat.


makepkg.bat - called like this:
   makepkg install mypkg
   makepkg check mypkg
  No other arguments are accepted.
  This command is similar to Rcmd install or Rcmd check except that
  it first builds the package, which is necessary if one is using the R
  .Rbuildignore  facility.  Also it calls Rcmd.bat which in turn will
  set R_LIBS if its not already set and if ...\R\library exists.  Note that 
  certain flags are set near the top.  This file can be manually editted 
  to change those as it does not itself take any flags.  If used with a 
  second argument of install it will install the package in the library 
  subfolder of the current folder, i.e. in .\library .  


ADDITIONAL INFORMATION

Additional information on writing Windows XP batch files is
in RESOURCES.  Information on COPYING and COPYRIGHT is in
the COPYING and COPYRIGHT files.  Acknowledgements are in
the THANKS file.  Changes to the batchfiles are recorded
in the NEWS file.

Gabor Grothendieck
ggrothendieck@gmail.com

