The R Project SVN R

R for Windows
=============

This distribution contains the sources to build a port of R to run on
(32-bit) Windows 95, 98, ME, NT4, 2000, XP and 2003 on Intel/clone
chips. See the file `README.rw2xxx' for fuller details, including how
to install the binary versions.


Building From Source on Windows
===============================

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

First collect the tools that you need.  There is a `portal' with
current links at http://www.murdoch-sutherland.com/Rtools/.


Collect the tools
-----------------

You will need suitable versions of at least make, sh, cat, cp, cut,
diff, echo, egrep, expr, grep, ls, mkdir, mv, rm, sed, touch; we use
those from the cygwin distribution
(http://www.cygwin.com/mirrors.html) or (gzip, makeinfo, texindex)
compiled from the sources.  We have packaged a set at
http://www.murdoch-sutherland.com/Rtools/tools.zip.

BEWARE: `Native' ports of make are _not_ suitable (including that at
the mingw site).  There were also problems with several earlier
versions of the cygwin tools and dll.  To avoid frustration, please
use our tool set, and make sure it is at the front of your path
(including before the Windows system directories).  If you are using a
Windows shell, type PATH at the prompt to find out.

iconv.dll from http://www.murdoch-sutherland.com/Rtools/iconv.dll.
Put this in R_HOME/modules at the end of the build.


You need a recent version of the Mingw port of gcc from
http://sourceforge.net/projects/mingw/.  There will be a distribution
called something like MinGW-3.1.0-1.exe (which is built from
gcc-3.2.3).  This needs updating with mingw-runtime >= 3.5 and w32api
>= 3.1.  The release of gcc-3.3.1 and the release candidates of 3.4.1
and 3.4.2 have also been tested successfully.  
Jan 2005: There is now a release candidate of MinGW-3.2.0: please use that.


The Windows port of perl5, available via
http://www.activestate.com/Products/ActivePerl/.
BEWARE: you do need the *Windows* port and not the Cygwin one.

zip and unzip from the Info-ZIP project (http://www.info-zip.org and
mirrors, and included in our tools.zip).

The TclTk support files are in
http://www.murdoch-sutherland.com/Rtools/R_Tcl.zip: unzip it at the
top level of the R sources: it will add directories $RHOME/Tcl,
$RHOME/Tcl/bin, etc.

To make compiled html (.chm) files you will need the
Microsoft HTML Help Workshop, currently available for download at
http://msdn.microsoft.com/library/en-us/htmlhelp/html/hwmicrosofthtmlhelpdownloads.asp
and http://www.microsoft.com/office/ork/xp/appndx/appa06.htm.
(It is not longer documented how not to make .chm files.)

You may need this on the same drive as the other tools. (Although we
have successfully used it elsewhere, others have reported problems).


All of these need to be installed and in your path, and the
appropriate environment variables set.  You also need `.' in your
path.  Do not use filepaths with spaces in: you can always use the
short forms (found by dir /x at the Windows command line).


Check your path
---------------

You need the following in your path (with the first two first):
.
our toolset
mingw\bin
Perl\bin
the latex bin directory
zip.exe, unzip.exe, hhc.exe

Do not use spaces nor unnecessary quotes in your PATH variable.

Make sure all of the above are before the Windows system directories
(especially that containing FIND.EXE).

Do not have our toolset and any other version of cygwin1.dll in your path.


Building
--------

You also need the R source (R-2.x.y.tgz).

Then: untar R-2.x.y.tgz somewhere (with no spaces in the path names),

    cd /somewhere
    tar zxvf /path/to/R-2.x.y.tgz
    cd /somewhere/R-2.x.y/src/gnuwin32

BEWARE: do untar the sources rather than use broken tools such as
WinZip that don't understand about symbolic links.

IMPORTANT: edit MkRules to set the appropriate paths as needed and to
set the type(s) of help that you want built.  BEWARE: MkRules contains
tabs and some editors (e.g. WinEdt) silently remove them.

Then run

    make


Note 1: The file bin/Rchtml.dll is only built if CHM help is
specified in MkRules. Its source is the help directory, and you need
the HTML Help Workshop files to build it.  You can just
copy this from a binary distribution.

Note 2: we have had reports that earlier versions of Norton Anti-Virus
lock up the machine when windres is run, so you may need to disable
it. (Norton Anti-Virus 2002 causes no problems.)

Note 3: By default Doug Lea's malloc in the file src/gnuwin32/malloc.c
is used for R's internal memory allocations.  You can opt out of this
by commenting the line LEA_MALLOC=YES in MkRules, in which case the
malloc in msvcrt.dll is used.  This does work but imposes a
considerable performance penalty.

Note 4: You can run a parallel make by e.g.

    make -j2

but this is only likely to be worthwhile on a dual-processor (or
perhaps a hyperthreaded P4) machine with ample (at least 384Mb) of
memory.  On a dual AthlonXP it reduced the build time by about 30%
whereas on a single P4HT it reduced it by 10%.  Note that this may
sometimes stop and have to be restarted.


You can test a build by (optionally) building the recommended packages
(see below) and running `make check'.  You may need to set TMPDIR to
(the absolute path to) a suitable temporary directory: the default is
c:/TEMP.  (Use forward slashes and do not use a path including spaces.)


Using ATLAS
-----------

You can make use of ATLAS (http://math-atlas.sourceforge.net/) fast
BLAS libraries by defining USE_ATLAS=YES in MkRules and specifying the
path to the libraries in macro ATLAS_PATH.

You will need to build the libraries optimized for your architecture
under the Cygwin compilers.

For convenience

    make Rblas-clean Rblas

will re-make the Rblas.dll and so allows experimentation with different BLAS
configurations.

Prebuilt Rblas.dll for various Pentium and AthlonXP chips are available
in the windows/contrib/ATLAS area on CRAN.


Using K. Goto's BLAS
--------------------

Another tuned BLAS which is available for some CPUs is by Kazushige
Goto.  He does not allow redistribution: they are currently available
via http://www.cs.utexas.edu/users/kgoto/signup_first.html.  To make
use of this, put the DLL somewhere in your path or in R_HOME/bin, and
edit MkRules to define USE_GOTO=YES and the name of the DLL (something
like libgoto_p4_512-r0.9.dll).

Goto's BLAS takes preference over ATLAS, and seems a little faster.
However, as it is compiled for MSVC, we have been unable to make it
work for complex arithmetic and so it is only used in for real linear
algebra.

Dr Goto supplies DLLs for PIII, P4 and Opteron processors: that for
PIIIs runs on AthlonXP as well.


Building bitmap device support
------------------------------

The file bin/Rbitmap.dll is not built automatically: instructions on
how to build it are in the file bitmap/INSTALL.

If everything is set up in directory bitmap,

    make bitmapdll

will work from this directory.


Internationalization
--------------------

This version of R can be built with support for some multibyte
character sets such as UTF and (some of) those used in Chinese,
Japanese and Korean.

Define SUPPORT_GUI_MBCS in MkRules to enable support for MBCS in the
RGui console, pager, data and script editors (this is based on the
Japanization patches by Nakama and Okada).

Define SUPPORT_UTF8 in MkRules to enable support in the R engine for
UTF-8 character sets.  [We need to supply a way to specify such a
locale.]  This will also handle MBCSs which are strict supersets of
ASCII, such as EUC-JP, but not [yet] Japanese in code page 932.

If either of these is defined you need the DLL msvcp60.dll to be
installed.  It is on recent versions of Windows, and can be obtained
by an Internet search.



Recommended packages
====================

The recommended packages can be built by

    make recommended

and checked by

    make check-recommended


If you are using a cvs/rsync version of the R sources, you need to put
the .tar.gz files for the recommended packages in
../library/Recommended, and run `make link-recommended'.  If you have
rsync installed,

    make rsync-recommended

does this from the CRAN master.


Building the Manuals
====================

To make the PDF versions of the manuals you will need pdftex installed
and configured to work with a large file: see doc/manual/README.  You
also need texindex (included in our tool set).  Then the pdf manuals
can be made by

    make manuals

If you want to make the info versions (not the Reference Manual), use

    cd ../../doc/manual
    make -f Makefile.win info

To make DVI versions of the manuals use

    cd ../../doc/manual
    make -f Makefile.win dvi

(assuming you have tex and latex installed and in your path).

The fptex distribution of TeX (via www.fptex.org) includes a suitable
port of pdftex.  Please read the section in R-admin.html about how to
make 'refman.pdf' and set the environment variables R_RD4DVI and
R_RD4PDF suitably and ensure you have the required fonts installed.

By default the manuals are made for the ISO standard a4 paper size.
Users living in N. America might want to use

    cd ../../doc/manual
    make -f Makefile.win R_PAPERSIZE=letter pdf 

or set R_PAPERSIZE in the environment and use make -e, for example

    R_PAPERSIZE=letter make -e manuals

See the R-admin manuals for fuller details.


Building the installers
=======================

See installer/INSTALL.  You need to have the files for a complete R build,
including bitmap and Tcl/Tk support and the manuals, as well as the
recommended packages.

Once everything is set up

    make distribution
    make check-all

will make all the pieces and the installers and put them in the
gnuwin32/cran subdirectory, then check the build.  This works by building
all the parts in the sequence:

    Rpwd.exe (a utility needed in the build)
    rbuild (the executables, the FAQ docs etc.)
    rpackage (the base packages)
    htmldocs (the HTML documentation)
    bitmapdll (the bitmap support files)
    recommended (the recommended packages)
    vignettes (the vignettes in package grid:
           only need if building from svn checkout)
    manuals (the PDF manuals)
    rinstaller (the install program)
    crandir (the CRAN distribution directory)

The parts can be made individually if a full build is not needed, but
earlier parts must be built before later ones.  (The Makefile doesn't
enforce this dependency---some build targets force a lot of
computation even if all files are up to date.)  The first four targets
are the default build if just "make" is run.

If you want to customize the installation by adding extra packages,
replace `make rinstaller' by something like

    make rinstaller EXTRA_PKGS='pkg1 pkg2 pkg3'

(Note these packages will also be added to the miniR installer.)

An alternative way to customize the installer starting with a binary
distribution is given in file installer/INSTALL.


Cross-building on ix86 Linux
============================

You will need i386-mingw32 cross-compilers installed and in your path.
There is currently a complete set of tools at

    http://www.stats.ox.ac.uk/pub/Rtools/mingw-cross4.tar.bz2

(Just unpack this somewhere and put its bin directory in your path.)

You will need Perl, zip and unzip installed and makeinfo >= 4.5
(part of GNU texinfo).

You also need the R source (R-2.x.y.tgz).

Then: untar R-2.x.y.tgz somewhere, and

    cd /somewhere/R-2.x.y/src/gnuwin32

Edit MkRules to set BUILD=CROSS and the appropriate paths (including
HEADER) as needed.

Edit MkRules to set the type(s) of help that you want built. (You will
not be able to cross-build .chm files, so WINHELP is automatically set
to NO.)

You also need a working copy of *this version* of R on Linux:
uncomment and set R_EXE in MkRules to point to it.

Then run `make' (and parallel make works reliably, unlike on Windows).

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

(It is possible to cross-build the installers using WINE, which we
leave as an exercise for the reader.)

To distribute a cross-build (or just to transfer it to a Windows machine
for testing) use

    cd installer
    make imagedir
    zip -r9X rw2000.zip rw2000  # or something similar

Currently we have not found a reliable way to convert base to lazy-loading
when cross-building, so it is left in the old format.


Feedback
========

Please send comments and bug reports to

    R-windows@r-project.org