Writing packages for R
======================

See the Writing R Extensions manual for a full description of how
to write a package.


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

Instructions for installing the toolset and building packages using the
standard methods are in the `R Installation and Administration' manual
(which is available in various formats as R-admin.* in the doc/manual
directory).

This file contains instructions for non-standard situations:

 - Using Microsoft Visual C++
 - Using Borland C++
 - Using other compilers and languages
 - Cross-building packages on Linux

 
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 Rdll.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) (as in R's own header files).  The list of the
relevant variables is at the end of the file 'R.exp'.

VC++ lacks some standard functions such as isnan and isfinite.  To use
R's macros you will need

#undef ISNAN
#define ISNAN(x) _isnan(x)
#undef R_FINITE
#define R_FINITE(x) _finite(x)

for example.  Even then, we have seen examples of IEC60559 arithmetic
being performed incorrectly.


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/4, 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\rw1050\src\include VCrndR.c R.lib

We believe that when referencing variables (rather than functions)
exported from R.dll these must be declared __declspec(dllimport) just
as for VC++.


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

To use C++ see the section in the R for Windows FAQ.  You can include
C++ code in packages and the supplied Makefiles will compile with g++
and link the DLL using g++ (and hence link against libstc++.a).  Use
of C++ I/O may or may not work, and has been seen to crash R.

For other compilers you will need to arrange to produce a DLL with
cdecl (also known as _cdecl or __cdecl) linkage.  The mingw 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 mingw g77 Fortran uses null-terminated strings.

WARNING: DLLs made with some compilers reset the FPU in their startup
code (Delphi has been 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().

For some further details and Delphi examples see
http://www.stats.uwo.ca/faculty/murdoch/software/compilingDLLs/


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

It is straightforward to build a package on a ix86-linux system,
although it seems not possible (and we have tried, including using
WINE) to cross-build .chm files.  You will need an installation of R
for Windows, either copied from a Windows system or cross-compiled.

First you need to set up the cross-compilers and tools (see the `R
Installation and Administration' manual) 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.

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 -r9X /dest/mypkg.zip mypkg

(Rcmd is a Windows executable, so cannot be used.)

If your package has no compiled code it is possible that zipping up
the installed package on Linux will produce an installable package on
Windows.  (It has always worked for us, but failures have been reported.)


Feedback
========

Please send comments and bug reports to

	R-windows@r-project.org