The R Project SVN R

Building from a source-code library under Windows
=================================================

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.

We recommend that you use the mingw32 port of gcc-2.95.2 by Mumit Khan
from http://www.mingw.org/ or
ftp://ftp.xraylith.wisc.edu/pub/khan/gnu-win32/mingw32. You will also
need suitable versions of make, sh, cat, cp, diff, echo, g(awk),
mkdir, mv, rm, sed; we have packaged a set at
http://www.stats.ox.ac.uk/pub/Rtools/tools.zip extracted from the
cygwin distribution (http://sources.redhat.com/cygwin/mirrors.html)
or (gzip, tar) compiled from the sources.

BEWARE: `Native' ports of make are _not_ suitable, and the 18 Jan 2000
cygwin port of make crashes when building packages.  There are also
problems with earlier versions of the cygwin1.dll and we have used
version 1.1.3.  To avoid frustration, please use our tool set.


It may also be possible to use the compilers from the cygwin 1.1
release with the -mno-cygwin flag.  (You will need the cygwin*, gcc*
and binutils* bundles. You will need to ensure that you have only one
version of cygwin1.dll in your path, and there is one in our tools
distribution.)

We have also successfully used the variant of mingw32 that uses the
MSVCRT run-time system, and in the case of the mclust library we found
this more successful than the standard version.  Be aware that many
Windows 95 machines do not have MSVCRT.DLL installed.

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

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 Window help files you will need hcrtf.exe from a
Windows compiler installation (this has been available for download at
ftp://ftp.microsoft.com/softlib/mslfiles/hcwsetup.exe).

For large packages it is helpful to make zipped help and/or data
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 BUILD and
the appropriate paths as needed.  (IMPORTANT: if you use cygwin you
must edit MkRules and set BUILD=CYGWIN.)

Then

    cd RHOME\src\gnuwin32
    make libR.a

which may take several minutes. (We have seen times from 30 secs to 20
minutes depending on processor speed, RAM, disk speed and
compiler. Using a network file system is likely to take longer. With
mingw32, gcc-2.95.2.1 and later only take a few seconds.)  This only
needs to be done once for each R release.

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

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, which will automatically be included by MakeDLL.
For example, for RODBC src/Makevars 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.


Using zipped help files
=======================

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.


Using zipped data files
=======================

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.


Checking packages
=================

The equivalent of `R CMD check mypkg' on Unix is

    make pkgcheck-mypkg

This runs all the examples in the help files. If you need to increase
the heap size or the number of cons cells (e.g. for nlme) use
environmental variables to do so.  

It will also run and `diff' examples in the tests directory if one
exists.


Debugging
=========

See the rw-FAQ.


Using Visual C++
================

You may if you prefer use Visual C++ to make the DLLs (unless they use
Fortran source!). First build the import library R.lib by

    lib /def:R.exp /out:Rdll.lib

Then you can compile the objects and build the DLL by

    cl /MT /Ox /D "WIN32"  /c *.c
    link /dll /def:mypkg.def /out:mypkg.dll *.obj Rdll.lib

where you will need to create the .def file by hand listing the entry
points to be exported.  (If there are just a few you can use /export
flags instead.) If the C sources use R header files you will need to
arrange for these to be searched, perhaps by including in the cl line

    /I ..\..\..\include

If you build a debug version of the DLL in the development
environment, you can debug the DLL code there just by setting the
executable to be debugged as the full path to the R front-end.

Extra care is needed when referencing variables (rather than
functions) exported from R.dll.  These must be declared
__declspec(dllimport).  A list of the relevant variables is in the
file `exported-vars'.


Using Borland C++
=================

Borland C++5.5 is available as a free download from
http://www.borland.com/bcppbuilder/freecompiler/ and as part of C++
Builder 5.  The following will make convolve.dll from convolve.c (flag
-6 optimizes for a Pentium Pro/II/III, and -u- removes extra underscores)

bcc32 -u- -6 -O2 -WDE convolve.c

You can build an import library for R.dll by copying R.exp to R.def and
using

implib R.lib R.def

and then add R.lib to the bcc32 command line, for example (from
Venables & Ripley's `S Programming')

bcc32 -u- -6 -O2 -WDE -I\R\rw1010\src\include VCrndR.c R.lib

We presume further steps are needed to reference variables (as
distinct from functions) exported from R.dll, but have not
investigated.


Using other compilers and languages
===================================

To use C++ see the section in the R for Windows FAQ.  You can include
C++ code in packages as from R 1.1.1, and the supplied Makefiles will
compile with g++ and link the DLL using g++ (and hence link against
libstc++.a).

For other compilers you will need to arrange to produce a DLL with
cdecl (also known as _cdecl or __cdecl) linkage.  The mingw32 port
(and VC++) uses no `name mangling' at all, so that if for example your
compiler adds leading or trailing underscores you will need to use the
transformed symbol in the call to .C in your R code.  Many compilers
can produce cdecl DLLs by a suitable choice of flags, but if yours
cannot you may need to write some `glue' code in C to interface to the
DLL.

If you use .Fortran this appends an underscore and does no case
conversion at all to the symbol name.  It is normally best to use
.C with compilers other than g77 and map the name manually if necessary.

Care is needed in passing character strings to and from a DLL by .C:
they must be equivalent to the C type char** and null-terminated.  Not
even the mingw32 g77 Fortran uses null-terminated strings.

WARNING: DLLs made with some compilers reset the FPU in their
startup code (Delphi is one), and this will cause operations such as 0./0.
to crash R.  You can re-set the FPU to the correct values by a call
to the C entry point Rwin_fpset().


Simple Ports
============

If your package has no C nor Fortran not C++ sources, several steps
can be omitted.

You will need 

suitable versions of make, sh, rm, sed, awk, mkdir, echo, cp and cat;
we have packaged a set at http://www.stats.ox.ac.uk/pub/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


If you have a Unix/Linux box, it will suffice to zip up the Unix
installation of the package.  Install the package, then

    cd `R RHOME`/library
    zip -rl /dest/mypkg.zip mypkg

(the -l flag converts to CRLF line endings: it is not necessary but
users may want to read the information files in a Windows editor).

zip is often installed on Linux machines, and sources and binaries for
Unix boxes are available via the Info-Zip site given above.


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
    make PKGDIR=/mysources RLIB=/R/library pkgcheck-mypkg

which installs the package in \mysources\mypkg as \R\library\mypkg and
checks its examples.


Cross-building packages on Linux
================================

It is straightforward to build a package on a ix86-linux system,
although it is not possible (as far as we know) to cross-build .chm or
.hlp files.  For a package without compiled code you can just zip up
the Linux installation of the package.

First you need to set up the cross-compilers and tools (see INSTALL)
and have them in your path. We will assume that your Linux
installation has Perl5, unzip and zip.

Edit MkRules to set BUILD=CROSS and the appropriate paths (including
HEADER) as needed, and check that Makefile has WINHELP set to NO.

Then packages can be made as natively, for example by

    cd .../src/gnuwin32
    make PKGDIR=/mysources RLIB=/R/win/library pkg-mypkg
    make PKGDIR=/mysources RLIB=/R/win/library pkgcheck-mypkg
    cd /R/win/library
    zip -rl /dest/mypkg.zip mypkg


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>