R @FULLVERSION@ for Windows
===================

This distribution contains a binary distribution of R-@RVER@ to run on
Windows XP and later (including 64-bit versions of Windows) on ix86
and x86_64 chips.  It is designed to be as close as possible to the
implementation on Unix, but see the list of differences below.  The
port was by Guido Masarotto, Brian Ripley and Duncan Murdoch.


Installation
============

The distribution is distributed as an installer @RWVER@-win.exe.  Just
run this for a Windows-style installer.

For more details, including command-line options for the installer and
how to uninstall, see the rw-FAQ.  If you are reading this as part of
an installed version of R, that is both a file rw-FAQ in this directory
and a file doc\html\rw-FAQ.html.


Usage
=====

There are two versions of the R executable in @RWVER@\bin\i386 (32-bit)
and @RWVER@\bin\x64 (64-bit).  By default only the first is
installed on 32-bit versions of Windows, and both on 64-bit OSes.

GUI:

Rgui.exe runs as a standard Windows GUI executable and provides an R
console in its own window.  It takes the standard R command-line
arguments; these are most easily set by making a shortcut to
...\@RWVER@\bin\i386\Rgui.exe (or x64\Rgui.exe) and adding the
arguments in the Target field.  Set the 'Start in' field of the
shortcut to the directory you want to use as the working directory
(where workspaces and files are saved to and loaded from).  The
installer creates a shortcut on the desktop for you (by default).

You have a choice of interface: SDI (separate windows) or MDI
(multiple child windows in one large window).  MDI is the default:
select SDI by adding --sdi in the Target field: this can also be
selected from the installer.

Command-line editing is available: see Help | Console for details.

The menus provide shortcuts to some R commands such as help, help.start,
apropos, ls, load, save.image, search.

The 'load' menu items (Source R code, Display file, Load Workspace)
keep track of the directory that was last used, and start their dialog
boxes from that directory the next time they are used.  That directory
can be made the working directory by the File | Change dir menu item.
All the 'save' menu items start dialog boxes at the current working
directory: this includes 'Save Workspace' and the various ways to save
graphics, as well as saving the workspace at the end of the session.

Note that a few of the text help files use accented Western European.
To see all the characters you must use an appropriate font
(European-language True Type fonts should be OK).  To check if your
preferred font has these characters, try "help(text)" and look at the
examples.


TERMINAL/BATCH:

Rterm.exe will run from a command line such as a 'Command Prompt'
window running the standard shell, cmd.exe, as well as the ports of
bash and tcsh that we use.  Its primary purpose is to allow batch
operation, but it does provide all the facilities needed for
interactive use, including command-line editing (see the file
README.Rterm).

Batch use: At its simplest, Rterm.exe can be used in a batch mode by
commands like

Rterm.exe --no-restore --no-save < infile > outfile 2>&1

although users will probably want to set up simple .bat or .cmd files
to run batch jobs. You can also use it via R CMD BATCH: see ?BATCH or
R CMD BATCH --help.

Use with ESS: You can use Rterm.exe to provide inferior R-mode in ESS
under NTEmacs.  The pager is automatically set to "console" so text
help will be displayed in emacs buffers.


GRAPHICS:

The screen device is called windows().  This is launched
automatically, and can also be launched explicitly by windows() from
both Rgui.exe and Rterm.exe.  A printer device can be opened using
win.print(), and graphs drawn as metafiles by win.metafile().

The graphics device pops up a separate window which has two menus.  The
device's File menu allows saving or printing or to run dev.off().

The History menu allows the recording of plots.  When plots have been
recorded they can be reviewed by PgUp and PgDn, saved and replaced.
Recording can be turned on automatically (the Recording item on the
list) or individual plots can be added (Add or the INS key).

The whole plot history can be saved to or retrieved from an R variable
in the global environment.
  The format of recorded plots may change between R versions.
  Recorded plots should NOT be used as a permanent
  storage format for R plots.

There is only one graphics history shared by all the windows devices.


Customization
=============

Environment variables can be set as NAME=value at the end of the
command line, including in a shortcut.  They can also be set (as
NAME=value lines) in the file .Renviron in the working directory, or
if that does not exist HOME\.Renviron.

Many aspects of the console (size, appearance, font, font size,
colours) can be customized by editing the file etc\Rconsole, and a
copy with a user's settings can be put in her HOME directory or in the
working directory.  (The exact sequence is to search the directory
pointed to by the first found of the environment variables R_USER then
HOME, then the Windows "personal" directory (typically
'C:\Users\username\My Documents' on recent versions of Windows and
'C:\Documents and Settings\username\My Documents' on XP) then
{HOMEDRIVE}{HOMEPATH} then the working directory, finally R_HOME\etc.
This also applies to .Renviron and other uses of 'HOME' in our
documentation.)  The file contains a description of the settings that
can be altered.  See also ?Rconsole.

An alternative way to edit the Rconsole file is to use the GUI
preferences item on the Edit menu in Rgui.exe.  This can change some
of the settings (for example colours, font and window sizes) on the
current running console.

The mapping between Windows fonts and the font number used in R's
graphics can be set by editing the file etc\Rdevga, and a copy with a
user's settings can be put in the HOME or working directory (see the
description of Rconsole).  This mapping applies to both the screen
device and the printer device.

Many R defaults can be set in the file R_HOME\etc\Rprofile or a user's
file .Rprofile.  In particular:

- The pager is set by options(pager=).  The default is "internal"
  which brings up a separate console-like window.  The internal pager
  can use a single window or a different window for each topic shown
  (configurable in Rconsole).  Other possibilities we have used are
  "notepad" and "console" to list the files in the console (Rgui.exe)
  or terminal window (Rterm.exe).


Adding packages
===============

Binaries for many packages are available under
CRAN/bin/windows/contrib.  These are zip files which should be
unpacked in @RWVER@\library.  The simplest option is use the items on
the Packages menu to install from a zip file or to download from CRAN.

Private libraries of packages can be used and can be specified by the
environment variable R_LIBS.  (Separate directories by ";" in this
version.)  They will not be linked to HTML help.  In more detail, to
use packages installed in directory R:\libraries\gm, set

R_LIBS=R:\libraries\gm

in the environment or your .Renviron file or on the command line, or
add the line

.libPaths("R:/libraries/gm")

to your .Rprofile or at the end of R_HOME\etc\Rprofile.

To install a package from source code you need the source-package
distribution installed from @RWVER@-win32.exe (but not the R sources).
The 'R Installation and Administration' manual contains detailed
instructions.


Differences from Unix versions of R
===================================

- R can be interrupted by Esc in Rgui and by Ctrl-C or Ctrl-Break in Rterm:
  Ctrl-C is used for copying in the GUI version.  C-c C-c works
  under NTemacs.

- Command-line editing is always available, but is simpler than
  under readline-based input on Unix.  For Rgui.exe, see the menu item
  'Help | Console', for Rterm.exe the file README.Rterm.

- Paths to files can be specified with "/" or "\\".

- system() is enhanced here and does not automatically use a shell.
  See its help page and that of shell().

- graphics device bmp() is available in this version.


Using package tcltk
===================

The package tcltk supports building graphical interfaces with Tcl/Tk.
"Support Files for Package tcltk" needs to be selected from the
installer for this to work; alternatively you can use an existing
installation of Tcl/Tk 8.6.x by following the instructions in the
rw-FAQ.


Building From Source
====================

See the 'R Installation and Adminstration' Manual
(doc\manual\R-admin.html).


Feedback
========

Please send comments and bug reports to

	R-windows@r-project.org

README for Rterm.exe
====================

Rterm.exe can be used in three distinct modes:

1) Interactively in an MSDOS / Commands window.
2) In batch mode by redirecting its input from a file or pipe.
3) As a no-echo process for ESS mode in NTEmacs with flag --ess.

Its purpose is to provide something similar to the main Unix interface
for R, including a batch capability.  The command-line arguments are
the same as those for RGui.exe and are documented in `An Introduction
to R' in the section `Invoking R under Windows' (--mdi and --sdi are
accepted but do nothing).  Batch use is covered in the rw-FAQ Q2.10.

In interactive use the interpreter can be interrupted by Ctrl-C or
Ctrl-Break.  Input is interpreted as-is except for the keys
interpreted by getline (see below) and that special characters
can be entered by Alt+numerical-key-pad sequences of up to 3 characters,
so Alt+123 and Alt+72 give {H, for example.

Command-line editing and history in interactive use
---------------------------------------------------

Input editing handles a single line and so scrolls long lines left and
right on the same line.  Until the user presses the RETURN key they
can use Emacs-style line editing commands and can traverse the history
of lines previously typed.

Entering printable keys generally inserts new text into the buffer (unless
in overwrite mode, see below).  Other special keys can be used to modify
the text in the buffer.  In the description of the keys below, ^n means
Control-n, or holding the CONTROL key down while pressing "n".  Errors
will ring the terminal bell.  A 'word' is delimited by spaces.

left/right, ^F/^B   : Move cursor forward/backward one character.
up/down,    ^P/^N   : Move to previous/next item on history list.
Home, ^A	: Move cursor to beginning of the line.
End,  ^E 	: Move cursor to end of the line.
ESC-F	: Move cursor forward one word.
ESC-B   : Move cursor backward one word.
^D, DEL	: Delete the character under the cursor.
^H	: Delete the character to the left of the cursor.
^K	: Kill from the cursor to the end of line.
^L	: Redraw current line.
^O	: Toggle overwrite/insert mode. Initially in insert mode. Text
	  added in overwrite mode (including yanks) overwrite
	  existing text, while insert mode does not overwrite.
^R/^S   : Perform incremental reverse/forward search for string on
	  the history list.  Typing normal characters adds to the current
	  search string and searches for a match. Typing ^R/^S marks
	  the start of a new search, and moves on to the next match.
	  Typing ^H or DEL deletes the last character from the search
	  string, and searches from the starting location of the last search.
	  Therefore, repeated DEL's appear to unwind to the match nearest
	  the point at which the last ^R or ^S was typed.  If DEL is
	  repeated until the search string is empty the search location
	  begins from the start of the history list.  Typing ESC or
	  any other editing character accepts the current match and
	  loads it into the buffer, terminating the search.
^T	: Transpose the characters under and to the left of the cursor.
^U      : Deletes the entire line
^W      : Deletes the previous word
^Y	: Yank previously killed text back at current location.  Note that
	  this will overwrite or insert, depending on the current mode.
TAB	: Within quotes, completes the current word as a file name,
	  otherwise as an R object name.  Completion is does as far as
	  can be done unambiguously.  A second press shows alternative
	  completions.  However, if environment variable R_COMPLETION is
	  set to FALSE, this advances to the next tab stop (set at every
	  8th column).
NL, CR  : returns current buffer to the program.

The R for Windows Build Process
===============================

from the point of view of a Unix installer of R.

Compilation of C/Fortran code is done in two pathways.

1) standard and add-on packages, the most similar to Unix.

The primary Makefiles are
$(R_HOME)/etc${R_ARCH}/Makeconf
share/make/winshlib.mk

included in that order.  Some settings in Makeconf are substituted in
etc/Makeconf by fixed/Makefile, taken from MkRules.


2) Everything else, where the primary Makefile is MkRules which is
where all the customization is done.  This is included by all
Makefile.win files in directories above this one and

./Makefile
./cran/Makefile
./fixed/Makefile
./front-ends/Makefile
./getline/Makefile
./installer/Makefile

and replaces Unix's top-level Makeconf.


The largest difference from Unix (even a R-shlib build) is the use of
DLLs, which require the exported symbols to be listed (via nm) in a
.def file and fed to the compiler with the object files for linking.

In recent years DLLs are linked to directly as libraries, but there
remains provision for import libraries via lib%.dll.a: %.def rules.

Making executables has a number of Windows-specific features, done in
front-ends/Makefile:

- A resource compiler is used to compile in version information, an
  icon and a manifest.  Also done for version information in all the
  other DLLs under bin and modules (R.dll Rblas.dll Rgraphapp.dll
  Riconv.dll Rlapack.dll internet.dll lapack.dll).

- LINKFLAGS includes flags for the stack size and to allow addressing
  over 2GB for 32-bit executables.

A resource compiler is used to add version information to the DLLs
under directories bin and modules.

The default is to compile without debug info: this can be enabled by
using 'make DEBUG=T' from this directory, or install add-on packages
with Rcmd INSTALL --debug.  Otherwise DLLs and executables are
stripped.


Link-Time Optimization
======================

To enable LTO for building R set the LTO macro in MkRules.local, to
-flto or e.g. -flto=8 to use 8 threads.

Checking of packages with LTO can be performed by setting the LTO_OPT
macro to -flto in MkRules.local and using Rcmd INSTALL --use-LTO.

For an installed version of R it should suffice to edit the value of
LTO_OPT in the etc/*/Makeconf files or to set it in a personal or site
Makevars file.

[Unlike a Unix-alike, LTO/LTO_OPT are used for Fortran as well as C/C++.]


Cross-compilation
=================

Linux distributions including Fedora, Debian and Ubuntu provide
cross-compilers and many cross-compiled libraries for both 32- and
64-bit Windows.  For example, on Fedora 32 for a 64-bit build one
might install the RPMs

mingw64-binutils
mingw64-bzip2
mingw64-cairo
mingw64-cpp
mingw64-crt
mingw64-filesystem
mingw64-gcc
mingw64-gcc-c++ (not needed for R, but needed for cairo, icu and libtiff)
mingw64-gcc-gfortran
mingw64-headers
mingw64-libgomp
mingw64-libpng
mingw64-libjpeg-turbo
mingw64-libtiff
mingw64-pcre2
mingw64-pkg-config
mingw64-readline
mingw64-tcl
mingw64-termcap
mingw64-tk
mingw64-winpthreads
mingw64-xz-libs
mingw64-zlib

or install the mingw32- variants for a 32-bit build.  At the time of
writing this used GCC 9.2.1.

To build all the compiled code, set BINPREF in MkRules.local, e.g. to

WIN = 64
BINPREF64 = /usr/bin/x86_64-w64-mingw32-

or

WIN = 32
BINPREF = /usr/bin/i686-w64-mingw32-

Setting LTO is supported.

Then in this directory

make MkRules rbuild rpackages-cross

To make the cairo devices, set something like

USE_CAIRO = TRUE
CAIRO_CPPFLAGS = -I/usr/x86_64-w64-mingw32/sys-root/mingw/include/cairo
CAIRO_LIBS = "-lcairo -lpixman-1 -lpng -lz -lgdi32 -lmsimg32"

in MkRules.local and run

make cairodevices


This will link to the DLLs of external software and for libgomp and
pthreads (for OpenMP).

For a more static build, install

mingw64-bzip2-static
mingw64-libpng-static
mingw64-libjpeg-turbo-static
mingw64-libtiff-static
mingw64-pcre2-static
mingw64-winpthreads-static
mingw64-xz-libs-static
mingw64-zlib-static

and remove the corresponding libfoo.dll.a files from
/usr/x86_64-w64-mingw32/sys-root/mingw/lib, and libgomp.dll.a.  (The
build still uses DLLs for libgcc_s_seh and Tcl/Tk).  For a static
build of the Cairo devices one would need other RPMs like

mingw64-cairo-static
mingw64-fontconfig-static
mingw64-freetype-static
mingw64-pixman-static

Rather than remove the .dll.a files, one could experiment with -Wl,-Bstatic.

There are curl and ICU libraries for optional features.  Settings for
Fedora's libs (DLL versions):

USE_LIBCURL = YES
CURL_LIBS = -lcurl

USE_ICU = YES
ICU_LIBS = -licuuc -licui18n -licudata

There is a static version for curl but not ICU.


Cross-building packages
=======================

There is experimental minimal support for cross-building packages.

Copy {bin,etc}/{i386,x64} from this build to a standard Linux build.

Edit the copy of etc/*/Makeconf to have

R_WIN = /path/to/top/directory/of/this/build
R_XTRA_CPPFLAGS = -I"$(R_WIN)/include" -DNDEBUG

Set the environment variable R_CROSS_BUILD to i386 or x64.

Use R CMD INSTALL as usual. (This does not do a staged install nor
test loading.)  --use-LTO is supported if LTO_OPT was set.

R CMD INSTALL --build will produce a zipped installation.

Should a package require external libraries, these can be placed under
LOCAL_SOFT as defined in etc/*/Makeconf in the copy.

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

All the examples given here have worked at some point with 32-bit R,
but are mainly of historical interest.


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

You may if you prefer use Visual C++ to make the DLLs (unless they use
Fortran source!). The notes here were tested with VC++6.

First build the import library Rdll.lib by (from the sources)

	make R.exp

	lib /def:R.exp /out:Rdll.lib
or, depending on your version of VC++
	link /lib /def:R.exp /machine:x86 /out:Rdll.lib

Another way to make R.exp is to use pexports.exe from mingw-utils,
e.g. pexports R.dll > R.exp.

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).

For some applications making use of the R API headers you will need to
build import libraries for Rblas.dll or graphapp.dll and link against
those.

VC++6 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

make R.exp
implib R.lib R.exp

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\R-2.3.0\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 libstdc++).  Use of
C++ I/O may or may not work, and has been seen to crash R.

To use F90 or F95, see `Writing R Extensions'.

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 gfortran 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 used null-terminated strings. (g77 was in
GCC 3.x.y, superseded by gfortran.)

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