The R Project SVN R

Rev

Rev 11368 | Blame | Compare with Previous | Last modification | View Log | Download | RSS feed 

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html lang="en">
<head>
<meta name="generator" content="HTML Tidy, see www.w3.org">
<title>R for Windows FAQ</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="R for Windows FAQ">
<meta name="generator" content="makeinfo 4.0">
<link href="http://texinfo.org/" rel="generator-home">
<title>R for Windows FAQ</title>
</head>
<body>
<h1 align="center">R for Windows FAQ</h1>

<h2>Version for <tt>rw1020</tt></h2>

<address>B. D. Ripley</address>

<hr>
<p>...Table of Contents... <a name="Top"></a> </p>

<hr>
<a name="Introduction"></a> 

<h1>1 Introduction</h1>

<p>This FAQ is for the Windows port of R: it describes features
specific to that version. The main R FAQ can be found at</p>

<pre>
<a href=
"http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html">http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html</a>.
</pre>

<p>The information here applies only to recent versions of R for
Windows, (<code>rw1020</code> or later); the current version is
often called something like <code>rw1020</code> (although not
officially).</p>

<hr>
<a name="Installation%20and%20Usage"></a> 

<h1>2 Installation and Usage</h1>

<a name="Where%20can%20I%20find%20the%20latest%20version%3f"></a> 

<h2>2.1 Where can I find the latest version?</h2>

<p>Go to any CRAN site (see <a href=
"http://cran.r-project.org/mirrors.html">
http://cran.r-project.org/mirrors.html</a> for a list), navigate to
the <code>bin/windows/windows-NT/base</code> directory and collect
the files you need. You will need at least the files</p>

<pre>
      rwXxxxb1.zip rwXxxxb2.zip
      rwXxxxh.zip (text help) or rwXxxxch.zip (Compiled HTML help)
</pre>

<p>and you may want <code>rwXxxxwh.zip</code> (the Windows help
files) or <code>rwXxxxw.zip</code> (the HTML format help files),
<code>rwXxxxl.zip</code> (the LaTeX format help files, used for
offline printing), or <code>rwXxxxd?.zip</code> (the draft manuals,
in PDF).</p>

<p>Optionally, you can download the installer, <code>
rwinst.exe</code>. <a name=
"How%20do%20I%20install%20R%20for%20Windows%3f"></a></p>

<h2>2.2 How do I install R for Windows?</h2>

<p>First, you need Windows 95/98/ME/NT4/2000: Windows 3.11+win32s
will not work. Your file system must allow long file names (as is
likely except perhaps for some network-mounted systems).</p>

<p>The simplest way is to run the installer (double-click on the
icon for <code>rwinst.exe</code> and navigate its wizard-like
pages). Alternatively, choose a location and unzip the zip files
(with a tool that preserves long file names and the directory
structure: we recommend the INFO-ZIP project's <code>unzip</code>).
All the files will unpack into a directory called <code>
rwXxxx</code>, for some <code>Xxxx</code>.</p>

<p>Choose a working directory for R. Make a shortcut to <code>
rwXxxx\bin\Rgui.exe</code> on your desktop or somewhere on the
Start menu file tree. Right-click the shortcut, select
Properties... and change the `Start in' field to your working
directory.</p>

<p>You may also want to add command-line arguments at the end of
the Target field, for example <code>--max-mem-size=40M</code>. You
can also set environment variables at the end of the Target field,
for example <code>R_LIBS=e:/R/library</code>. <a name=
"How%20do%20I%20run%20it%3f"></a></p>

<h2>2.3 How do I run it?</h2>

<p>Just double-click on the shortcut you prepared at
installation.</p>

<p>If you want to set up another project, make a new shortcut or
use the existing one, and change the `Start in' field of the
Properties. <a name=
"How%20can%20I%20keep%20workspaces%20for%20different%20projects%20in%20different%20directories%3f">
</a></p>

<h2>2.4 How can I keep workspaces for different projects in
different directories?</h2>

<p>Create a separate shortcut for each project: see Q2.3. All the
paths to files used by R are relative to the starting directory, so
setting the `Start in' field automatically helps separate projects.
<a name="How%20do%20I%20print%20from%20R%3f"></a></p>

<h2>2.5 How do I print from R?</h2>

<p>It depends what you want to print.</p>

<ul>
<li>You can print the graphics window from its menu or by using
<code>dev.print()</code>.</li>

<li>You can print from the R console or pager by <code>File |
Print</code>. (This will print the selection if there is one,
otherwise the whole console or pager contents.)</li>

<li>You can print help files from the pager or HTML browser.</li>

<li>If you have configured <code>RHOME\bin\helpPRINT.bat</code> and
have latex installed you can print help files by <code>
help(fn_name, offline=TRUE)</code>.</li>
</ul>

<a name="Can%20I%20use%20R%20BATCH%3f"></a> 

<h2>2.6 Can I use <code>R BATCH</code>?</h2>

<p>Yes, if you have Perl installed. The Windows analogue is <code>
Rcmd BATCH</code>: use <code>Rcmd BATCH --help</code> for full
details.</p>

<p>Otherwise you can set up a batch file using <code>
Rterm.exe</code>. A sample batch file might contain (as one
line)</p>

<pre>
path_to_R\bin\Rterm.exe --no-restore --no-save &lt; %1 &gt; %1.out
</pre>

<a name="Can%20I%20use%20rwXxxx%20with%20ESS%20and%20emacs%3f"></a>


<h2>2.7 Can I use rwXxxx with ESS and emacs?</h2>

<p>Yes. The latest versions of ESS (e.g. 5.1.18) come with support
for this version of R, and there is support for interrupting the R
process from ESS (by <code>C-c C-c</code>).</p>

<p>For help with ESS, please send email to <a href=
"mailto:ESS-help@stat.ethz.ch">ESS-help@stat.ethz.ch</a>, not the R
mailing lists. <a name=
"What%20are%20HOME%20and%20working%20directories%3f"></a></p>

<h2>2.8 What are HOME and working directories?</h2>

<p>Several places in the documentation use these terms.</p>

<p>The working directory is the directory from which <code>
Rgui</code> or <code>Rterm</code> was launched, unless a shortcut
was used when it is given by the `Start in' field of the shortcut's
properties. You can find this from R code by the call <code>
getwd()</code>.</p>

<p>The home directory is set as follows:<br>
If environment variable <code>R_USER</code> is set, its value is
used.<br>
Otherwise if environment variable <code>HOME</code> is set, its
value is used.<br>
Otherwise if environment variables <code>HOMEDRIVE</code> and
<code>HOMEPATH</code> are set, the value is <code>
${HOMEDRIVE}${HOMEPATH}</code>.<br>
If all of these fail, the current working directory is used.</p>

<p>You can find this from R code by <code>
Sys.getenv("R_USER")</code>.</p>

<hr>
<a name="Packages"></a> 

<h1>3 Packages</h1>

<a name=
"Can%20I%20install%20packages%20(libraries)%20in%20this%20version%3f">
</a> 

<h2>3.1 Can I install packages (libraries) in this version?</h2>

<p>Yes, of course. The easy way is to see if a pre-compiled binary
version of the package is available: look on CRAN at <code>
bin/windows/windows-NT/contrib</code>. If there is, download the
zip file and unpack it in the <code>rwXxxx\library</code>
directory, using <code>unzip</code> or similar, or using the
installer <code>rwinst.exe</code>. Perhaps even easier is to use
the R function <code>install.packages()</code>: check out its help
page.</p>

<p>If there is not a binary version or that is not up-to-date or
you prefer compiling from source, get <code>rwXxxxsp.zip</code>
from the distribution (see Q1.1) and unpack it in <code>
rwXxxx</code>. Then <code>cd src\gnuwin32</code> and read <code>
README.packages</code>. You will need to collect and install
several tools to use this. Once you have done so, installation is
easy: just run <code>Rcmd INSTALL pkgname</code>. To check the
package (run all the examples on its help pages and in its test
suite, if any) use <code>Rcmd check pkgname</code>. <a name=
"I%20don't%20have%20permission%20to%20write%20to%20the%20rwXxxx%2flibrary%20directory">
</a></p>

<h2>3.2 I don't have permission to write to the <code>
rwXxxx/library</code> directory.</h2>

<p>You can install packages anywhere and use the environment
variable <code>R_LIBS</code> to point to the library location(s).
You can also set the R variable <code>.lib.loc</code> in your
<code>.Rprofile</code> or when running R.</p>

<p>Suppose your packages are installed in <code>p:\mylibs</code>.
Then you can EITHER</p>

<pre>
set the environment variable R_LIBS to p:\mylibs
</pre>

<p>OR put in the <code>.Rprofile</code> in the working directory or
your home directory</p>

<pre>
.lib.loc &lt;- c("p:/mylibs", .Library)
</pre>

<p>OR use a package by, e.g.</p>

<pre>
library(MASS, lib.loc="p:/mylibs")
</pre>

<p>How you set an environment variable is system specific: in
Windows 9x you can set them in autoexec.bat or in an MS-DOS window
from which you launch <code>Rgui</code> / <code>Rterm</code>. Under
Windows NT/2000 you can use the control panel or the properties of
`My Computer'. You can also set them on the command line, for
example in the shortcut you could have</p>

<pre>
path_to_R\bin\Rgui.exe --vsize=10M R_LIBS=e:/R/library
</pre>

<p>and you can set variables in a file <code>.Renviron</code> in
the working directory or your home directory, for example</p>

<pre>
R_LIBS=e:/R/library
R_VSIZE=10M
R_NSIZE=400k
</pre>

<p>The order of precedence is the command line (flags before
variables) then <code>.Renviron</code> then the inherited
environment. <a name=
"The%20packages%20I%20installed%20do%20not%20appear%20in%20the%20HTML%20help%20system">
</a></p>

<h2>3.3 The packages I installed do not appear in the HTML help
system.</h2>

<p>HTML help only works for packages installed in <code>
rwXxxx\library</code>.</p>

<p>To update the HTML help files after you have installed a binary
package, run at the R prompt.</p>

<pre>
&gt; link.html.help()
</pre>

<p>(Using <code>install.packages()</code> does this for you. The
source-code installation also does this automatically, and if you
have that installed you can use (preferably)</p>

<pre>
cd rwXxxx\src\gnuwin32\help
make indices
</pre>

<p>instead.) <a name=
"My%20functions%20are%20not%20found%20by%20the%20HTML%20help%20search%20system.">
</a></p>

<h2>3.4 My functions are not found by the HTML help search
system.</h2>

<p>The following conditions need to hold for functions in a package
you installed.</p>

<ul>
<li>the package is installed in <code>rwXxxx\library</code>.</li>

<li>the package contains a <code>CONTENTS</code> file in top-level
directory.</li>

<li>you updated the indices as described in the answer to Q3.3
after installing the package.</li>
</ul>

<p>If those all hold true, this works for us. <a name=
"Package%20TclTk%20does%20not%20work."></a></p>

<h2>3.5 Package TclTk does not work.</h2>

<p>For package tcltk to work (try <code>demo(tkdensity)</code> or
<code>demo(tkttest)</code>) you need to have Tcl installed.
Download <code>tcl832.exe</code> (or use <code>tcl831.exe</code> if
you already have it) from &lt;<code>dev.scriptics.com</code>&gt;
and install it. (That will put the <code>bin</code> directory
containing the Tcl and Tk DLLs in your path). You then need to set
the environment variable <code>TCL_LIBRARY</code>, to something
like <code>c:/Program Files/Tcl/lib/tcl8.3</code>. (The startup
code for the package will warn you if this is unset, and Q3.2
explains how to set them.)</p>

<hr>
<a name="Windows%20Features"></a> 

<h1>4 Windows Features</h1>

<a name=
"What%20should%20I%20expect%20to%20behave%20differently%20from%20the%20Unix%20version%20of%20R%3f">
</a> 

<h2>4.1 What should I expect to behave differently from the Unix
version of R?</h2>

<ul>
<li>R commands can be interrupted by &lt;Esc&gt; in <code>
Rgui.exe</code> and &lt;Ctrl-break&gt; or &lt;Ctrl-C&gt; in <code>
Rterm.exe</code>: &lt;Ctrl-C&gt; is used for copying in the GUI
version.</li>

<li>Command-line editing is always available, but is simpler than
the readline-based editing on Unix. For <code>Rgui.exe</code>, the
menu item `Help | Console' will give details.</li>

<li>Using <code>help.start()</code> does not automatically send
help requests to the browser: use <code>options(htmlhelp=T)</code>
to turn this on.</li>

<li>The HTML help system can only access packages installed in the
standard place.</li>

<li>Paths to files (e.g. in <code>source()</code>) can be specified
with either "/" or "\\".</li>

<li><code>system()</code> is slightly different: see its help page
and that of <code>shell()</code>.</li>
</ul>

<a name=
"I%20hear%20about%20some%20nifty%20features.%20Please%20tell%20me%20about%20them!">
</a> 

<h2>4.2 I hear about some nifty features: please tell me about
them!</h2>

<p>You have read the <code>README</code>? There are file menus on
the R console, pager and graphics windows. You can source and save
from those menus, and copy the graphics to <code>png</code>, <code>
jpeg</code>, <code>bmp</code>, <code>postscript</code> or <code>
metafile</code>. There are right-click menus giving shortcuts to
menu items, and optionally toolbars with buttons giving shortcuts
to frequent operations.</p>

<p>If you resize the R console the <code>options(width=)</code> is
automatically set to the console width (unless disabled in the
configuration file).</p>

<p>The graphics has a history mechanism. As the README says:</p>

<blockquote>`The History menu allows the recording of plots. When
plots have been recorded they can be reviewed by &lt;PgUp&gt; and
&lt;PgDn&gt;, saved and replaced. Recording can be turned on
automatically (the Recording item on the list) or individual plots
can be added (Add or the &lt;INS&gt; key). The whole plot history
can be saved to or retrieved from an R variable in the global
environment. 

<p>There is only one graphics history shared by all the windows
devices.'</p>
</blockquote>

<p>The R console and graphics windows have configuration files
stored in the <code>RHOME\etc</code> directory called <code>
Rconsole</code> and <code>Rdevga</code>; you can keep personal
copies in your <code>HOME</code> directory. They contain comments
which should suffice for you to edit them to your preferences. For
more details see <code>?Rconsole</code>. There is a Preferences
editor invoked from the <code>Edit</code> menu which can be used to
edit the file <code>Rconsole</code>.</p>

<hr>
<a name="Workspaces"></a> 

<h1>5 Workspaces</h1>

<a name=
"My%20workspace%20gets%20saved%20in%20a%20strange%20place.%20how%20do%20I%20stop%20this%3f">
</a> 

<h2>5.1 My workspace gets saved in a strange place: how do I stop
this?</h2>

<p>Have you changed the working directory?: see Q5.2. <a name=
"How%20do%20I%20store%20my%20workspace%20in%20a%20different%20place%3f">
</a></p>

<h2>5.2 How do I store my workspace in a different place?</h2>

<p>Use the `File | Change Dir' menu item to select a new working
directory: this defaults to the last directory you loaded a file
from. The workspace is saved in the working directory. You can also
save a snapshot of the workspace from the `Save Workspace' menu
item. <a name=
"Can%20I%20load%20workspaces%20saved%20under%20Unix%2fGNU-Linux%3f">
</a></p>

<h2>5.3 Can I load workspaces saved under Unix/GNU-Linux?</h2>

<p>Yes. The converse (saving on Windows, loading on Unix) also
works.</p>

<hr>
<a name="The%20R%20Console%20and%20Fonts"></a> 

<h1>6 The R Console and Fonts</h1>

<a name=
"I%20would%20like%20to%20be%20able%20to%20use%20Japanese%20fonts"></a>


<h2>6.1 I would like to be able to use Japanese fonts</h2>

<p>for example, in the console and to annotate graphs.</p>

<p>We believe this is possible by setting suitable fonts in the
Rconsole and Rdevga configuration files (see Q4.2). You can specify
additional fonts in Rdevga, and use them by</p>

<pre>
par(font=, font.lab=, font.main=, font.sub=)
</pre>

<p>Nineteen fonts are specified (as 1 to 19) by default: you can
add to these (up to 13 more) or replace them. <a name=
"I%20don't%20see%20characters%20with%20accents%20at%20the%20R%20console">
</a></p>

<h2>6.2 I don't see characters with accents at the R console, for
example in ?text.</h2>

<p>You need to specify a font in Rconsole (see Q4.2) that supports
latin1 encoding. The default, <code>Courier New</code>, does on our
systems, as does <code>FixedSys</code>. This may be a problem in
other locales, especially for non-Western European languages. <a
name=
"The%20output%20to%20the%20console%20seems%20to%20be%20delayed">
</a></p>

<h2>6.3 When using Rgui the output to the console seems to be
delayed.</h2>

<p>This is deliberate: the console output is buffered and
re-written in chunks to be less distracting. You can turn buffering
off or on from the Misc menu or the right-click menu:
&lt;Ctrl-W&gt; toggles the setting.</p>

<p>If you are sourcing R code or writing from a function, there is
another option. A call to the R function <code>
flush.console()</code> will write out the buffer and so update the
console. <a name="Long%20lines%20seem%20to%20be%20truncated.">
</a></p>

<h2>6.4 Long lines in the console or pager are truncated.</h2>

<p>They only <strong>seem</strong> to be truncated: that $ at the
end indicates you can scroll the window to see the rest of the
message. Use the horizontal scrollbar or the &lt;CTRL+arrow&gt;
keys to scroll horizontally.</p>

<hr>
<a name="Building%20from%20Source"></a> 

<h1>7 Building from Source</h1>

<a name="How%20can%20I%20compile%20R%20from%20source%3f"></a> 

<h2>7.1 How can I compile R from source?</h2>

<p>Get the R sources. Suppose you want to compile R-1.2.0.</p>

<pre>
tar zxvf R-1.2.0.tgz
cd R-1.2.0
cd src\gnuwin32
</pre>

<p>Now read the <code>INSTALL</code> file and set up all the tools
needed. Then you can just use <code>make</code>, sit back and wait.
(A complete build takes about 15 minutes on a 300MHz PII with a
fast local disc.)</p>

<p>You may need to compile under a case-honouring file system: we
found that a <code>samba</code>-mounted file system (which maps all
file names to lower case) did not work. <a name=
"How%20do%20I%20debug%20code%20that%20I%20have%20compiled%20and%20dyn.load-ed%3f">
</a></p>

<h2>7.2 How do I debug code that I have compiled and
dyn.load-ed?</h2>

<p>First, build a version of the R system with debugging
information by</p>

<pre>
make clean
make DEBUG=T
</pre>

<p>and make a debug version of your package by</p>

<pre>
make pkgclean-mypkg
make DEBUG=T pkg-mypkg
</pre>

<p>Then you can debug by</p>

<pre>
gdb /path/to/rwXxxx/bin/Rgui.exe
</pre>

<p>However, note</p>

<ul>
<li>gdb will only be able to find the source code if we run in the
location where the source was compiled
(<code>rwXxxx/src/gnuwin32</code> for the main system, <code>
rwXxxx/src/library/mypkg/src</code> for a package), unless told
otherwise by the <code>directory</code> command. It is most
convenient to set a list of code locations via <code>
directory</code> commands in the file <code>.gdbinit</code> in the
directory from which <code>gdb</code> is run.</li>

<li>It is only possible to set breakpoints in a DLL after the DLL
has been loaded. So a way to examine the function <code>
tukeyline</code> in package <code>eda</code> might be 

<pre>
     gdb ../../../../bin/Rgui.exe
     (gdb) break WinMain
     (gdb) run
     [ stops with R.dll loaded ]
     (gdb) break R_ReadConsole
     (gdb) continue
     [ stops with console running ]
     (gdb) continue
     Rconsole&gt; library(eda)
     (gdb) break tukeyline
     (gdb) clear R_ReadConsole
     (gdb) continue
</pre>

<p>Fortran symbols need an underline appended.</p>
</li>

<li>Windows has little support for signals, so the usual idea of
running a program under a debugger and sending it a signal to
interrupt it and drop control back to the debugger does not work
with <code>mingw32</code> version of <code>gdb</code>. It does
often work with the <code>cygwin</code> version.</li>

<li>We have seen examples in debugging problems with Windows events
that the <code>cygwin gdb</code> was able to catch but which
terminated the <code>mingw32 gdb</code>.</li>
</ul>

<p>If you have an X server available on the PC, there is a version
of <code>DDD</code> available that runs under the cygwin emulation
layer (follow the links at <a href=
"http://sources.redhat.com/cygwin">
http://sources.redhat.com/cygwin</a>) and provides a graphical user
interface to <code>gdb</code>. Another (Windows-native) GUI for
<code>gdb</code> is <code>Insight</code>, part of the latest <code>
cygwin</code> version of <code>gdb</code> <a name=
"How%20do%20I%20include%20C++%20code%3f"></a></p>

<h2>7.3 How do I include C++ code?</h2>

<p>You need to do two things:</p>

<p>(a) Write a wrapper to export the symbols you want to call from
R as <code>extern "C"</code>.</p>

<p>(b) Include the C++ libraries in the link to make the DLL.
Suppose <code>X.cc</code> contains your C++ code, and <code>
X_main.cc</code> is the wrapper, as in the example in `<em>Writing
R Extensions</em>'. Then build the DLL by (<code>gcc</code>)</p>

<pre>
...\bin\Rcmd SHLIB X.cc X_main.cc
</pre>

<p>or (VC++, which requires extension <code>.cpp</code>)</p>

<pre>
cl /MT /c X.cpp X_main.cpp
link /dll /out:X.dll /export:X_main X.obj X_main.obj
</pre>

<p>or (Borland C++, which also requires extension <code>
.cpp</code>)</p>

<pre>
bcc32 -u- -WDE X.cpp X_main.cpp
</pre>

<p>and call the entry point(s) in <code>X_R</code>, such as <code>
X_main</code>. Construction of static variables will occur when the
DLL is loaded, and destruction when the DLL is unloaded, usually
when R terminates.</p>

<p>Note that you will not see the messages from this example in the
GUI console: see the next section.</p>

<p>This example is in package <code>cxx_0.0-0.tar.gz</code> in the
<code>src/contrib/Devel</code> section on CRAN, and that can be
compiled as package in the usual way on Windows. <a name=
"The%20output%20from%20my%20C%20code%20disappears."></a></p>

<h2>7.4 The output from my C code disappears. Why?</h2>

<p>The <code>Rgui.exe</code> console is a Windows application:
writing to <code>stdout</code> or <code>stderr</code> will not
produce output in the console. (This will work with <code>
Rterm.exe</code>.) Use <code>Rprintf</code> or <code>
REprintf</code> instead. These are declared in header file <code>
R_ext/PrtUtil.h</code>.</p>

<p>Note that output from the console is delayed (see <a href=
"#The%20output%20to%20the%20console%20seems%20to%20be%20delayed">
The output to the console seems to be delayed</a>), so that you
will not normally see any output before returning to the R prompt.
<a name="The%20output%20from%20my%20Fortran%20code%20disappears.">
</a></p>

<h2>7.5 The output from my Fortran code disappears. Why?</h2>

<p>Writing to Fortran output writes to a file, not the <code>
Rgui</code> console. Use one of the subroutines <code>
dblepr</code>, <code>intpr</code> or <code>realpr</code> documented
in the <em>`Writing R Extensions'</em> manual. <a name=
"The%20console%20freezes%20when%20my%20compiled%20code%20is%20running">
</a></p>

<h2>7.6 The console freezes when my compiled code is running.</h2>

<p>The console, pagers and graphics window all run in the same
thread as the R engine. To allow the console etc to respond to
Windows events, call <code>R_ProcessEvents()</code> periodically
from your compiled code. If you want output to be updated on the
console, call <code>R_FlushConsole()</code> and then <code>
R_ProcessEvents()</code>.</p>

<hr width="100%">
<address>Last edited 2000 November 25 by Brian Ripley <code><a
href="mailto:ripley@stats.ox.ac.uk">
ripley@stats.ox.ac.uk</a></code></address>
</body>
</html>