\input texinfo
@c %**start of header
@setfilename RMacOSX-FAQ.info
@settitle R for Mac OS X FAQ
@setchapternewpage on
@set FAQ-YEAR 2004
@set FAQ-VERSION 1.9-2 @value{FAQ-YEAR}-06-08
@set REL-VERSION 1.9.0
@documentlanguage en
@documentencoding ISO-8859-1
@c %**end of header

@c % makeinfo -D UseExternalXrefs --html --force --no-split RMacOSX-FAQ.texi

@dircategory Programming
@direntry
* R for Mac OS X FAQ: (MacOSX-FAQ).               The FAQ on R for Mac OS X
@end direntry

@finalout

@macro SPLUS{}
@sc{S-Plus}
@end macro

@macro R{}
@acronym{R}
@end macro

@macro CRAN{}
@acronym{CRAN}
@end macro

@macro HTML{}
@acronym{HTML}
@end macro

@macro FORTRAN{}
FORTRAN
@end macro

@macro XML{}
@acronym{XML}
@end macro

@macro XSL{}
@acronym{XSL}
@end macro

@titlepage
@title R for Mac OS X @acronym{FAQ}
@subtitle Frequently Asked Questions on R for Mac OS X
@subtitle Version @value{FAQ-VERSION}
@author Stefano M. Iacus
@end titlepage

@ifinfo
@c We do not really see this in info, but in plain text output.
R for Mac OS X FAQ						 @*
Frequently Asked Questions on R for Mac OS X@*
Version @value{FAQ-VERSION}      @*
Stefano M. Iacus                 @*

@sp 2
@end ifinfo

@ifnothtml
@contents
@end ifnothtml

@ifnottex
@node Top, Introduction, (dir), (dir)
@top R for Mac OS X FAQ
@ifhtml
@html
<h2>Frequently Asked Questions on R for Mac OS X</h2>
<h2>Version @value{FAQ-VERSION}</h2>
<address>Stefano M. Iacus</address>
<p><p><hr><p>
@end html
@end ifhtml
@end ifnottex

@menu
* Introduction::                    
* Building R from sources::
* Command line version of R::                     
* R with Aqua GUI::                     
* How to install packages::                     
* R and external applications::                 
* The near future of the Aqua GUI::               
* Aqua GUI Bugs::       
* Quartz device::               
* TclTk issues::               
* Additional resources::
* Acknowledgments::       
* Sparse questions::
@end menu

@node Introduction, Building R from sources, Top, Top
@chapter Introduction
This is a very first try of writing a R for Mac OS X. I hope to finish it in time for R-1.9.0.
In any case, please send me requests/questions you would like answers on.

This document contains information on how to build @R{} from sources, how to install and run it.
It also contains a user guide to the Aqua GUI version of @R{}.
@menu
* How many versions of R for Mac OS X?::                  
* What machines does R for Mac OS X run on?::  
* How can R for Mac OS X be obtained and installed?::      
@end menu

@node How many versions of R for Mac OS X?, What machines does R for Mac OS X run on?, , Introduction
@section How many versions of R for Mac OS X?

There is currently only one version of R for Mac OS X.
But R on Mac OS X can be used as a command-line application (@pxref{Command line version of R}), like on any
other unix-like system, or via the Aqua GUI (@pxref{R with Aqua GUI}). This second approach in using R
for Mac OS X is mostly preferred by "traditional" Macintosh users.

@node What machines does R for Mac OS X run on?, How can R for Mac OS X be obtained and installed?, How many versions of R for Mac OS X?, Introduction
@section What machines does R for Mac OS X run on?

R for Mac OS X requires Mac OS X version 10.2 or higher to run. The latest version of the system is
always preferable though. We do not support Mac OS X version 10.1.

@node How can R for Mac OS X be obtained and installed?, , What machines does R for Mac OS X run on?, Introduction
@section How can R for Mac OS X be obtained and installed?

@node Building R from sources, Command line version of R, Introduction, Top
@chapter Building R from sources
@menu
* What is needed to build R::
* How to configure and build R::
* How to install R::
* How to build and install the Aqua GUI::
@end menu

@node What is needed to build R, How to configure and build R, , Building R from sources
@section What is needed to build R
@menu
* the C/C++ compiler gcc 3.3::
* the Fortran compiler g77 for gcc 3.3::
* the libreadline 4.3 (optional)::
* the X11 window server (optional)::
* the X11 TclTk headers and libraries (optional)::
* the Aqua TclTk headers and libraries (optional)::
* a TeX suite of tools for documentation (optional)::
@end menu

@node the C/C++ compiler gcc 3.3
@subsection the C/C++ compiler gcc 3.3
If you have Mac OS X 10.3 (aka Panther) you just need to install the software inside the Xcode Tools CD 
(which is CD number 4). This is only true if you bought Panther. In most of the cases you have 
Panther already installed on your brand new machine, which means that you don't have the forth 
Developer CD. You should take it from Apple Developer Connection site (@pxref{Apple Developer Connection}): in the
download section, look for Xcode Tools v 1.1 or above.

If you are using Mac OS X 10.2 (aka Jaguar) then you should download and install the 
Apple Developers Tools Dec 2002 including the latest updates which dates August 2003. Either it comes 
on a separate CD with your Mac, either you can download these  from the Apple Developer Connection site (@pxref{Apple Developer Connection})
In either cases be sure you have gcc version 3.3 just by typing in a Terminal window 
@example
gcc -vv
@end example

@node the Fortran compiler g77 for gcc 3.3
@subsection the Fortran compiler g77 for gcc 3.3
You need to install a version of the g77 Fortran compiler which is built for gcc 3.3. 
The following instructions apply to binaries coming from  HPC for Mac OS X page @uref{http://hpc.sourceforge.net}. 
Please take care: there are two versions of the g77 binaries, one for Jaguar and one for Panther. 
Use the appropriate one.

Once you have the binaries, please do the following (you'll be asked for a root password):
cd to the download folder and type
@example
sudo tar -zxvf g77v3.4-bin.tar.gz -C /
rehash
@end example
It installs everything in @emph{/usr/local}. The name of the .tar.gz archive can be different, see the related web page.


@node the libreadline 4.3 (optional)
@subsection the libreadline 4.3 (optional)
This library is optional. 
You need this library to be able to retrieve history using use arrow keys or for tab completion of filenames
when you run R as a command line tool. The original source archive is located at GNU Org web page @uref{ftp://www.gnu.org}. 
You need to modify the original file @emph{shlib/Makefile.in} in order to make it
work under Mac OS X 10.2.x and later (this is because libreadline needs to be linked against
@emph{-lncurses -lcc_dynamic}). If you can do better at configure time working on the original archive 
let me know. I suggest you to download my patched version from @uref{http://www.economia.unimi.it/R}. 
Once you have done, please do the following (you'll be asked for a root password):
uncompress the archive, cd inside the folder and type the following
@example
./configure
make
sudo make install
@end example
It installs everything in @emph{/usr/local}.
These instructions apply to both Jaguar and Panther.

@node the X11 window server (optional)
@subsection the X11 window server (optional)
If you have Panther, you probably have the X11 Window server already installed on your system. 
This is what you need to run a version of R with the capability of using the X11 device, but it isn't sufficient
if you want to build it.
You need to install the additional X11 SDK package from the Xcode Tools CD. 
Please note: the installer on the Xcode Tools CD does not install the X11 SDK by default: 
you should look inside the Xcode Tools CD and install manually the X11 SDK.

If you have Jaguar, you'll need to install both the X11 Window server and the X11 SDK package from 
the XFree86 web page.  Apple site only supports the latest version of his OS (at the moment Panther).
Users report that other version of X11 Window Servers (other than the one distributed by Apple) work as well.

@node the X11 TclTk headers and libraries (optional)
@subsection the X11 TclTk headers and libraries (optional)
You need to download the sources of the Tcl and Tk 8.4.x packages to build yourself the sources. 
The original sources can be found on the official TclTk web page @uref{http://www.tcl.tk/software/tcltk/8.4.html}.
Please do the following respecting the sequence (you'll be asked for a root password). These are examples for version 8.4.4
of the Tcl and Tk sources, you'll probably find new version on the web page, thus only the name of the .tar.gz archives
changes.


For Tcl: download the tlc 8.4 sources, cd inside the folder where you have downloaded the archive and
type:
@example
tar zxf tcl8.4.4-src.tar.gz
cd tcl8.4.4/unix/
./configure
make
sudo make install
@end example

For Tk: download the tk 8.4 sources, cd inside the folder where you have downloaded the archive and type:
@example
tar zxf tk8.4.4-src.tar.gz
cd tk8.4.4/unix/
./configure
make
sudo make install
@end example

@node the Aqua TclTk headers and libraries (optional)
@subsection the Aqua TclTk headers and libraries (optional)
Once you have installed the AquaTclTk libraries and headers files you should configure @R{} using this additional
arguments
@example
--with-tcl-config=/Library/Frameworks/Tcl.framework/tclConfig.sh 
--with-tk-config=/Library/Frameworks/Tk.framework/tkConfig.sh
TCLTK_LIBS='-framework Tcl -framework Tk'
TCLTK_CPPFLAGS='-I/Library/Frameworks/Tcl.Framework/Headers -I/Library/Frameworks/Tk.Framework/Headers'
@end example

@node a TeX suite of tools for documentation (optional)
@subsection a TeX suite of tools for documentation (optional)
There is a nice installer, called the i-installer II, that allows you to install a complete 
teTeX distribution. You can find details on the i-installer at @uref{http://www.rna.nl/ii.html}. 
The teTeX is one of the i-Packages.

@node How to configure and build R, How to install R, What is needed to build R, Building R from sources  
@section How to configure and build R
Download the latest sources of R from @CRAN{}. Unpack the archive with tar -zxf @emph{name_of_R_sources_archive} and cd
inside the R sources directory. Then you need to configure R for your system and build R. 
Just type
@example
./configure --with-blas='-framework vecLib' --with-lapack --with-aqua 
make
@end example
This will configure R to be built as a Framework to be installed inside your @emph{/Library/Frameworks} directory with the name 
@emph{R.framework}. You can change the default location of the @emph{R.framework} 
installation at configure time by specifying the flag @emph{--enable-R-framework[=DIR]}, i.e. 
with something like
@example
./configure --with-blas='-framework vecLib' --with-lapack 
            --with-aqua --enable-R-framework=FOO
@end example
and the final destination of the @emph{R.framework} will be @emph{FOO/R.framework}, which means that you 
don't have to specify the @emph{R.framework} text in the path. 

@node How to install R, How to build and install the Aqua GUI, How to configure and build R, Building R from sources
@section How to install R
A standard installation of R requires you have built it as a Framework. At this point just type (a root 
password will be required):
@example
sudo make install
@end example
and all will be installed in @emph{/Library/Frameworks}.
You can decide to change the R.framework destination by using the @emph{prefix} option specifying the 
final destination.
@smallexample
sudo make prefix=/where/you/want/R.framework/to/go install
@end smallexample
As in the above, you don't need to specify the name @emph{R.framework} in the path.

@node  How to build and install the Aqua GUI,  ,How to install R, Building R from sources
@section How to build and install the Aqua GUI
At the moment, there is nothing special to  do to build the Aqua GUI.
You just need to install it using
@example
make install-aqua
@end example
and it will install the @emph{R.app} application in the @emph{Applications} folder on your system.
The install procedure fails if the @file{R.framework} has not been installed first.


@node Command line version of R, R with Aqua GUI, Building R from sources, Top
@chapter Command line version of R
The command line version of @R{} is nothing but a classic unix-like implementation of @R{}. So general 
documentation for @R{} applies to this version as well.
On each release (and patched-release) ready to use binaries are distributed through @CRAN{}.
These binaries come with a common installer used by R with Aqua GUI so please read
the related notes (@pxref{How to get R with Aqua GUI}).
To use @R{} you probably need to add a symbolic link on your System as the @R{} binary is 
located inside the framework.
Suppose you have the @emph{/usr/local/bin} directory on your System, than you should just 
type in your Terminal (a root password is required)
@smallexample
sudo ln -s /Library/Frameworks/R.framework/Resources/R /usr/local/bin/R
@end smallexample
Assuming that you have @emph{/usr/local/bin} in your @emph{PATH} environment variable, you'll be able to launch R from any location
on your System just by typing @emph{R}.
In this way, when you install a new version of the @emph{R.framework} this link will point to the latest R binary.

@node R with Aqua GUI
@chapter R with Aqua GUI
@menu
* How to get R with Aqua GUI::
* How to install the Aqua GUI::
* The R Console::
* The Menus::
* Preferences::
* The near future of the Aqua GUI::
* Aqua GUI Bugs::
@end menu

@node How to get R with Aqua GUI
@section How to get R with Aqua GUI
The @file{bin/macosx} directory of a @CRAN{} site contains a standard
Apple installer package named @file{R.dmg.sit} compressed in Aladdin
Stuffit format.  Once downloaded, uncompressed and executed, the
installer will install the current non-developer release of R.  R  is
a native Mac OS X Darwin version of R with an Aqua GUI. 
Inside
@file{bin/macosx/@var{x}.@var{y}} there are prebuilt binary packages to
be used with R corresponding to the ``@var{x}.@var{y}'' release of
R. The installation of these packages is available through the
``Package'' menu of the Aqua GUI (@pxref{Packages Menu}). 

@node How to install the Aqua GUI
@section How to install the Aqua GUI

@node The R Console
@section The R Console
In this section you'll find general informations on the Aqua GUI. For specific @R{} tasks that
can be done via the Aqua GUI using menus you should read below (@pxref{The Menus}). 
@menu 
* The Input and the Output::
* Copy and Paste::
* The current and startup working directories::
* Resizing the R Console::
* Input and Output text colors::
@end menu


@node The Input and the Output
@subsection The Input and the Output
The current design of the R Console is to have separate frames for input (user) and output (R).
The user is supposed to type command into the bottom frame of the R Console, this input is echoed
into the upper frame and R will give any related output in the upper frame.
The output frame (the upper one) is a read-only frame. 

@node Copy and Paste
@subsection  Copy and Paste
Copy and paste works in R as in any other Macintosh application.
But when two selection are active: one in the output frame and one in the input frame, the output frame takes precedence 
when copying to the clipboard.
You can also copy from the @emph{quartz()} graphic device (@pxref{Quartz device}) to the clipboard. In this case a bitmap image is
created. If you want high resolution graphic exports, you should better save the image using the @emph{File/Save as} menu item (@pxref{Quartz device}).


@node The current and startup working directories
@subsection The current and startup working directories
If not otherwise specified in the Preferences (@pxref{Preferences}), or if the specified path is no longer available, then
the default working directory at startup is the user home.
The working directory can be changed using the @emph{setwd} R command or using the @emph{Tools} menu item @emph{Change working directory}.
The current working directory is displayed on the main bar of the R Console window.

@noindent
This feature is useful if you want different startup procedures defined by the @file{.Rprofile}; you can 
edit a @file{.Rprofile} (containing you personal initialization @R{} commands) in a particular directory and use
the Preferences to change the startup directory. Next time you launch @file{R.app} the @file{.Rprofile} is read and executed
by @R{} at startup. This is the equivalent on Unix (or the command line) to launch @R{} from different directories.

 
@node Resizing the R Console
@subsection Resizing the R Console
When the R Console Window is resized, the R option @emph{width} is set appropriately so that any future
output will fit the window size. This behavior can be inhibited using the Preferences settings (@pxref{Preferences}).
On closing the R application, the position and the size of the R Console window are saved in the Preferences and reused
next time you launch R. You can inhibit R to do this using the appropriate Preferences settings.

@node Input and Output text colors
@subsection Input and Output text colors
Text windows and frames are divided in Read-Only and Read and Write ones. Text colors can be set separately
for the two kinds of windows. This happens as well for their respective backgrounds. Use the Preferences window to set these 
colors (@pxref{Preferences}).

@node The Menus
@section The Menus
@menu
* Application Menu::
* File Menu::
* Edit Menu::
* Tools Menu::
* Workspace Menu::
* Packages Menu::
* The Help Menu::
@end menu

@node Application Menu
@subsection Application Menu
The Application menu is the first one after the main Apple Menu. In Mac OS X 10.3 it reports the name R.bin under Mac OS X 10.2 it is just R (as it should be).
We are not able to fix this behavior at the moment.

With this menu you can access three items: 1. the About box, which tells you which version of R is currently in use, 2. Check for updates, which search on @CRAN{} if a new version
of the binary distribution of @R{} for Mac OS X is available (you need an internet connection), 3. you can access the Preferences (@pxref{Preferences}). 

@node File Menu
@subsection File Menu
This menu provides standard functionalities. 
The @emph{open} command is associated to the action  @emph{Source @R{} code}, which means that you can select a file, which is a script, and it will be executed
in @R{}. This is a interface to the @R{} source command @command{source}.

@node Edit Menu
@subsection Tools Menu
Apart for standard functionalities, the only relevant item in this menu is the @emph{Edito Object} which is an interface to
the  @R{} @command{edit} function.

@node Tools Menu
@subsection Tools Menu
With this menu you can load and save the history of commands typed in the @R{} Console or view what's currently inside.
You can also change the current working directory, let @R{} show you the current working directory or set it back to the
startup directory. From release 1.9.0 of @R{} the current working directory is also shown on the main window bar.

@node Workspace Menu
@subsection Workspace Menu
Here you find self explanatory menu items for manage your workspace in @R{}. You can either load and save the workspace also
by specifying file name. All of these are interfaces to the @command{load} and @command{save} @R{} commands.
The only relevant item, which is specific to this GUI, is the @emph{Browse workspace}. This will open a window with a summary
description of the objects in your workspace. Complex objects (like lists, data.frame etc) can be expanded (one level only though).

@node Packages Menu
@subsection Packages Menu
Using this menu you can have access to the list of packages and data-sets installed on your system and to the ones
on @CRAN{} or on the Bioconductor site.

With the first two menus you can load and detach packages and data-set from the workspace.
Let's start with the @emph{Package Manager}. This opens a window with several columns displayed. 
For each package on your system you can see a check box, the current status of the package (loaded/not loaded), its name
and the package description text. You use the check box to select/de-select the packages you want.
On window closure, the checked packaged will be loaded and the unchecked ones (if loaded) will the detached (not completely as on Mac OS X you cannot
unload completely dynamic libraries).

The same applies to the @emph{Dataset Manager} menu but for data-sets.

You can than get or update packages @CRAN{} either in binary or source format. Daily build of @CRAN{} packages are available
for Mac OS X. If you don't know how to build @R{} itself from source (@pxref{Building R from sources}), 
you'll probably be unable to build packages from source on your own.
In this case, you should always choose for the binary option. These binary packages work (for sure!) for the release version of @R{} for Mac OS X
you find on @CRAN{} even though it is not excluded that they will work for other prebuilt versions of @R{}.


When you attempt to install packages from @CRAN{}, @R{} first tries to get a connection to the Internet to download
the list of available packages. Than a window will open similar to the one in the package manager with the only difference that
for each package there is also the information concerning the version of the package installed on your system (if any) and
the version of the prebuilt package available on @CRAN{}. When you close the window, the select packages will be downloaded.

The same strategy applies to the Bioconductor menu item, with some more options typical of the Bioconductor way
of managing packages.

For some reason it could happen that you have the package you want to install (either in binary or source form) on one of your
local disks, or even a directory containing a package source. You can use the last menu to do the task of installing the package.
Having a package in a directory form usually applies to people that are developing packages themselves.


For more information on this topic see also @ref{How to install packages}.

@node The Help Menu
@subsection The Help Menu
Using this menu you can open the on-line manuals (@emph{R Help}), read this FAQ and  review the latest changes, bug fixes and new features of R for Mac OS X (@emph{What's new in this version}).
There are also interfaces to the R @emph{help} and @emph{help.search} functions as well as the @emph{example} function. 

@node Preferences
@section Preferences
You can set several aspects of the @R{} GUI via preferences. You can access the Preferences window via the Application menu when the
@R{} Console is open.
Preferences are organized in Tabs, more or less grouped for content.

@menu
* Text Windows tab::
* Quartz device tab::
* Packages tab::
* Misc tab::
@end menu

@node Text Windows tab
@subsection Text Windows tab
You can change the font size, face and the tab size in all the windows including the Console.
If you have help windows opened, the changed only apply to the Console window and to the window
you'll open from now on. This is a misfeature more than a bug.

You can also change the foreground and background colors for the read-only windows (i.e. the @R{} Console
output and the Help windows) and for read-and-write windows (i.e. the @R{} Console input and the Edit windows).
At the moment you cannot change the color of the cursor which always stays black which ever  background you choose.
So, for the time being, it's a bad idea to set the background of the @R{} Console to black.

You have also the possibility to check two options. The first is for adapting the @R{} output when you resize the
@R{} Console to the maximum character displayable, the second one is to let @R{} remember the position of the
@R{} Console on exit.

@node Quartz device tab
@subsection Quartz device tab
You can set all the parameters of the @command{quartz} device for this tab. Please note: your changes only take effect
if you select the final checkbox, namely @emph{override the R quartz default settings}.

This also apply to the @emph{Quartz window position} option even if it is not a @command{quartz} parameter itself.


@node Packages tab
@subsection Packages tab
From this tab you can set the default repositories for the @CRAN{} and Bioconductor urls. This will affect the
corresponding @R{} @command{options}.

@node Misc tab
@subsection Misc tab
For this tab you can decide to redirect the stderr and stdout of @R{} and the tasks launched by @R{}, to the @R{} Console.
This is useful, for example, during package installation. If you don't check these options, every output will be sent to the @emph{Console}
application which you can find on every Mac OS X installation inside the directory @file{/Applications/Utilities}.

You can also set the startup working directory. This is very useful for having different sessions in different
directories (see @ref{The current and startup working directories} and @ref{How can I have a per session .Rprofile?}).

@node The near future of the Aqua GUI
@section The near future of the Aqua GUI
Jointly with Simon Urbanek we are currently working to replace the current Aqua GUI, which is Carbon-based,
with a pure Cocoa GUI. This will allow for a better integration of R with Mac OS X and
a fully Aqua-compliant GUI.
A preview of the Cocoa GUI for Darwin R can be obtained after the official
release of R 1.9.0 is out from @uref{http://www.economia.unimi.it/R}.

@node Aqua GUI Bugs, ,The near future of the Aqua GUI, R with Aqua GUI
@section Aqua GUI Bugs
On Unix systems a bug report can be generated using the function
@code{bug.report()}.  This automatically includes the version
information and sends the bug to the correct address.  Alternatively the
bug report can be emailed to @email{R-bugs@@R-project.org} or submitted
to the Web page at @uref{http://bugs.R-project.org/}.

You can also send specific Aqua GUI bugs directly to @email{stefano.iacus@@unimi.it}

In any circumstances, in case of a crash, please report the 
crash.log for the @emph{R.bin} application. You can get this
crash.log using the @emph{Console.app} located inside @emph{/Applications/Utilities}.

@node How to install packages
@chapter How to install packages
You have several options for installing new packages on your system. We discuss here only the interface to the standard
@R{} functions like @command{install.package}. For the @R{} functions see the standard @R{} documentation.

@menu
* Which kind of packages can I install using the GUI?::
* Installation of packages from source::
* Installation of pre-built binary packages::
* Can I install packages built for other platforms?::
* Where are the packages I've installed?::
@end menu

@node Which kind of packages can I install using the GUI?, Installation of packages from source, , How to install packages
@section Which kind of packages can I install using the GUI?
At the moment the GUI menus only provide direct access/download/installation of packages located on @CRAN{} or in the
Bioconductor repository. You can also install packages from local files, either binary of source packages, as explained
below. Otherwise you can use the appropriate @R{} commands to install packages from a specific location other than the above mentioned ones.


@node Installation of packages from source, Installation of pre-built binary packages, Which kind of packages can I install using the GUI?, How to install packages
@section Installation of packages from source
You can choose to install packages from source if they are located on @CRAN{}, on the BioConductor repository and
on your local disk. In any case, in order to be able to build packages from source, you need to have the same working
setup for building @R{} itself (@pxref{Building R from sources}). In same cases you can still build packages without all
the tools installed, but surely not for all the packages containing C/C++ or Fortran source code.

@noindent
If you decide to install packages from @CRAN{} you should use the @emph{Packages} menu of the GUI. In particular the sub-item @emph{Get CRAN packages.../Source}.
This will connect to @CRAN{} through the Internet and a list of available packages will be shown.
This is list tells you if a package is already installed on your system, the version of the package available on @CRAN{} and the version
of the same package if already installed.
You can make multiple selection of packages you intend to install using the checkboxes (one per package).
When you close this window, you'll be asked if you really want to download the selected packages and the process of installation
begins. If you don't select any package, nothing happens.
@R{} will not respond on the Console until you  close this window.
The same applies for packages in the BioConductor repository. You have also several other options specific to the
BioConductor way of managing repositories of packages.

@noindent
You can also download any other package from the Internet yourself and decide to install it from source.
You have to use @emph{Packages/->Install form local file} submenus. Where you can choose a standard @file{package.tar.gz}
tarball or the directory containing your package if you have the package in expanded form.



@node Installation of pre-built binary packages, Can I install packages built for other platforms? ,Installation of packages from source, How to install packages
@section Installation of pre-built binary packages
Same considerations of above apply with two minor differences. The first one is that se only distribute pre-built
version of packages which pass all the test/checks on Mac OS X. So you'll see that some of the packages are missing with respect to the huge list
of source packages available on @CRAN{}.

@noindent
The second difference is that, when you install packages from local file, it is assumed that the binary package is named
as @file{package.tgz}. This is to distinguish among source and binary archives.

@node Can I install packages built for other platforms?,  Where are the packages I've installed?,Installation of pre-built binary packages, How to install packages
@section Can I install packages built for other platforms?
As a general rule the answer is @emph{yes} if the package does not contain any C/C++/Fortran code in the sources, otherwise
the answer is negative. Another caution should be taken, that is, the package and the installed version of @R{} should be 
the same major release, i.e. you can install a package built for @R{} 1.8.0 on @R{} 1.8.1, but usually not the same
package on @R{} 1.9.0.

@noindent
A Mac OS X specific requirements, is that a prebuilt package is assumed to be named (and accordingly archived and
compressed) as @file{package_name.tgz}.
On Windows, for example, packages come in a zipped format.


@node Where are the packages I've installed?, ,Can I install packages built for other platforms?, How to install packages
@section Where are the packages I've installed?
The main library of packages is the one located inside the R.framework. This library contains the packages (base and
recommended ones) distributed along with @R{}. At the moment you cannot use the GUI Console to install packages 
in this location because of authentication problems, you can surely do this from the command line with an admin
password, with something like
@example
sudo R CMD INSTALL pkg_ver.tar.gz
@end example

@noindent
By default, the user of @file{R.app} installs packages inside the @file{Library/R/library} directory 
in his home directory, i.e. @file{~/Library/R/library}.
If you install a package using the @file{R.app} interfaces and you then use @R{} from the command line,
you won't see or have access to these packages unless you add the @file{~/Library/R/library} to the
list of libraries locations. You can do the following from inside @R{}
@example
.libPaths("~/Library/R/library")
@end example
or write this command in the @file{.Rprofile} file in your startup directory.
On some version of OS X the @file{~} symbol is not correctly expanded. You should preferably use this
version of the above command
@example
.libPaths(path.expand("~/Library/R/library"))
@end example

@noindent 
If you have a version of @file{RAqua.app} installed on your system, it is likely that you have all the
packages installed in @file{~/Library/RAqua/library}. You can add this library of packages in the @command{.libPaths()}
but most of them will probably not work as they were built for release 1.8.x of @R{}.


@node R and external applications, Quartz device, How to install packages, Top
@chapter R and external applications

@menu 
* AppleScript support::
* External editors::
* Finder actions::
@end menu

@node AppleScript support, External editors, ,  R and external applications
@section AppleScript support


@R{} has partial support for Apple-Scripts. 
At the moment R can be invoked and asked to run commands from an AppleScript script.
What follows is an example of script that interacts with @R{}. It firstly  invokes @R{} and then
sends commands to @R{} with the @command{cmd} applescript command. 

@example
set CommandLine to "R.Version()"
try
	tell application "R"
		activate
		with timeout of 90000 seconds
			cmd CommandLine
			cmd "Sys.getenv()"
			cmd "print(\"HelloWorld!\")"
		end timeout
	end tell
end try
@end example

@noindent
In the above, @command{cmd} is the (only) applescript command in the @R{} dictionary that is 
used to tell @R{} to execute an @R{} command in the R Console. The syntax is 
@example
cmd <command string>
@end example
where command string have to be in quotes. Actually, the output of the command
is not sent back to the application that is calling @R{} but to the @R{} Console directly.

@noindent
There are some issues. The first is that if @R{} is still not running, it will take a while (depending on 
how fast your machine is) to startup. In the meanwhile the script sends commands without waiting and it
could happen that some commands are missed by @R{}, i.e. they arrive before @R{} is ready to 
receive applescript commands. The second issue, is that it could be that the applescript calls a bad version
of @R{}. This could happen if you have an old version of @R{} (for example the old Carbon @R{}) installed on your
System.

@noindent
As an example, we report here a small script that asks @R{} to @command{source} a file using a file dialog.
@smallexample
set file_to_source to (choose file with prompt "Choose file to source") as alias

try
	tell application "R"
		activate
		with timeout of 90000 seconds
			cmd "source(\"" & file_to_source & "\")"
		end timeout
	end tell
end try
@end smallexample


@node External editors, Finder actions, AppleScript support,  R and external applications
@section External editors
@R{} accepts the Apple Event command @emph{open}. This means than an external editor can communicate with @R{} sending
portions of @R{} code to execute via files. This is the approach used by the @R{}-Tcl Mode in Alpha X 
(see @uref{http://www.kelehers.org/alpha/}).


@node Finder actions, , External editors,R and external applications
@section Finder actions
Dragging a file on the @R{} icon, causes @R{} to source this file via the @command{source} @R{} command or,
if the file is an @R{} image data file RDX1 or RDX2 (normally files with extension @file{.rda} or @file{.Rdata}), the data is loaded in the workspace and every object
with the same name in the workspace is overwritten without notice. Loading a data file is equivalent to
the @R{} command @command{load}.
At the moment there is no control over the file types, i.e. dragging wrong files (i.e. files that are
not @R{} scripts or image data) simply gives an error. It's up to the user to @emph{do the right thing}.

@noindent
If @R{} is not yet running this action causes @R{} to startup.

@node Quartz device, TclTk issues, R and external applications, Top
@chapter Quartz device
The quartz device is the native graphic device in R for Mac OS X. It's name derives from Apple's Quartz Technology
which is essentially similar to PDF rendering. One of the most amazing features of Quartz is antialiasing which gives you
@emph{very nice} plots and images. Try to compare  a quartz plot  with the same plot generated on
any other interactive device. For its PDF nature it is also resolution independent.
 
@menu
* Interactive mode::
* Saving the image::
* Copying the image into the clipboard::
* Known bugs and missing features::
@end menu

@node Interactive mode, Saving the image,, Quartz device
@section Interactive mode
The quartz device allows for interaction. You can use both @command{identify} and @command{locator} functions.
To break the sequence you should press the ESC key on your keyboard as Apple's mouse have ever had only one
button.

@node Saving the image, Copying the image into the clipboard, Interactive mode, Quartz device
@section Saving the image
You can can the content of the quartz device window into a PDF file. This is a very simple way to
export high quality graphics from @R{} into other applications on Mac OS X graphics is PDF based (so are almost all
applications available). If you want bitmap copies of you quartz device window just use copy, to copy the image into the clipboard and
paste the result in a graphic application (@pxref{Copying the image into the clipboard}).

@node Copying the image into the clipboard, Known bugs and missing features, Saving the image, Quartz device
@section Copying the image into the clipboard
You can copy the content of the quartz device window in the clipboard to make the resulting image available for
pasting into other applications. The clipboard will contain a bitmap copy of the quartz device window. If you
want to work with high resolution images, you should save the content of the quartz device as a PDF file (@pxref{Saving the image}).
Pay attention to the following fact: the bitmap image produced has exactly the same dimensions of the quartz device window. This
means that if you resize the window, the resulting image you obtain in the clipboard will have the same
dimensions and you cannot resize the image from the inside another applications (say MS-Word) without loosing quality.


@node Known bugs and missing features,,Copying the image into the clipboard,Quartz device
@section Known bugs and missing features
When rendering text and/or mathematical symbols the style is ignored, i.e. only plain style is drawn.
The printing function is not yet implemented.

@node TclTk issues, Additional resources, Quartz device, Top
@chapter TclTk issues
Each binary distribution of @R{} available through @CRAN{} is built to use the X11 implementation of TclTk.
Of course a X windows server has to be started first. If you are not using the Aqua GUI you need to also
define the environment variable DISPLAY before attempting to use X11 from inside @R{}. You can do this as follows
@example
Sys.putenv("DISPLAY"=":0")
@end example
If you don't like the X11 GUI you would probably want to build R using the Aqua version of TclTk (@pxref{the Aqua TclTk headers and libraries (optional)}).
After installing the R.framework you should do the following to have the quartz device working under Aqua TclTk. Open a
Terminal window and move inside the @file{Resources/bin} directory of the @file{R.framework}
(usually @file{/Library/Frameworks/R.framework}), then type the following
@example
sudo /Developer/Tools/Rez -t APPL Carbon.r -o R.bin
@end example


@node Additional resources, Acknowledgments, TclTk issues, Top
@chapter Additional resources
Here are few references that can be of interest for Mac OS X and/or developers.

@menu
* Apple Developer Connection::
* The R for Mac OS X Developer page::
@end menu

@node Apple Developer Connection
@section Apple Developer Connection
The Apple Developer Connection (can be reached at @uref{http://developer.apple.com}) is the main source
of information for Apple products (OS, hardware, software) for developers. You can subscribe for free to
ADC and get the latest up-to-date tools from Apple (compilers for example).

@node The R for Mac OS X Developer page
@section The R for Mac OS X Developer page
There is a page dedicated to the latest R-devel version of R. This page is located at
@uref{http://www.economia.unimi.it/R} and is maintained by Stefano M. Iacus.
This page is intended to give additional documentation for building  the latest R-devel
version of R. From time to time, snapshots of R-devel binaries are available for testing purposes.

@node Acknowledgments, Sparse questions,  Additional resources, Top
@chapter Acknowledgments

Special thanks go to Simon Urbanek, Jan de Leeuw, Byron Ellis and Thomas Lumley
in random order. Last but not least Apple for amazing OS and GUI.

@node Sparse questions, , Acknowledgments, Top
@chapter Sparse questions
@menu
* How can I have a per session .Rprofile?::
* What happens if I drag a file on the R icon?::
* How can I interrupt lengthy operations or output?::
* I don't see a thing when installing packages!::
@end menu

@node How can I have a per session .Rprofile?,What happens if I drag a file on the R icon?,,Sparse questions
@section How can I have a per session .Rprofile?
You can by writing a @file{.Rprofile} file in your favorite
session directory and change accordingly the startup working directory using the Preferences (@pxref{The current and startup working directories}).

@node What happens if I drag a file on the R icon?,How can I interrupt lengthy operations or output?,How can I have a per session .Rprofile?,Sparse questions
@section What happens if I drag a file on the R icon?
In this case @R{} will try to source this file or load the image data file (@pxref{Finder actions}). If @R{} is not
yet running it will be launched.

@node How can I interrupt lengthy operations or output?, I don't see a thing when installing packages!,What happens if I drag a file on the R icon?,Sparse questions
@section How can I interrupt lengthy operations or output?
You can now use the standard Macintosh control break sequence, that is you should press
"Cmd option" and "." (dot). This will interrupt any @R{} loops. The "Esc" key gives you the same result. 

@node I don't see a thing when installing packages!,,How can I interrupt lengthy operations or output?, Sparse questions
@section I don't see a thing when installing packages!
Well, this is not a question but the answer is that you are not looking at the right place.
Every input and output which is not @R{} specific (i.e. the output of standard commands) is generally sent to
the standard output (stdout) or standard error (stderr) depending on its nature. In particular every call to the
@command{system} function, executes outside @R{} in a Mac OS X shell. The package installation is done via
the @command{system} facility. 
You have to use the Preferences to redirect the stderr and/or the stdout to the @R{} Console (see @ref{Misc tab})
or you can look at the @emph{Console} application inside @file{/Applications/Utilities} on your system.
This applies to every GUI application on Mac OS X so, as a general rule, if an application behaves strangely or quits,
please have a look to the @emph{Console} application.

@bye

@c Local Variables: ***
@c mode: TeXinfo ***
@c End: ***
