Building from a source-code library under Windows ================================================= [If you are reading this file as part of the full R source distribution, you need to build R first: see file INSTALL.] 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.stats.ox.ac.uk/pub/Rtools/. You will need suitable versions of at least 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://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 versions of the cygwin tools and dll. To avoid frustration, please use our tool set. We recommend that you use the mingw port of gcc-2.95.2-1 by Mumit Khan from http://www.mingw.org/. (The `portal' gives more precise instructions on the current locations.) As R itself is built against msvcrt.dll, we strongly recommend that you use that version of the compilers. BEWARE: you *cannot* use earlier versions of the mingw compilers, for example the gcc-2.95.2 (no -1): the symptom is a report that `-shared' is not understood. It might also be possible to use the compilers from the cygwin 1.1 net release with the -mno-cygwin -mwin32 flags; the current versions use mscrt.dll. (You will need the cygwin, gcc, mingw32, w32api and binutils bundles. All the recent versions we have tried do not work unchanged with -mno-cygwin.) 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/library/tools/htmlhelp/wkshp/download.htm You may need this on the same drive as the other tools. (Although we have successfully used it elsewhere, others have reported problems). 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.) BEWARE: if you have Norton Anti-Virus you may need to disable it. Some versions lock up the machine when windres is run. BEWARE: Don't expect this to work if the path to R_HOME contains spaces. Then cd R_HOME\src\gnuwin32 make libR.a which might take several minutes. (We have seen times from 5 secs to 20 minutes depending on compiler version, processor speed, RAM, disk speed and compiler.) This only needs to be done once for each R release, and should be done automatically when needed if omitted at this point. At this point there are two approaches: 1) Streamlined way Assuming that ...\rw1040\bin is in your path, use Rcmd INSTALL package where `package' can be a directory or a .tar.gz file. See Rcmd 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 "winhlp" 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 sources are usually designed for use under Unix and are best removed. BEWARE: references to variables in R.dll are converted to the right form by including "globalvar.h" in the C source. If you use your own Makefile.win or set CFLAGS (rather than append to it) you may need to include "globalvar.h" explicitly. (References to exported variables may lurk inside the macros of Rinternals.h and Rdefines.h.) 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. This is an option to Rcmd INSTALL. 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. This is an option to Rcmd INSTALL. Checking and building packages ============================== The equivalent of `R CMD check mypkg' on Unix is Rcmd check mypkg Use `Rcmd check --help' for full details. There is an analogous call for build. You may need to set TMPDIR to a suitable temporary directory: the default is c:\TEMP. These have been used successfully under NT/2000. We have seen problems with some Perl versions on Win 95/08/ME. make pkgcheck-mypkg will perform the tests of the examples and tests directory, as far as we know on all OSes. 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\rw1040\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(). 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.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 which installs the package in \mysources\mypkg as \R\library\mypkg. It may well be simpler to use Rcmd INSTALL -l /R/library /mysources/mypkg Cross-building packages on Linux ================================ It is straightforward to build a package on a ix86-linux system, although it is not possible (and we have tried, including using WINE) 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 file src/gnuwin32/INSTALL in the full source distribution) 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 STAMP=NO 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 (Rcmd is a Windows executable, so cannot be used. Notice the STAMP=NO line.) Feedback ======== Please send comments and bug reports to (preferably both of) Guido Masarotto Brian Ripley