R 0.65.1 for Windows 9x and NT
==============================

This distribution contains a binary distribution of R-0.65.1 to run on
Windows 95, 98 and NT4 on Intel/clone chips. It is designed to
be as close as possible to the implementation on Unix, but see the
list of differences below. The port was by Guido Masarotto with
many important contributions by Brian Ripley.

See Announce or CHANGES for the new features of this version.


Installation
============

The simplest way is to run the installer (double-click on the icon for
rwinst.exe and navigate its wizard-like pages).

To install manually, unpack rw0651b.zip anywhere you like. It will
unpack to a directory tree under rw0651. The help, HTML, Compiled
HTML, Windows and latex help files are in separate files rw0651h.zip,
rw0651w.zip, rw0651ch.zip, rw0651wh.zip and rw0651l.zip which should
be unpacked in the same directory in which you unpacked rw0651b.zip.

Usage
=====

There are two executables in rw0651\bin:

GUI:

Rgui.exe runs as a standard Windows GUI executable and provides an R
console in its own window. It takes the standard R command-line
arguments; these are most easily set by making a shortcut to
...\rw0651\bin\rgui.exe and adding the arguments in the Target field.
Set the `Start in' field of the shortcut to the directory you want to use
as the working directory (where workspaces and files are saved and
loaded from).

Command-line editing is available: see Help | Console for details.

The menus provide shortcuts to some R commands such as help, help.start,
apropos, ls, load, save.image, search.

The `load' menu items (Source R code, Load image) keep track of the
directory that was last used, and start their dialog boxes from that
directory the next time they are used. That directory can be made the
working directory by the File | Change dir menu item.  All the `save'
menu items start dialog boxes at the current working directory: this
includes Save image and the various ways to save graphics, as well as
saving the workspace at the end of the session.

Observe that the help files use the latin1 encoding. To see all the
characters you must use an appropriate font (European-language True
Type fonts should be OK). To check if your preferred font has latin1
capability, try "help(text)" and look at the examples.  [Note: only a
couple of files make use of latin1 characters not contained in the
standard ASCII set so if you like a font without latin1 capability,
use it.]


TERMINAL/BATCH:

Rterm.exe will run from a command line such as an MS-DOS or Commands
Window running the standard shells, command.com (9x) and cmd.exe (NT),
as well as the ports of bash and tcsh that we use.  Its primary
purpose is to allow batch operation, but it does provide all the
facilities needed for interactive use, including simple command-line
editing.

Batch use: At it simplest, Rterm.exe can be used in a batch mode by
commands like

Rterm.exe --vsize 10M --nsize 400k --no-restore --no-save < infile > outfile

although users will probably want to set up simple .bat or .cmd files
to run batch jobs.


Use with ESS: You can use Rterm.exe to provide inferior R-mode in
ESS under NTEmacs, for example ess-5.1.9.  The pager is automatically
set to "console" so help will be displayed in emacs buffers.


GRAPHICS:

The screen device is called windows(). This is launched automatically,
and can also be launched explicitly by windows() or win.graph() (or
x11()) from both Rgui.exe and Rterm.exe.  A printer device can be
opened using win.print(), and graphs drawn as metafiles by
win.metafile().

The graphics device pops up a separate window which has two menus. The
device's File menu allows saving or printing or to run dev.off().

The History menu allows the recording of plots. When plots have been
recorded they can be reviewed by PgUp and PgDn, saved and replaced.
Recording can be turned on automatically (the Recording item on the
list) or individual plots can be added (Add or the INS key).
The whole plot history can be saved to or retrieved from an R variable
in the global environment.

There is only one graphics history shared by all the windows devices.

HELP:

There are several options for help, depending on which help files you
installed.

(i) Text help. This is the default, and the fallback option.
It will display in the currently set pager (use options(pager=) to change).

(ii) Compiled HTML files. Set this as the default by
options(chmhelp=T) or for individual help items by help(topic,
chmhelp=T).  Full text search is available from the Search tab.  To
make use of this you will need a recent version of Windows or IE4 or
later installed, or use the updater hhupd.exe on CRAN at 
bin/windows/windows-NT/etc.

(iii) Windows .hlp files. Set this as the default by
options(winhelp=T) or for individual help items by help(topic,
winhelp=T).  Full text search is available from the Search tab. The
conversion to this format is a little rough, and tables may be
incomplete.

(iv) HTML help to be displayed in your normal browser.  Set this as
the default by options(htmlhelp=T) or for individual help items by
help(topic, htmlhelp=T).  Using help.start() sets the browser to the 
top-level page, from which you can access a search engine.

(v) Latex help files are available for use with help(topic, offline=T).
You will need to customize the file rw0651\bin\helpPRINT.bat: it
contains instructions.



Customization
=============

Environment variables can be set as NAME=value on the command line,
including in a short-cut.  They can also be set (as NAME=value lines)
in the file .Renviron, or if that does not exist HOME\.Renviron.

Many aspects of the console (size, appearance, font, colours) can be
customized by editing the file etc\Rconsole, and a copy with a user's
settings can be put in her HOME directory or in the working
directory. (The exact sequence is to search the directory pointed to
by the first found of the environment variables R_USER then HOME then
{HOMEDRIVE}{HOMEPATH} then the working directory, finally R_HOME\etc.
This applies to .Renviron and other uses of `HOME' in our documentation.)
The file contains a description of the settings that can be
altered. See also ?Rconsole.

The mapping between Windows fonts and R font's number can be set by
editing the file etc\Rdevga, and a copy with a user's settings can be
put in the HOME or working directory (see the description of
Rconsole). This mapping applies to both the screen device and the
printer device.

Many R defaults can be set in the file R_HOME\etc\Rprofile or a user's
file .Rprofile. In particular:

- The pager is set by options(pager=). The default is "internal" which
  brings up a separate console-like window. The internal pager can use
  a single window or a different window for each topic shown
  (configurable in etc\Rconsole). Other possibilities we have
  used are "notepad" and "pfe32 /v", and "console" to list the files in
  the console (rgui.exe) or terminal window (rterm.exe).


Adding packages
===============

Binaries for many packages are available at
CRAN/bin/windows/windows-NT/contrib. These are zip files which should
be unpacked in rw0651\library. They are then available for use. You
can also use the installer rwinst.exe to selectively unpack the zip
files.

The list of packages and functions given by HTML help and used by the
search engine can be updated from a running R process by the command

	link.html.help()

provided the owner of the process has write permission on
rw0651\doc\html.  If you have the source-package files and Perl
installed you can use

	cd ...\rw0651\src\gnuwin32\help
	make indices

Private libraries of packages can be used and can be specified by the
environment variable RLIBS. (Separate directories by ";" in this
version.)  They will not be linked to HTML help.  In more detail, to
use packages installed in directory R:\libraries\gm, set

RLIBS=R:\libraries\gm

in the environment or on the command line, or add the line

.lib.loc <- c("R:/libraries/gm", .lib.loc)

to your .Rprofile or at the end of R_HOME\etc\Rprofile.

To install a package from source code you need the source-package
distribution rw0651sp.zip installed (but not the R source). This contains
detailed instructions.


Differences from Unix
=====================

- R can be interrupted by Esc in Rgui and by Ctrl-Break in Rterm:
  Ctrl-C is used for copying in the GUI version. C-c C-c works
  under emacs (only).

- Command-line editing is always available, but is much simpler than
  under readline-based input on Unix.

- The commands history is saved between sessions only by Rgui.

- The HTML function and package lists and search datasbase are not
  re-generated automatically by html.start(). Use link.html.help().

- Paths to files can be specified with "/" or "\\".

- Using help.start() does not automatically send help requests to the
  browser: use options(htmlhelp=T) to turn this on.

- Graphics save and replay only here.

- system() is enhanced here and does not automatically use a shell.
  See its help page and that of shell.


Building From Source
====================

[Some further details, including how to debug, are given in the RW-FAQ.]

First collect the tools that you need.

Building on Windows
-------------------

We recommend that you use the mingw32 port of gcc-2.95 by Mumit Khan from
ftp://ftp.xraylith.wisc.edu/pub/khan/gnu-win32/mingw32. You will also
need suitable versions of make, sh, rm, sed, awk, mkdir, echo, cp and
cat; we have packaged a set at CRAN/bin/windows/windows-NT/base/etc/tools.zip
extracted from the cygwin distribution
(http://sourceware.cygnus.com/cygwin and several mirrors). To avoid
past problems on some versions of Windows95, we use the cygwin ld
contained in that set, which must be before the mingw32 one in your
path. (We have no way of knowing if this is still necessary.)

It is also possible to use earlier mingw32 compilers or cygwin-b20.1
with the --no-cygwin flag, but we suggest you do so only if you have a
working setup from building earlier versions of R.  We have also
successfully used the variant of mingw32 that uses the MSVCRT run-time 
system (under gcc-2.95 but not earlier versions).
Be aware that not all Windows machines have MSVCRT.DLL installed.

(If you want to use cygwin, we suggest you upgrade to gcc-2.95 by
installing the files gcc-2.95-cygb20.tar.gz and gcc-2.95-mingw-extra.tar.gz
from ftp://ftp.xraylith.wisc.edu/pub/khan/gnu-win32/cygwin32.)

perl5, available via http://www.perl.com/CPAN/ports.

groff, available at http://www.itribe.net/virtunix/groff-1.10nt.zip.

zip and unzip from the Info-ZIP project
(ftp://ftp.cdrom.com/pub/infozip/Info-ZIP.html and mirrors).

If you want to make compiled html (.chm) files you will need the
Microsoft HTML Help Workshop, available for download at 
http://msdn.microsoft.com/workshop/author/htmlhelp.

If you want to make Windows (.hlp) files you will need a Windows help
compiler, preferably hcrtf.exe. This is available for download at
ftp://ftp.microsoft.com/support/MSLFILES/HCWSETUP.EXE.

All of these need to be installed and in your path, and the
appropriate environment variables set.

You also need: the R source (R-0.65.1.tgz), and to build the
installer, unzip5.40.zip from any Info-Zip mirror.  Do remember to set
MAKE_MODE to UNIX (set MAKE_MODE=UNIX at the Windows command-line).


Then: untar R-0.65.1.tgz somewhere,

	cd /somewhere/R-0.65.1/src/gnuwin32

edit MkRules to set the appropriate paths as needed
edit Makefile to set the type(s) of help that you want built.

and run

	make BUILD=MINGW32 or CYGWIN

Note 1: the file rw0651\unzip\unzip32.dll is not in the source
distribution, nor are the sources (it is the standard Info-Zip unzip
5.40, built with MSVC++4.2). You will need to copy it from a binary
distribution.

The file rw0651\bin\Rchtml.dll is only built if chm help is specifed
in the main Makefile. Its source is the help directory, and you need
the HTML Help Workshop files to build it. It contains instructions
to build it under VC++6, and it is preferable to use that as the 
VC++ library will check versions of the components needed.

Note 2: we are aware that because of limitations in line length or in
the shell used that the Makefiles do not work unchanged on all the
possible combinations of tools, compilers and OSes.  We have tested
the Cygwin make and shell under NT, and cross-building (see below).

Note 3: building libR.a is highly disk intensive and can take several
minutes even on a local disc. We have seen times from 30 secs to 20
minutes. Using a network file system is likely to take longer.


You can test a build by `make check': expect some differences in the tests
of print routines.


Cross-building on i386 Linux
----------------------------

You will need i386-mingw32 cross-compilers installed: see

http://www.xraylith.wisc.edu/~khan/software/gnu-win32/mingw-cross-howto.txt

and ensure that these are in your path. You will need Perl and nroff
installed.

You also need: the R source (R-0.65.1.tgz), and to build the installer,
unzip5.40.zip from any Info-ZIP mirror.

Then: untar R-0.65.1.tgz somewhere

	cd /somewhere/R-0.65.1/src/gnuwin32

Edit MkRules to set BUILD=CROSS and the appropriate paths as needed.
Edit Makefile to set the type(s) of help that you want built. (You
will not be able to cross-build .chm or .hlp files, nor Rchmtl.dll.)

Set the environment variable TEMP to, say, /tmp, and make.

Packages can be made in the same way as natively: see the file
readme.packages.



Feedback
========

Please send comments and bug reports to (preferably both of)

    Guido Masarotto <guido@hal.stat.unipd.it>
    Brian Ripley <ripley@stats.ox.ac.uk>
