Building from a source-code library under Windows ================================================= If your package has neither C nor Fortran source, see `Simple ports' at 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, rm, sed, (g)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) or (make) compiled from the GNU sources ourselves. BEWARE: Most `native' ports of make are _not_ suitable, and the 18 Jan 2000 cygwin port crashes when building packages. It is also 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.) We have also successfully used the variant of mingw32 that uses the MSVCRT run-time system (under gcc-2.95.x but not earlier versions), and in the case of the mclust library we found this more successful that the standard version. Be aware that many Windows 95 machines do not have MSVCRT.DLL installed. perl5, available via http://www.perl.com/CPAN/ports. 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), or hcp505.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). 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.) Do remember to set MAKE_MODE to UNIX (set MAKE_MODE=UNIX at the Windows command-line) if using a cygwin port of make. 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.) 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 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 the C sources use R header files you will need to arrange for these to be searched, perhaps by /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 to the full path to the R front-end. 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 II/III) 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 `S Programming') bcc32 -u- -6 -O2 -WDE -I\R\rw1010\src\include VCrndR.c R.lib Using other compilers and languages =================================== To use C++ see the section in the R for Windows FAQ. 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. Simple Ports ============ If your package has neither C nor Fortran source, 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 bin/windows/windows-NT/etc/tools.zip perl5, available via http://www.perl.com/CPAN/ports. 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 absolutely 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 i386-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 Brian Ripley