The R Project SVN R

[If you are reading this file as part of the full R source distribution,

you need to build R first: see file INSTALL.]

    here as a result of bitter experience.  Please do not report problems

    to R-help unless you have followed all the prescriptions. ***

If your package has no C nor Fortran nor C++ sources, see `Simple ports' 

near the bottom of this file.

First collect the tools that you need.  There is a `portal' with

current links at http://www.murdoch-sutherland.com/Rtools/.

You will need suitable versions of at least make, sh, cat, cp, diff,

echo, mkdir, mv, rm, sed; we have packaged a set at

http://www.murdoch-sutherland.com/Rtools/tools.zip extracted from the

cygwin distribution (http://www.cygwin.com/mirrors.html) or (gzip)

compiled from the sources.

BEWARE: `Native' ports of make are _not_ suitable (including that at

the mingw site).  There were also problems with several earlier

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.

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).  Earlier versions may work, but mingw-runtime >= 3.0 and

w32api >= 2.0 are essential.  The releases of gcc-3.3.1, 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.

If you want 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

You may need this on the same drive as the other tools. (Although we

have successfully used it elsewhere, others have reported problems).

files: for that you need zip and unzip from the Info-ZIP project

(www.info-zip.org and mirrors, and included in our tools.zip).

All of these need to be installed and in your path, and the

appropriate environment variables set.  

Edit MkRules to set the appropriate paths as needed.

BEWARE: MkRules contains tabs and some editors (e.g. WinEdt) silently 

Do not use filepaths with spaces in: you can always use the short forms

(found by dir /x at the Windows command line).

Do not use unnecessary quotes in your PATH variable.

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

BEWARE: if you have Norton Anti-Virus you may need to disable it.

Some versions lock up the machine when windres is run.  (Norton

Anti-Virus 2002 causes no problems.)

BEWARE: Don't expect this to work if the path to R_HOME contains spaces.

It may work, but we don't recommend it.

Then

	cd R_HOME\src\gnuwin32

	make libR.a libRblas.a

which might take up to a minute.  This only needs to be done once for

each R release, and will be done automatically when needed if

omitted at this point.

At this point there are two approaches:

1) Streamlined way

Assuming that ...\rw10xx\bin is in your path, use

	R CMD INSTALL package

where `package' can be a directory or a .tar.gz file.  See

R CMD INSTALL --help for a full list of options, which include

  -l, --library=LIB	install packages to library tree LIB

      --docs=TYPE	type(s) of documentation to build and install

      --use-zip-data	collect data files in zip archive

      --use-zip-help	collect help and examples into zip archives

      --use-zip		combine `--use-zip-data' and `--use-zip-help'

TYPE can be "none" or "normal" or "chm" (the default) or "all"

2) Manual `full-control'

For each package you want to install, unpack it to a directory, say

mypkg, in R_HOME\src\library, and run

	cd R_HOME\src\gnuwin32

	make pkg-mypkg

Customising compilation

=======================

The Makefiles can be customized: in particular the name of the DLL can

be set (for example we once needed integrate-DLLNM=adapt), the compile

flags can be set (see the examples in MakeDll) and the types of help

(if any) to be generated can be chosen (variables HELP and WINHELP).

The simplest way to customize the compilation steps is to set variables in

a file src\Makevars.win, which will automatically be included by MakeDLL.

For example, for RODBC src\Makevars.win could include the line

DLLLIBS+=-lodbc32

or, equivalently,

RODBC-DLLLIBS=-lodbc32

If you have a file src\Makefile.win, that will be used as the makefile

for source compilation in place of our makefile MakeDll.

BEWARE: files src\Makefile or src\Makevars will be used if they exist

and the .win equivalents do not.  Such files included in package

BEWARE: references to variables in R.dll are converted to the

right form by using the header files.  You must include them.

=======================

You will need zip installed, of course. Just run

	make ziponly-mypkg

after building mypkg.  Target `ziphelp-mypkg' will make the zip files

but not remove the separate files: this can be used for testing.

This is an option to R CMD INSTALL.

=======================

You will need zip installed. Just run

	make zipdata-mypkg

after building mypkg.  This is recommended if you have either many small

data files (as in package Devore5) or a few large data files.

This is an option to R CMD INSTALL.

==============================

`R CMD check mypkg' can be used just as on Unix.  Use `R CMD check

--help' for full details.  There is an analogous call for build.

You may need to set TMPDIR to (the absolute path to) a suitable

temporary directory: the default is c:/TEMP.  (Use forward slashes,

although the code will try to convert backslashes as from 1.7.0.  Do

not have spaces in the filepath, although from 1.9.0 we attempt to

work around this.)

These have been used successfully under NT/2000/XP.  We have seen

problems with some Perl versions on Win 95/98/ME, but believe these

are now resolved.  `make pkgcheck-mypkg' will perform the tests of the

examples and tests directory, as far as we know on all versions of

Windows.

=====================================

See the Writing R Extensions manual for full instructions on converting

package help files to DVI or PDF format.  If you have the necessary tools 

installed,

	R CMD rd2dvi --pdf mypkg

will use LaTeX to build a PDF version of the reference manual.	

Debugging

=========

See the rw-FAQ.

Simple Ports

============

If your package has no C nor Fortran nor C++ sources, several steps

can be omitted.

You will need 

suitable versions of Unix tools including make, sh, rm, sed, awk,

mkdir, echo, cp and cat; we have packaged a set at

http://www.murdoch-sutherland.com/Rtools/tools.zip.

perl5, available via http://www.activestate.com/Products/ActivePerl/

All of these need to be installed and in your path, and the

appropriate environment variables set.

For each package you want to install, unpack it to a directory, say

mypkg, in RHOME\src\library, and run

	cd RHOME\src\gnuwin32

	make pkg-mypkg

Non-standard locations

======================

You can specify the location of the package source by PKGDIR and the

library in which to install the package by RLIB, as in

	make PKGDIR=/mysources RLIB=/R/library pkg-mypkg

which installs the package in \mysources\mypkg as \R\library\mypkg.

It may well be simpler to use

	R CMD INSTALL -l /R/library /mysources/mypkg

Once again, if the paths contain spaces use the short forms, although

R CMD INSTALL will attempt to convert the paths if needed (but they

will need to be quoted on the command line, probably by double

quotes).