R for Mac OS X FAQ

Frequently Asked Questions on R for Mac OS X

Version 2.12-2 2011-02-25

Stefano M. Iacus

Simon Urbanek

Rob J. Goedman

R for Mac OS X FAQ
******************

Introduction
************

This R for Mac OS X FAQ is rather incomplete at the moment and requires contributions from users. Anything specific to the R language can be found in the official R-FAQ (see http://cran.r-project.org/doc/FAQ/R-FAQ.html). Please send any requests/questions you would like answers to the R-SIG-Mac (https://stat.ethz.ch/mailman/listinfo/r-sig-mac) mailing list.

In this document R refers to the core, command line based R system while R.APP refers to the GUI based Mac OS application that controls the underlying R.

This document contains information on how to build R from sources, how to install and run it on Mac OS X. It also contains a user guide to the R.APP version of R.

The last section of this document contains the most frequently asked questions that don't fit strictly into any of the categories above -- it is usually a good idea to always look into that section if your issue doesn't fit any of the above or was not answered in one of the specific sections. Always read this FAQ first before asking for help on R-SIG-Mac!

How many versions of R for Mac OS X?
====================================

There is currently only one version of R for Mac OS X. However, R on Mac OS X can be used either on the command-line (see Command line version of R) like on other Unix systems, or via the R.APP GUI (see R.app). The second approach is mostly preferred by Macintosh users.

What machines does R for Mac OS X run on?
=========================================

R for Mac OS X requires Mac OS X version 10.2 (Jaguar) or higher to run. The R.APP GUI requires Mac OS X 10.3 (Panther) or higher. The latest version of the system is always preferable, though. We do not support Mac OS X version 10.1 and earlier. The binaries provided on CRAN are universal (32-bit Intel + PowerPC, 64-bit Intel) and require Mac OS X 10.5 (Leopard) or higher.

R can be compiled from sources as a pure 64-bit application on PowerMac G5 and Intel x86_64 machines on Mac OS X 10.4 or higher. R.APP GUI can be built for 64-bit R as well, but Mac OS X 10.5 (Leopard) or higher is necessary.

How can R for Mac OS X be obtained and installed?
=================================================

R is available on CRAN in the form of an Installer package consisting of the R framework and the R.APP GUI. The package is usually named R.pkg with optional version number. Previously the legacy Tiger build was packaged in a compressed disk image and usually named R.dmg.

The installation is done by double-clicking on the Installer package. The Installer will guide you through the steps necessary to install R on Mac OS X. Note that the Installer will require password or login of an administrator. The installation can be customized, but the default is suitable for most users.

If you experience problems with R, we highly recommend the use of the CRAN binary package to make sure R was built correctly. Nevertheless it is possible to build R from the sources which can be useful for special purposes. Note that the CRAN binary includes R shared library, so there is no need to re-compile R with --enable-R-shlib.

How can R for Mac OS X be uninstalled?
======================================

R for Mac OS X consists of two parts: the GUI (R.APP) and the R framework. The un-installation is as simple as removing those two folders (e.g. by dragging them into the Trash). The typical installation will install the GUI into the /Applications folder and the R framework in the /Library/Frameworks folder.

If you want to get rid of R from the Terminal, simply run (prepend sudo if you don't have admin privileges):

     rm -rf /Library/Frameworks/R.framework /Applications/R.app

Another alternative is to use Apple's pkgutil tools to uninstall R. R consists of three packages: org.r-project.R.Leopard.fw.pkg, org.r-project.R.Leopard.GUI.pkg and org.r-project.R.Leopard.GUI64.pkg. You can use pkgutil --unlink for each of them to remove their files and/or pkgutil --forget if you want the Apple Installer to forget about the package without deleting its files (useful when installing multiple R versions in parallel).

Installation Problems
=====================

The binary version of R is provided as an Apple Installer package. Therefore the installation is performed by the Apple Installer, which is the recommended way of installing software on Mac OS X. If you encounter any problem during the installation, please check the Installer log by clicking on the ``Window'' menu and item ``Installer Log''. The full output (select ``Show All Log'') is useful for tracking down problems.

Some users have experienced problems during the installation of optional packages (compiler tools or Tcl/Tk) due to an infinite soft link ``/usr/local/lib''. This prevents installation of any files into that location. Apple Xcode 2.5 and 3.0 is suspected to create this problem as it renames the ``real'', existing /usr/local/lib to ``lib 1'' while creating an infinite link (i.e a link that points to itself). If that is the case (easily verified with ls -ld /usr/local/lib*), you can fix this problem by issuing the following commands in Terminal:

     sudo rm -f /usr/local/lib && \
     sudo mv '/usr/local/lib 1' /usr/local/lib

Note: In order for Tcl/Tk to work, don't forget to install the additional tools the very first time you upgrade. On the MacOS install page, see the note on the difference between the xxx.pkg and the xxx.dmg.

R installer since version 2.7.0 attempts to detect and resolve the above problem automatically.

Building R from sources
***********************

Quick start
===========

If you have a clean, recent Mac OS X (10.5 Leopard or 10.6 Snow Leopard) and want quick instructions how to build your own R binary, read this section. In all other cases please read the details in the following sections.

First, you need to install developer tools - that is Xcode 3.1 for Mac OS X 10.5 (Leopard) or Xcode 3.2 for Mac OS X 10.6 (Snow Leopard). Xcode is present on the OS X installation DVD or can be downloaded from http://developer.apple.com/mac/. Then download the matching FORTRAN compiler from http://R.research.att.com/tools/.

Optionally you can also install TeX (http://www.tug.org/mactex/) to build documntation. You can pick useful external libraries from http://r.research.att.com/libs/ (such as readline, libpng, jpeg) but they are not required. You can install them using the Terminal (in Application/Utilities) for example:

     curl -s -S http://r.research.att.com/libs/readline-5.2-12-darwin8-bin4.tar.gz \
     | sudo tar fvxz - -C /

Download, configure and build R. In the following we assume you have an Intel-based Mac with of 64-bit support. Again in Terminal type:

     # download R
     curl -O http://cran.r-project.org/src/base/R-2/R-2.12.2.tar.gz
     # unpack R
     tar fxz R-2.12.2.tar.gz
     # choose the architecture (x86_64, i386, ppc or ppc64)
     arch=x86_64
     # create a build directory
     mkdir R-$arch
     cd R-$arch
     # configure R
     ../R-2.12.2/configure r_arch=$arch  CC="gcc -arch $arch" \
          CXX="g++ -arch $arch" F77="gfortran -arch $arch" \
          FC="gfortran -arch $arch" OBJC="gcc -arch $arch" \
          --x-includes=/usr/X11/include --x-libraries=/usr/X11/lib \
          --with-blas='-framework vecLib' --with-lapack
     # build R
     make -j8
     # At this point you can run R as `bin/R' even without installing

     # install R
     make install
     # in some cases you may need to use ``sudo make install'' instead

If you want 32-bit Intel build replace arch=x86_64 with arch=i386. For PowerPC use arch=ppc (32-bit) or arch=ppc64 (64-bit and only supported on Mac OS X 10.5). You can repeat the steps above for any number of architectures.

In order to make the newly installed R visible from the command line, use

     sudo ln -sfn /Library/Frameworks/R.framework/Resources/bin/R /usr/bin/R

Please note that any version of R you build yourself will be different from the released binary CRAN version and may not work with the package binaries we provide. Therefore we recommend using the CRAN binary or nightly builds from http://R.research.att.com unless you want to modify R sources yourself.

What is needed to build R
=========================

The requirements for building R vary, depending whether the build machine is an Intel-based or PowerPC-based Mac and whether universal build is desired. The following description shows the minimum requirements for building R. The process of building a universal binary is more complex and described in section see How to build universal R.

C/C++ compiler (gcc 3.3 or later)
---------------------------------

If you have Mac OS X 10.3 (aka Panther) or higher you just need to install the software from the Xcode Tools CD or DVD. This is only true if you bought retail version of Mac OS X. If your computer came with pre-installed version of OS X, look into /Applications/Installers. Recent installations feature Xcode Tools folder containing the necessary installer. If neither of the above works for you, download Xcode from http://developer.apple.com/tools/xcode/.

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 or you can download these from the Apple Developer Connection site (see Apple Developer Connection) In either cases be sure you have gcc version 3.3 or later - you can check the version by typing the following in a Terminal window:

     gcc --version

Users of Intel Macs have to use gcc version 4.0 or higher, because gcc 3.x is not supported on Intel Macs. Apple's gcc-4.2 is highly recommended because previous versions are known to contain bugs.

Fortran compiler (g77 3.3 or later)
-----------------------------------

Unfortunately the Xcode Tools don't include a Fortran compiler. You need to install a version 3.3 or later of the Fortran compiler from gcc which is built for Mac OS X. We provide GNU Fortran builds that can be added to Apple's Xcode tools - see http://r.research.att.com/tools/. The CRAN binaries are configured to use Apple's gcc and the supplied Fortran compiler (see also Why do I need custom compilers for the CRAN binary?).

Please note that it is important that the major version of the Fortran compiler matches the version of your C compiler! You can only use gcc 3.x with g77 3.x or gcc 4.x with gfortran 4.x, other combinations usually don't work.

libreadline 4.3 or higher (optional)
------------------------------------

The readline library is optional and only necessary for OS X 10.3 (Panther) and earlier. Mac OS X 10.4 (Tiger) comes with libedit library which emulates readline. Nevertheless, GNU readline has some additional functionality so it may be worth installing anyway.

Readline is necessary if you want 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 web page ftp://www.gnu.org. (Also consider installing the rcompletion package that uses readline for code-completion in R).

Readline 5.0 and later compile out-of-the box, however it is recommended to use make CPPFLAGS=-DNEED_EXTERN_PC, because the configure script fails to detect that flag. The use of readline 5.2 with recent patches is recommended due to bugs in earlier versions that can lead to crashes. (We cannot distribute readline 6.0 on CRAN due to its incompatible licensing terms).

To compile readline, uncompress the source archive and follow the standard installation sequence:

     ./configure
     make CPPFLAGS=-DNEED_EXTERN_PC
     sudo make install

It installs everything in /usr/local.

Note: It is possible to build multi-architecture readline binary in one step, for example set CC='gcc -arch ppc -arch ppc64 -arch i386 -arch x86_64' to build all four architectures (see Apple Xcode tools reference for details). Such binary is available as a part of the development pack from http://cran.r-project.org/bin/macosx/tools/.

X11 window server (optional)
----------------------------

X11 window system is necessary to use the X11 device in R and other devices that rely on X11.

Mac OS X 10.6 (Snow Leopard) requires manual identification of X11 location using --x-includes=/usr/X11/include --x-libraries=/usr/X11/lib.

Mac OS X 10.5 (Leopard) installs X11 by default, however the default X11 installation ships with a broken OpenGL library that prevents compilation. See http://r.research.att.com/building.html for the latest update on the details. Also /usr/X11/bin must be on the PATH in order for R to recognize X11 properly (e.g. by issuing export PATH=/usr/X11/bin:$PATH).

Mac OS X 10.3 (Panther) and 10.4 (Tiger) include X11 on the installation CD/DVD, however, it is not selected by default. If it is not installed, you can re-install it using the original installation CD/DVD.

To install X11 on those systems, follow these steps:

 1. Insert Mac OS X Disk 1 (CD/DVD) that came with your Mac

 2. Ctrl-Click (or right button click) on "Install Bundled Software Only", select "Show Original"

 3. double-click on "X11User.pkg"

If you have a retail version of OS X, replace second step by

 2. Go to System/Installation/Packages direrctory on the DVD

In addition to the user part, you need to install the X11 SDK package from the Xcode Tools CD. In Xcode 2.4.0 and higher this is the default if X11 is installed, therefore it is important to install X11 before installing Xcode.

Mac OS X 10.2 (Jaguar) does not include X11 installer. However, there are two options to obtain X11: Apple released X11 beta for Jaguar which is still around, although not officially supported. It features the Quartz window manager that integrates nicely into the system. If you are unable to find Apple's X11 beta, you will need to install both the X11 Window server and the X11 SDK package from the XFree86 web page. Other versions such as using fink are available, too.

Cairo graphics library (optional)
---------------------------------

R 2.7.0 and later include support for cairo graphics library as one of the options in X11 support. Mac OS X does not include cairo library, therefore we have to build our own. In order to simplify the distribution, we use a static build of cairo. Therefore the library is not needed at run time as it's already part of R. However, if you want to compile R, you can obtain the same binary we use for the release from http://r.research.att.com/devpack4-darwin8-bin4.tar.gz. Read more on CRAN in the ``tools'' directory.

In general cairo grapics library can be obtained from http://www.cairographics.org/. More recent versions can use either native ATSUI/Quartz font back-end or FreeType. If the latter is used, make sure you get the most recent (even development) version available, because there are known bugs in FreeType with respect to Mac font support.

Cairo support is strictly optional given that Quartz is the default graphics device on Mac OS X, but it can be useful for remote displays.

X11 TclTk headers and libraries (optional)
------------------------------------------

If you plan to use tcltk package for R, you can either use Tcl/Tk headers and library supplied in the R CRAN binary or compile your own. The CRAN binary includes universal Tcl/Tk 8.5.5 for X11 (boht 32-bit and 64-bit).

Alternatively you need to download the sources of the Tcl and Tk 8.5.x packages to build yourself the sources. The original sources can be found on the official TclTk web page http://www.tcl.tk/software/tcltk/8.5.html (do NOT use the ActiveTcl native binaries, they don't work with the tcltk package in R). Please do the following respecting the sequence (you'll be asked for a root password). These are examples for version 8.5.5 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.

The following shell commands will download, compile and install universal Tcl/Tk. Modify the configure part to suit your needs, such as if you don't need all architectures:

     cd /tmp/
     curl -O http://internap.dl.sourceforge.net/sourceforge/tcl/tcl8.5.5-src.tar.gz
     curl -O http://internap.dl.sourceforge.net/sourceforge/tcl/tk8.5.5-src.tar.gz
     tar fxz tcl8.5.5-src.tar.gz
     cd tcl8.5.5/unix
     CFLAGS='-arch i386 -arch ppc -arch ppc64 -arch x86_64' ./configure --with-x \
     --disable-corefoundation --enable-threads --disable-symbols --disable-aqua
     make
     sudo make install

     cd ../..
     tar fxz tk8.5.5-src.tar.gz
     cd tk8.5.5/unix
     CFLAGS='-arch i386 -arch ppc -arch ppc64 -arch x86_64' ./configure --with-x \
     --disable-corefoundation --enable-threads --disable-symbols --disable-aqua
     make
     sudo make install

(64-bit build of Tk will only work if you have 64-bit X11 installed - this is the default o Leaoprd but not on Tiger).

Aqua TclTk headers and libraries (optional)
-------------------------------------------

Mac OS X 10.4 (Tiger) comes with Aqua TclTk libraries. If those are not detected automatically, use the following flags with configure:

     --with-tcl-config=/System/Library/Frameworks/Tcl.framework/tclConfig.sh
     --with-tk-config=/System/Library/Frameworks/Tk.framework/tkConfig.sh

Note that currently R.APP doesn't support Aqua Tcl/Tk, because of conflicting event loops (in fact Aqua Tcl/Tk cannot be embedded in any UI application due to its design assumptions). Therefore we strongy discourage the use of Aqua TclTk.

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 http://www.rna.nl/ii.html. The teTeX is one of the i-Packages.

MacTeX (http://www.tug.org/mactex/) is a more recent alternative, but it is huge and contains other (possibly unwanted) libraries and programs.

Note: You may also want to install TeXShop (http://www.uoregon.edu/~koch/texshop/texshop.html). Beside wonderful GUI for editing TeX files that page also provides many useful links for TeX on Mac OS X.

How to configure and build R
============================

Download the latest sources of R from CRAN or fetch them using SVN. Unpack the archive with tar -zxf name_of_R_sources_archive and cd inside the R sources directory. Then you need to configure R for your system and build R. It is recommended to use separate directory for building from the sources. For example if you unpackged R as R-2.12.2 type:

     mkdir build
     cd build
     ../R-2.12.2/configure
     make

This will configure R to be built as a Framework to be installed inside your /Library/Frameworks directory with the name R.framework. make will compile R. Such compiled R can already be used by running the bin/R script.

Note that the default configuration assumes that all your compilers produce binaries for the same architecture. This is not true on Mac OS X 10.6 (Snow Leopard) where by default Xcode gcc produces 64-bit binaries but gfortran produces 32-bit binaries. Therefore in such a case you must set the compiler varaibles (CC, CXX, OBJC, F77, FC) accordingly to make sure they target the same architecture (see also How to build universal R).

Some additional, useful flags that you may want to add to configure include:

  * --with-blas='-framework vecLib' enables vecLib as BLAS implementation. Given that vecLib is highly optimized by Apple, it is recommended for most users. (Currently there is one exception: users with Nehalem-based Mac Pros may want to use other alternatives such as ATLAS because current vecLib fails to recognize cores on such machines and will run in single-threaded mode which is slow.)

  * --enable-BLAS-shlib enables the use of libRblas.dylib which separates BLAS from the R library. This allows you to switch between various BLAS implementations (such as vecLib, internal R BLAS and ATLAS) without the need to re-compile R. It is in general a good idea and can be used with both internal BLAS and vecLib. (This option is enabled in the binary available from CRAN.)

You can change the default location of the R.framework installation at configure time by specifying the flag --enable-R-framework[=DIR], i.e. with something like

     ./configure --enable-R-framework=FOO

and the final destination of the R.framework will be FOO/R.framework, which means that you don't have to specify the R.framework text in the path.

The R framework supports multiple versions of R in the same framework, thus allowing parallel R versions to co-exist. By default R version x.y.z will install into the Versions/x.y subdirectory of the framework. The name of the subdirectory can be overridden by using FW_VERSION configure setting, such as for example FW_VERSION=R-devel which will install in Versions/R-devel. The currently used framework is always the one pointed to by the Versions/Current, see Apple's documentation on framework bundle anatomy for details (http://developer.apple.com/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/FrameworkAnatomy.html).

How to install R
================

Once the compilation succeeds type:

     sudo make install

to install R in /Library/Frameworks (unless changed at configure time). You must have admin privileges and your password will be required.

You can decide to change the installation destination by using the prefix option: final destination.

     sudo make prefix=/my/new/R/location install

As in the above, you don't need to specify the name R.framework in the path. (See R documentation for details.)

How to build and install the R.app
==================================

The sources for the R.APP GUI are currently not included in the global R source distribution. They are available in the form of a Xcode project on the R for Mac OS X CRAN pages (released versions) as well as the SVN repository. In order to check out the latest development version, use

     svn co https://svn.r-project.org/R-packages/trunk/Mac-GUI

Before compiling R.APP make sure R is installed in /Library/Frameworks/R.framework and working.

Using Xcode load the R.xcodeproj project, select R target (which is the default), set Deployment configuration build. The same effect can be achieved on the command line in the Mac-GUI directory by typing:

     xcodebuild -target R -configuration Deployment

The current development is done using Xcode 3.1 or higher. The default deployment build is universal, therefore you will need universal R framework and Mac OS X 10.4u SDK. Make sure /Library is available inside the SDK, recent Xcode installations ensure this automatically.

For compatibility, the GUI offers an old-style project for Xcode 2.0 named R.xcode which will build PowerPC binary only. However, this project file is no longer actively maintained. In addition to the default Deployment configuration there is also Depolyment64 configuration that build 64-bit version of the GUI - you must have 64-bit R framework and Mac OS X 10.5 or higher for this to work. Other useful configurations include Leopard, Leopard64, SnowLeopard and Debug.

The build includes both R.APP and this R for Mac OS X FAQ. However, it is recommended to use at least GNU texinfo 4.7, because a bug in previous versions leads to invalid html output. Mac OS X 10.4 (Tiger) and later include the correct version of makeinfo.

R.APP does not need to be installed in any specific way. Building R.APP results in the R.APP bundle which appears as one R icon. This application bundle can be run anywhere and it is customary to place it in the Applications folder.

How to build universal R
========================

Starting with R 2.3.0 it is possible to build R that runs on multiple architectures. One special application of this feature is to build R that runs on both Intel and PowerPC based Macs on Mac OS X 10.4.4 or higher. Such R build is called universal. Other application is to build 32-bit and 64-bit version of R for the same platform.

In order to be able to build universal R, all necessary libraries must be available as i386 and ppc binaries. For system libraries this is the default for Mac OS X on Intel Macs. Other libraries such as readline must be compiled accordingly.

In addition, the compilers must support both architectures as well. You will need Xcode Developer Tools version 2.4.0 or higher and a Fortran compiler that can create universal binaries. Such compiler is supplied with R 2.6.x in the CRAN binary package and available from http://r.research.att.com/tools/.

The next step is to build a binary for each architecture. This can be either done natively on two machines - one PowerPC and one Intel based Mac, or by cross-compiling the PowerPC part on an Intel Mac. In either case, the configuration is the same.

Configure, build and install the ppc binary (assuming R-2.12.2.tar.gz is in the current directory, replace R-2.12.2 with any other version or name as appropriate):

     tar fxz R-2.12.2.tar.gz
     mkdir R-ppc
     cd R-ppc
     ../R-2.12.2/configure r_arch=ppc CC="gcc -arch ppc" \
     CXX="g++ -arch ppc" F77="gfortran -arch ppc" \
     FC="gfortran -arch ppc" OBJC="gcc -arch ppc"
     make
     make install
     cd ..

Depending on your permissions, you may need to run sudo make install. The next step is to build and install the Intel binary:

     mkdir R-i386
     cd R-i386
     ../R-2.12.2/configure r_arch=i386 CC="gcc -arch i386" \
     CXX="g++ -arch i386" F77="gfortran -arch i386" \
     FC="gfortran -arch i386" OBJC="gcc -arch i386"
     make
     make install
     cd ..

The installation scripts in R are intelligent enough to merge both builds together and create a universal R framework. One crucial requirement for this to work is to use i386 and ppc as the architecture names. Other supported architecture names are ppc64 and x86_64 for 64-bit builds. One R installation can contain all four architectures.

Finally, the standard R shell script uses by default the last installed architecture. This is probably not what you want, because the native architecture is known at run time. Therefore the line

     : ${R_ARCH=/i386}

can be replaced by

     : ${R_ARCH=/`arch`}.

to default to the current native architecture. It addition, it may be a good idea to make sure that the PATH environment variable contains the path to your universal compiler, otherwise there may be problems with compilation of universal packages. Those are also modifications that you will find in the CRAN release as compared to vanilla R (plus the default of package type being binary instead of source).

To run a specific architecture use the --arch flag when starting R, e.g., R --arch x86_64 for 64-bit R on Intel platform.

Starting with R 2.10.0 installations on Mac OS X 10.6 (Snow Leopard) default to 64-bit if the host CPU supports is. All other installations use the native platform type (which is 32-bit in most cases).

Command line version of R
*************************

The command line version of R is identical to R as used on other unix operating systems. Therefore 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.APP so please read the related notes (see How to get R.app). 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 /usr/local/bin directory on your system (if you do not have one, you can use /usr/bin instead) you should just type in your Terminal (a root password is required)

     sudo ln -s /Library/Frameworks/R.framework/Resources/R /usr/local/bin/R

Assuming that you have /usr/local/bin in your PATH environment variable, you will be able to launch R from any location on your system just by typing R. In this way, when you install a new version of the R.framework this link will point to the latest R binary.

R.app
*****

R.APP is the name of the Cocoa-based GUI for Mac OS X that was introduced in R 2.0.0. It appears as an icon labeled R, but to avoid confusion with general R, we prefer to use the name as it appears when using Get Info on the GUI: R.APP This stands for R application.

Internally R.APP is a Cocoa program (hence written in Obj-C) that loads the R dynamic library in order to use R facilities.

Historically there were two more GUIs for Mac OS X: RAqua and Cocoa GUI bundle. The latter was never officially released and RAqua was retired in R version 2.1, because it used legacy toolkit from the times of MacOS9.

How to get R.app
================

R.APP is part of the binary distribution of R for Mac OS X available from CRAN. That distribution consists of one disk image containing multiple packages including the R framework and R.APP.

Development versions of R.APP are made available on daily basis in the form of a disk image containing the R.APP itself. See the Mac OS X pages on CRAN for detail how to obtain such images (currently at http://R.research.att.com/).

How to install the R.app
========================

R.APP is installed the same way as the R framework, namely using binary package provided on CRAN. The bin/macosx directory of a CRAN site contains a standard Apple installer package inside a disk image named R.dmg (optinally containing the version number). Download and double-click the image. New window will appear with a package icon representing the installer. Double-click that icon and it will install the current non-developer release of R, including R.APP.

Please, carefully read the note on the usage of tcltk and Fortran on the bin/macosx directory of a CRAN site, e.g. http://cran.cnr.berkeley.edu/.

Nightly builds typically come as a disk image that contains R.APP itself and thus can be started directly from the disk image or installed by dragging the icon in the Applications folder.

The R Console
=============

In this section you'll find general information on the R.APP. For specific R tasks that can be done via the R.APP using menus you should read below (see The Menus).

The Input and the Output
------------------------

The current design of the R Console is to have a single frame for input (user) and output (R).

Copy and Paste
--------------

Copy and paste works in R as in any other Macintosh application.

If you want high resolution graphic exports, you can save the PDF format using the File/Save as menu item (see Quartz device). Or you can use supported formats in R through pdf(), jpeg() etc. (type ?capabilities to get more details).

The current and startup working directories
-------------------------------------------

If not otherwise specified in the Preferences (see 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 setwd R command or using the Misc menu item Change working directory. Finally it is possible to use a specific directory for a single R session by dragging a folder onto the R.APP icon. If R.APP is not runnig, this will cause R.APP to be started in the directory corresponding to the folder dragged. The same can be achieved on the command line - for example open -a R . causes R.APP to be started using the current directory as the startup working directory.

This feature is useful if you want different startup procedures defined by the .Rprofile; you can edit a .Rprofile (containing you personal initialization R commands) in a particular directory and use the Preferences (or any other method mentioned above) to change the startup directory. Next time you launch R.app the .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.

Resizing the R Console
----------------------

When the R Console Window is resized, the R option width is set appropriately so that any future output will fit the window size.

R Console text colors
---------------------

Use the Preferences window to set the R Console text colors (see Preferences).

General Features
================

Editor
------

R.APP provides an integrated editor for editing of R code. It sports a number of features designed to help developing code inside R. The probably most often used function is the ability to execute code directly from the editor by pressing Command-Return. Other features include syntax highlighting, brace-matching, code completion and function indexing.

Editor undo and line numbers
----------------------------

The editor supports undo/redo operations on an appropriate level of granularity (used to be all or nothing). The editor has an optional facility to show line numbers. These help with locating error messages. The editor also responds to the 'Go to Line' Edit menu function. The associated Preference Pane allows enabling/disabling of the line numbers, as well as setting line number gutter width (to fit larger line numbers) and text margin width.

Editor text completion
----------------------

Completion of typed input (both file names and R code) in the editor is available through the Edit menu 'Complete' or by typing Control-. (same as is Xcode). It uses the same facilities as the console window (for compatibility the console responds to both Tab and Control-.).

Editor function list
--------------------

The editor maintains a popup list of functions defined in the edited document. The list is available in the toolbar and is updated as you type. Selecting a function from that list causes the cursor to jump to the beginning of the function.

Editor syntax coloring
----------------------

The editor supports syntax-highlighting for R code. It is possible to change the syntax highlighting colors using the Syntax Color Preference Pane (see below). Starting with R.APP version 1.17 lazy syntax highlighting is used, which means that changes influencing the entire file (such as typing a single or double quote) no longer apply to the entire file, but only a few lines. This temporary state is usually recovered by closing the quote, but in some rare instances it may persist until a change is made to the first line of the offending quote. However, lazy highlighting brings huge speedup when editing large files.

Editor (internal and external)
------------------------------

By default, the editor used is incorporated into R.APP, the Mac OS X GUI for R. It is a relatively simple multi-document editor that supports the features listed above. Additionally, two powerful commands are available to source the file being edited in its entirety (Command-E) or to source the current selection to R (Command-Return). Using R's edit() function, allows editing of R objects or files while R is kept waiting for the edit session to finish.

It is possible to 'redirect' all R requests to an external editor, which runs outside R.APP. In that case, it is not possible to keep R waiting if edit() is used. Using AppleScript it is easy to implement Command-E and Command-Return like functionality.

Editor help
-----------

The editor contains a light-weight help system in form of a search filed placed inside the toolbar. It is possible to use either an exact or approximate search.

Drag & drop
-----------

Drag and drop of a directory on the R icon while R is not running will start R and set the working directory. By default .RData and .Rapp.history are fetched from this working directory. If a file is dropped on the R icon while R is not running, R is started, the file is either restored (if it is a saved workspace), sourced into R or opened in the selected editor. Whether the file is opened or sourced is specified by a Preference setting in the StartUp Preference Pane.

Note: At this point opening a file in the editor before R is finished loading will crash R.

While R is running, d&d of a directory updates the working directory. D&d of a file sources or opens the file in the selected editor. Double clicking on files bound to ("Open With ...") R, if R is not running, R is started and the file is sourced or opened in editor. If R is running, the file is opened in the editor.

Help system
-----------

The Help screen allows a user to go back or forward to previous help pages. It is possible to print help pages. If a help topic is not found, a pop-up window allows to exit the help search or expand the search to a fuzzy/approximate search.

History
-------

R.APP uses history files that are (superset) compatible with history files created by R. Multiline support remains available from inside R.APP. Multiline is particularly useful when using the Command-Return feature while editing an R script. Import and export allows storing and importing history from files visible in the Mac OS Finder. Multiline is preserved. This can be set through the StartUp Preference Panel. Default number of kept history entries is 250. A variety of history entry cleanup modes is possible. At a minimum it is suggested to select "Cleanup history entries". It's optional to select removal of duplicate entries and strip comments.

Note: R itself sometimes stores history in a file usually called .Rhistory. It is suggested to use a different name for the R.app history file.

Authentication and .libPath
---------------------------

The official CRAN binaries come pre-packaged in such a way that administrator have sufficient privileges to update R and install packages system-wide. However, the default unix build requires root-authentication for package instllation and other administrative tasks. As it is not feasible to run the GUI as root, we provide the possibility to authenticate system commands issued from the GUI. The authentication requires an administrator login and causes all subsequent system commands to be executed as root. Use with care!

In order to allow non-administrators to maintain their own set of packages, R.APP optionally adds ~/Library/R/x.y/library to the .libPaths (see start-up preferences, x.y denotes the R version without patch level). It is possible to use the Package Installer to install packages either globally (admin users only) or for the current user only.

Note that user-local packages are only used when the corresponding preference option is enabled. The default for admin users is to use system-wide directorie, for non-admin users local packages will be used.

The Menus
=========

Application Menu
----------------

The Application menu is the first one after the main Apple Menu.

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 (see Preferences).

File Menu
---------

This menu provides standard functionalities. The open command is associated to the action  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 source.

Misc Menu
---------

Apart for standard functionalities, the only relevant item in this menu is the Edito Object which is an interface to the  R edit function.

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

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 load and save R commands. The only relevant item, which is specific to this GUI, is the 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).

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 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 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 (see 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 How to install packages.

The Help Menu
-------------

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

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.

Startup
.......

The Drag & drop section defines drag & drop behaviour during R start-up. Options are to open file in an editor or to source file. Default is to source the file. The Default Library Paths section enables, on next start-up of R, to add a directory, e.g. ~/R/Library, to the library search/install path. The initial working directory section can be used to enforce the initial working directory. If no directory is specified, this directory is used as the default. The Change button allows to select a new directory. The Always apply selection will enforce the specified intial start-up directory. The history section controls reading of the history file on startup. If selected, R will read history file on start-up. The R history file field is used to read and store history from/to. This field can be edited to allow selecting files starting with a period (e.g. .Rapp.history). If you want the same history file regardless of your selected working directory, specify a fixed path (e.g. ~/.Rapp.history). The Default button will reset the history file name to its default value. The History handling area allows setting of the max number of entries to be kept in history, to remove duplicate entries, to cleanup history entries (this is very useful to remove blank lines when submitting multiple lines using Command-Return) and the strip comments before the entry is added to the history.

Editor Preferences
..................

If Built-in editor is selected, allows enable/disable of syntax coloring, brace highlighting and the showing of line numbers. If External editor is selected, allows specifying which external editor. That editor will be used for all editing functions. It runs as a separate application. Using an external editor means that R will never wait while editing (e.g. edit(A) will return immediately and open A in the external editor. Command-E and Command-Return like functionality would need to be implemented by other means, i.e. AppleScript. The external editor can be any application (e.g. SubEthaEdit, TextWrangler, BBEdit, Smultron, etc) or can be activated through a shell script (e.g. see or smultron, both give better control on how to start the editor).

Syntax Colors
.............

Enables to select the syntax colors.

Console Colors
..............

Enables to select the input/output colors in R Console.

Quartz window
.............

Currently the the Quartz preference pane is not being used.

The near future of the R.app
============================

We have introduced R.APP in R 2.0. Although it was a new apporach, tt that point it was mainly replicating features fount in the old Carbon GUI. With R 2.1 we have moved more towards look at feel of the OS X operating system and worked mainly on improving the editor and its integration. In the near future we want to continue to improve the interface, add new features and exploit the possibilities of Mac OS X 10.4 (Tiger).

The R.APP is still very much a moving target. Although we release official versions with each R release, we continue to work on R.APP and offer experimental builds that can be used with the last official release of R. See http://R.research.att.com/ for the current links to the most recent R.APP.

R.app Bugs
==========

On Unix systems a bug report can be generated using the function bug.report().  This automatically includes the version information and sends the bug to the correct address.  Alternatively the bug report can be emailed to R-bugs@R-project.org or submitted to the Web page at http://bugs.R-project.org/.

Before you fill a bug report, please try to reproduce it using both R.APP and the console version of R (if applicable). If the bug if R.APP-specific, please report the bug to R-SIG-Mac@R-project.org instead. Please do NOT forget to mention the exact R.APP version and include the output of sessionInfo().

In any circumstances, in case of a crash, please report the crash.log for the R.bin and/or R.app application. You can get this crash.log using the Console.app located inside /Applications/Utilities (select `1' in the crash menu in the R console at the time of the crash (if you see that menu) to generate a crash report).

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 install.package. For the R functions see the standard R documentation.

Which kind of packages can I install using the GUI?
===================================================

At the moment the GUI provide direct access/download/installation of packages located on CRAN, the Bioconductor repository or a custom 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 (see install.packages) to install packages from a specific location other than the above mentioned ones.

Installation of packages
========================

R for Mac OS X recognizes packages in two forms: binary packages and source packages.

Binary packages are R packages in ready-to-use form, such that no additional tools are necessary for their use. Binary packages are specific for a given R version and OS. CRAN and Bioconductor repositories offer R packages in binary form for the last released R version. Unlike on other unix systems, R for Mac OS X installs binary packages by default, i.e. install.packages will look for binary repositories unless instructed otherwise.

Source packages are general in that they can be used on any platform and OS supported by R, but they need to be processed and/or compiled before they can be used. Additional tools are necessary for that, see Installation of source packages for details. For most users binary packages are sufficient.

On Mac OS X packages can be installed in three ways:

  * Using Package Manager in the R.APP GUI (recommended for most Mac users)

  * Using install.packages command in R

  * Using R CMD INSTALL command in the shell (aka Terminal)

The latter two methods are common to all unix systems and as such described in the general R documentation. In the following we will concentrate on using the Package Installer.

If you decide to install packages you should use the Packages & Data menu of the GUI, in particular the sub-item Package Installer. Select the repository, package type (binary or source) and press Get List. This will connect to the repository through the Internet and a list all packages available for installation. The 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 use the search field to narrow the list of package to those matching your search criteria. Additionally you can use the search list menu to list only packages that are already installed on your system which is useful for comparing versions of available and installed packages. Finally, you can filter down to packages that have been installed by a previous R version as to allow a simple upgrade.

Select any package you want to install and press the Install button. You can follow the progress of the installation in the R Console. Once the required packages are installed, the list is re-loaded to reflect the versions of newly installed packages.

If you want to update all packages to the latest version, select the repository to use for the packages and press Update All. R will automatically determine the list of packages that can be updated and present you with a selection of packages to update.

You can also download any other package from the Internet yourself and decide to install it from source. In such case select one of the local entries in the top left list and press the Install button (which is now enabled).

Packages can also be installed from other repositories by selecting Other Repository source. Enter the repository URL in the adjacent field. Note that currently the Package Installer assumes that custom repositories maintain proper hierarchy for both source and binary packages the same way CRAN does when using Other Repository. If your custom repository is flat, select Other Directory URL in the installation type list.

Installation of source packages
===============================

Usually it is much faster and easier to install binary packages, because they are immeditely ready to use. On the other hand only packages that pass all tests are available in binary form from CRAN. If your desired package is not available in binary form, you will need to use its source form. Source packages have to be compiled first before they can be used. If you want to install a source package, you will need the same working setup for building R itself (see Building R from sources), including Apple Xcode Tools and a working FORTRAN compiler (if the package requires it).

Important: When using binary R installation from CRAN, you must use Xcode 3.1 or higher (available from see Apple Developer Connection). Although R can be built using older tools, the way it is build depends on the version of the tools and therefore your must upgrade at least to Xcode 3.1 (or preferably the latest available) which is compatible with the CRAN build. Failing to do so will result in either of the following errors at compile time:

     make: gcc-4.2: Command not found

     cc1: error: invalid option 'macosx-version-min=10.4'

     /usr/bin/libtool: unknown option character `m' in: -macosx_version_min

A sign of missing Xcode tools is when the installation fails with

     make: command not found

In all such cases, please install the most recent Xcode Tools version available from see Apple Developer Connection.

Building universal packages
===========================

Starting with R 2.3.0 the same binary package can be used for both PowerPC and Intel based Macs. Such a package is called universal, because it works on either platform. Building universal packages requires special handling. First, R itself must be compiled as universal binary to support universal packages at all. The CRAN binary is built this way, see How to build universal R for details.

Further, universal binaries can be currently built on Intel Macs only. The main reason is that the default Mac OS X installation on PowerPC based Macs does not include system libraries for Intel Macs (experienced users can try to add corresponding -isysroot for 10.4u SDK to CC). If you happen to have a PowerPC machine with full system libraries it should work. Finally, a compiler supporting both platforms is necessary, see How to build universal R.

Once all tools are in place it is considerably easy to build an universal binary. If the package does not contain a configure script then a regular package installation using either install.packages or R CMD INSTALL automatically creates an universal binary. If the package contains a configure script then it cannot be compiled in-place for multiple platforms, and the following process should be used. Assuming that you have a source package called foo_1.0.tar.gz that uses a configure script, it can be installed universally using the following three-step process:

     # full 32-bitIntel install
     R --arch=i386 CMD INSTALL foo_1.0.tar.gz
     # 64-bit Intel library
     R --arch=x86_64 CMD INSTALL --libs-only foo_1.0.tar.gz
     # 32-bit PowerPC library (will require Rosetta to build)
     R --arch=ppc CMD INSTALL --libs-only foo_1.0.tar.gz

In the first step a full package for the Intel platform is built and installed. In the following steps a package for 64-bit Intel platform and PowerPC is built, but only the relevant binary libraries are installed. This way all platforms share the same set of files except for the package library.

R CMD INSTALL --build does not support universal binaries of packages that contain configure scripts for reasons stated above. Therefore it is necessary to create the resulting tar-ball manually. The following is just one example how the process could be automated (replace first line with the real package name and version):

     pkg=foo_1.0
     rm -rf /tmp/pkg
     mkdir /tmp/pkg
     R --arch=i386 CMD INSTALL -l /tmp/pkg $pkg.tar.gz
     R --arch=x86_64 CMD INSTALL -l /tmp/pkg --libs-only $pkg.tar.gz
     R --arch=ppc CMD INSTALL -l /tmp/pkg --libs-only $pkg.tar.gz
     tar fvcz $pkg.tgz -C /tmp/pkg `echo $pkg|awk -F_ '{print $1}'`
     rm -rf /tmp/pkg

Normally, building a package from sources produces a binary that is tied to the developer tools that you compiled it with, especially if FORTRAN is used, because it requires run-time libraries. Anything you compile with a Fortran requires that you have that Fortran installed at run time, because Fortran uses its own run-time libraries (if the Fortran you compiled with used dynamic libraries). This implies that if you distribute your package you have to tell users to install the same Fortran you used to compile it.

However, unlike other unices Mac users do not necessarily have development tools installed, so on CRAN we make an effort to modify the binaries such that they work even without the tools they have been compiled with. There are several possible approaches, but since R itself already uses the same Fortran, we ship a copy of the Fortran libraries inside R and modify packages such that they use it instead of the one from developer tools.

If you want to share a binary with multiple users and don't want to require them to install Xcode, you can use the same approach as CRAN but only if you use the same tools as we do on CRAN. It means to change the path of the FORTRAN dynamic library (libgfortran) to point inside the R version that you are compiling for. For example, if you have installed a universal package FOO for R 2.12.x, you can change the paths as follows:

     # change into the library where you installed FOO
     cd /Library/Frameworks/R.framework/Resources/library
     # fix the Fortran paths in FOO to point to R 2.12 instead
     for lib in `ls FOO/libs/*/*.so`; do
      install_name_tool -change /usr/local/lib/libgfortran.2.dylib \
        /Library/Frameworks/R.framework/Versions/2.12/Resources/lib/libgfortran.2.dylib \
       $lib
     done

Can I install packages built for other platforms?
=================================================

As a general rule the answer is yes if the package does not contain any C/C++/Fortran code in the sources, otherwise the answer is negative. Another condition is that the package and the installed version of R should be the same major release, i.e. you can install a package built for R 2.1.0 on R 2.1.1, but usually not the same package on R 2.2.0.

A Mac OS X specific requirements is that a prebuilt package is assumed to be named (and accordingly archived and compressed) as package_name.tgz. The build script uses the more common extension .tar.gz and thus the resulting file must be renamed. On Windows, for example, packages come in a zipped format.

Where are the packages I've installed?
======================================

The main library of packages is the one located inside the R.framework (in /Library/Frameworks/R.framework/Resources/library). This library contains the packages (base and recommended ones) distributed along with R. Only administrators are allowed to install packages in this system-wide directory. Note that this directory is R-version-specific. Optionally users can install private packages in their ~/Library/R/x.y/library directory where x.y denotes the R version without the patch level (such as 2.12) - see startup preferences.

The Package Installer performs installation to either place depending on the installation target setting. The default for an admin users is to install packages system-wide, whereas the default for regular users is their private place.

If you happen to use install.packages R function instead of the Package Installer, the regular unix behavior applies (see help pages for details). For default setup this means that the packages are installed according to the startup preference setting. You can check the current defaults by issuing

     .libPaths()

Note: When upgrading to a next major release of R, users should delete their ~/Library/R/library directory, because packages are incompatible across major R versions. When you experience problems loading packages or starting R after an upgrade, make sure you don't have packages for your old R version floating around. More recent versions of R.APP (1.19) include the version number in the path to prevent this from happening.

R and external applications
***************************

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 cmd applescript command.

     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

In the above, 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

     cmd <command string>

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.

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.

As an example, we report here a small script that asks R to source a file using a file dialog.

     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

External editors
================

R accepts the Apple Event command 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 http://www.kelehers.org/alpha/).

Finder actions
==============

Dragging a file on the R icon, causes R to source this file via the source R command or, if the file is an R image data file RDX1 or RDX2 (normally files with extension .rda or .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 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 do the right thing.

If R is not yet running this action causes R to startup.

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

Interactive mode
================

The quartz device allows for interaction. You can use both identify and 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. If you happen to have a multi-button mouse, you can use any of the additional buttons to break the loop, unless you re-defined the function of the buttons.

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). However, this process uses R's PDF device and not Mac OS X PDF facilities and thus doesn't yeild an exact copy of the device contents. For Mac-native solution, see (see Copying the image into the clipboard) and quartz.save command.

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 both a PDF versiond and a bitmap version of the quartz device window. Which version will be used depends on the pasting applications, most modern application will prefer the PDF version which is of higher quality as it supports vector graphics. Note that there is currently a difference between using the clipboard and saving to a PDF file (see Saving the image). The latter will use R's PDF device which will not yield WYSIWYG results. However, using quartz.save command will produce the same result as the clipboard operation.

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.

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 R.APP you need to also define the environment variable DISPLAY before attempting to use X11 from inside R (Mac OS X 10.4 and earlier only!). You can do this as follows

     Sys.setenv(DISPLAY=":0")

If you don't like the X11 GUI you would probably want to build R using the Aqua version of TclTk (see Aqua TclTk headers and libraries (optional)).

Note: Mac OS X 10.5 (Leopard) now comes with a ``feature'' that changes the way X11 server is setup. As a consequence DISPLAY variable should not be touched or it will impede that mechnism. The good part is that it should start X11 automatically.

Internationalization of the R.app
*********************************

R and the R.APP GUI introduced support for internationalization in R 2.1.0. Among other things this means that both messages and GUI elements can be translated into various languages. R.APP automatically detects user's settings in the International section of the System Preferences and uses that information to offer translated messages and GUI if available. Please note that both Language and Formats information is used so they should be set up consistently.

If you use a non-standard setup (e.g. different language than formats), you can override the auto-detection performed by setting force.LANG defaults setting, such as for example

     defaults write org.R-project.R force.LANG en_US.UTF-8

when run in Terminal it will enforce US-english setting regardless of the system setting. Please note that you must always use .UTF-8 version of the locale, otherwise R.APP will not work properly.

Another change from previous versions (R 2.0 and R.APP 1.01) is the support for UTF-8 character encoding. By default R.APP uses UTF-8 for newly created documents and for the console. When opening new documents R.APP assumes UTF-8 and only if the document violates UTF-8 rules, it will try to fallback to legacy encoding, usually Mac Roman.

If you are interested in translating R.APP GUI into other languages, please read the developer documentation http://developer.r-project.org/Translations.html for details.

Additional resources
********************

Here are few references that can be of interest for Mac OS X and/or developers.

Apple Developer Connection
==========================

The Apple Developer Connection (can be reached at 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).

The R for Mac OS X Developer page
=================================

There is a page dedicated to development versions for R for Mac OS X. This page is located at http://R.research.att.com/ and is maintained by Simon Urbanek. It contains latest nightly builds of R and R.APP as well as information on tools necessary to build R.

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.

Sparse questions
****************

How can I have a per session .Rprofile?
=======================================

You can by writing a .Rprofile file in your favorite session directory and change accordingly the startup working directory using the Preferences (see The current and startup working directories).

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 (see Finder actions). If R is not yet running it will be launched.

How can I interrupt lengthy operations or output?
=================================================

In R.APP you can use the the Stop toolbar button or the ESC (escape) key in the console window to interrupt a running calculation or output.

For the command line version the same is achieved by pressing Ctrl-c. Both applications honor the INT signal, i.e. you can type the following in a separate Terminal window to cancel all R computations:

     killall -INT R

However, if the executed code does not check for interrupts (using R_CheckUserInterrupt) there may be no way of stopping R. In that case it may be worth alerting the maintainer of the package to allow interruption (if appropriate).

I see spurious error messages when starting R!
==============================================

If you see error messages upon start of the R GUI which contain Library/InputManagers anywhere in the text, then you have some broken haxxies installed in your system. Those messages do NOT come from R, so don't blame us. Bundles located in Library/InputManagers of your home (or system) are hacks that get loaded into every Mac application that you start. In most cases you don't see them crashing, because most applications don't show the console output, but R does, so all the errors those hacks are causing become visible. The easiest remedy is to delete all offending bundles (possibly the whole Library/InputManagers folder) and get a fixed version of the hack (if you need it). The most common cause for broken hacks is system updgrade (e.g. you get a new Mac and you transfer you settings which include those hacks that are incompatible with your new Mac).

If you want to disable all external error output in the GUI, use

     defaults write org.R-project.R 'Ignore stderr' YES

in the Terminal. Note, however, that this will disable all error output from external programs including package installation or the system command.

Which BLAS is used and how can it be changed?
=============================================

The BLAS library used by R depends on the way R was compiled (see `R Installation and Anministration' manual for details). Current R binaries supplied from CRAN provide both vecLib-based BLAS and reference BLAS shipped with R. vecLib is a part of Apple's Accelerate framework which provides an optimized BLAS implementation for Mac hardware. Although fast, it is not under our control and may possibly deliver inaccurate results.

The CRAN binary uses --enable-BLAS-shlib option and two Rblas shared libraries are supplied: libRblas.vecLib.dylib which uses vecLib BLAS and libRblas.0.dylib which uses reference BLAS from R. A symbolic link libRblas.dylib determines which one is used. Currently the default is to use vecLib for speed, although R BLAS is recommended for precision.

In order to change which BLAS is used, change the libRblas.dylib symlink correspondingly - for example in Terminal:

     cd /Library/Frameworks/R.framework/Resources/lib

     # for vecLib use
     ln -sf libRblas.vecLib.dylib libRblas.dylib

     # for R reference BLAS use
     ln -sf libRblas.0.dylib libRblas.dylib

This feature is only present in the R CRAN binary. Ordinarily compiled R from sources will only have one of the above BLAS libraries, corresponding to the configuration options used.

I don't see a thing when installing packages!
=============================================

The output is not produced continuously during the package installation. Unlike previous GUIs R.APP does its best to display the output as soon as possible, but for example the documentation script does not print anything until done.

Also note that the development build of R.APP sends output to the error console instead of the screen. You may want to check the Console application in that case.

Why do I need custom compilers for the CRAN binary?
===================================================

As of R 2.5.0 the custom compilers are no longer necessary (save for Fortran). CRAN binary is now built using Apple's gcc compiler from Xcode Developer Tools 3.1.4 and a GNU Fortran 4.2.4 compiler. Xcode doesn't contain a Fortran compiler, therefore we must supply our own. It is available from http://r.research.att.com/tools/.

CRAN binaries of R versions 2.3.0 to 2.4.1 supplied their own complier (gcc 4.0.3 in /usr/local/gcc4.0), overriding the Apple-supplied compiler. The system compiler was kept in place, but R used the new compiler for compiling packages instead. The main reason for this was that the compiler supplied by Apple contained several fatal bugs that lead to crashes of R due to incorrectly generated code, especially for the Intel Macs. This has been fixed in Xcode 2.4.0 so we switched back to Apple's compilers for R 2.5.0 and later.

Why are Quartz plots much bigger than they used to be?
======================================================

R versions before 2.7.0 had a Quartz window that was smaller both in size and scale. This was caused by two ``bugs'': all devices in R have a default size of 7 inches. Quartz used a default of 5 inches and that was now changed to match all other devices. In addition, Quartz was incorrectly assuming a resolution of 72dpi for all screens. This means that a plot was drawn at ca. 3/4 of its intended size (given that most modern monitors use 100 dpi or more). The new Quartz device correctly detects the resolution of a screen by default and thus the plots will appear larger than they used to be. The resolution can be set using the dpi parameter of Quartz, i.e. to obtain the old behavior use quartz(width=5,height=5,dpi=72) when creating a new Quartz device. If you want to make this your default, use quartz.options(width=5, height=5, dpi=72). You can also set those options in the Quartz Preferences of the R.APP GUI.

Some other new features of Quartz in R 2.7.0 include a plot history (use <Cmd><Left> and <Cmd><Right> to browse), improved speed (uses Quartz Extreme) and the ability to create a variety of output formats (pdf, png, jpeg, tiff, gif, psd, bmp...) - see ?quartz for details. Also CarbonEL is no longer needed, Quartz starts its own even loop when necessary.

Why is Quartz so slow?
======================

In R 2.7.0 a new Quartz device was introduced for greater flexibility and speed. It was designed to take advantage of Quartz Extreme and hardware rendering where supported. Nonetheless it turned out that the way lines are drawn can be very slow for certain back-ends if Quartz falls back to software rendering. This issue was addressed in R 2.7.0 patched (r45567 or later). If you experience extreme slowness drawing lines or glitches in drawing, please update to R 2.8.0 or later.

Why are there faint lines in image plots?
=========================================

When plots based on the image() function are exported to PDF, Preview shows very faint grid lines at the edges of the rectangles that create the image. Those lines are a rendering artifact in Preview coming from the combination of anti-aliasing and sub-pixel rendering. They are not really a part of the PDF (zooming in will reveal that they are not a real object which would get larger with zoom) since the recangles are defined as a gapless coverage of the area. The effect can be circumvented by disabling anti-aliasing in Preview.

We correct for this effect in Quartz when rendering on-screen by snapping all recangles to pixel boundaries of the screen, but Preview does not.

The samme effect occurs in any plot with adjacent, filled polygons without border.

Why doesn't x86_64 build of R pass make check on Mac OS X 10.5.2?
=================================================================

Mac OS X 10.5.2 contains a very serious bug that makes log10 return incorrect results in 64-bit Intel programs (x86_64). The bug was fixed in Mac OS X 10.5.3 therefore you have to update to Mac OS X 10.5.3 if you want to use 64-bit Intel binaries.

If you want to create a binary that works on all versions of Mac OS X 10.5, you have to replace log10 by something like #define log10(X) (log2(X) * 0x1.34413509F79FFp-2) (see Apple SciTech mailing list for the corresponding discussion and different work-arounds).

Why doesn't R GUI support keyboard shortcut XYZ ?
=================================================

The R.APP GUI uses Apple frameworks for text editing and thus the behavior of text views (console, editor, etc.) is consistent with other applications and allows a very flexible customization. For example if you are not satistied with the default Emacs-like key bindings that Mac OS X provides, Apple allows you to extend them arbitrarily. For more details see Apple's documentaton on Key Bindings (http://developer.apple.com/documentation/Cocoa/Conceptual/EventOverview/TextDefaultsBindings/chapter_9_section_2.html). There are also many 3rd-party pages on key bindings customization, search for StandardKeyBinding.dict.

What is the difference between the Leopard and Tiger builds?
============================================================

Before R version 2.11.0 we provided two different binary builds on CRAN: Tiger (Mac OS X 10.4) and Leopard (Mac OS X 10.5) builds. The Tiger build was a 32-bit build for PowerPC and Intel and works on Mac OS X 10.4 or higher. It was built using the same setup as R prior to 2.8.0. It included two architectures i386 and ppc. The default package type was "mac.binary" and packages in repositories were expected in bin/macosx/universal/contrib/2.x.

In contrast the Leopard build requires Mac OS X 10.5 or higher and thus uses features that are new in Leopard. Also it includes both 32-bit and 64-bit architectures. On the console 64-bit version can be started using R --arch=x86_64 for Intel Macs or R --arch=ppc64 for PowerPC Macs (if included). There are two GUI binaries -- one for 32-bit and one for 64-bit. The Leopard build uses Apple's gcc-4.2 compilers, the default package type is "mac.binary.leopard" and consequently packages are expected in bin/macosx/leopard/contrib/2.x. Note that some packages may not be available in 64-bit (e.g. if dependent libraries are not available in 64-bit).

What is the difference between the CRAN build and a vanilla build?
==================================================================

The CRAN build of R is silghtly different from a vanilla build of R, i.e., a simple ./configure && make && make install. The default package type for all builds compiled from sources is "source" wheres CRAN uses "mac.binary" or "mac.binary.leopard" (see above). Only the CRAN build is guaranteed to be compatible with the package binaries on CRAN.

In addition, the CRAN build contains multiple architectures (two, three or four) and thus corresponds to setting r_arch at configure time and installing each architecture. This poses some challenges for package installation, since packages with a configure script need to be installed several times (see package installation FAQ above). Therefore it is recommended for users to install binary packages instead.

Further, the start script for the CRAN build is modified to launch the current architecture instead of the most recently installed one. Also PowerPC machines don't attempt to install other architectures due to missing universal files (this can be also (ab)used by setting NATIVE_ARCH=/ppc on any architecture to force analogous behavior).

Since R 2.8.0 the CRAN binary also contains (statically) the most recent FontConfig with configuration and cache located inside R. See the tools directory in CRAN for the corresponding libraries and details.

Why is R.home() in the R framework not versioned?
=================================================

In the command line version of R R.home() always points to the Resources directory symbolic link inside the R framework which points to Versions/Current/Resource which is turn points to the actual home -- a versioned directory such as for example Versions/2.11/Resources. This is how framework versioning works in Mac OS X and is defined by Apple (see Framework Anatomy (http://developer.apple.com/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/FrameworkAnatomy.html)).

The advanatage of this setup is that it is possible to install multiple R versions in parallel and they all will be fully functional as long as the Current symbolic link points to the currently used version. There is even a small GUI utility RSwitch available form the R for Mac devel page (http://r.research.att.com/) that allows you to select the desired version. In addition, any application embedding R (such as the R GUI) can choose to use a specific R version (in most cases) or any version.

Although it is possible to set R_HOME directly to the versioned path in the R shell scripts (and thus be able to run different version in parallel without changing the symbolic link), there are several dangers lurking there so we don't recommend it. One problem is that building packages from source won't work. The linker is always linking against the current version of the framework and therefore only the currently active version of R can compile packages. Further, packages may have used the value of R.home() at install time and thus may not work with incorrect setting. Similar problem may arise with help pages. Finally, if such an R start script happens to get copied and the R version changes, it will stop working.

R.app GUI crashes on startup!
=============================

If your R.app GUI crashes on startup, there are usually two major causes for this: saved workspace or corrupted history

Saved workspaces can contain commands that implicitly load packages which in turn can trigger bugs in packages or feed R with incorrect starting values (especially if it was saved using another R). Try removing or renaming your workspace -- it's called .RData. If you did not change your startup settings, you can e.g. use

     mv ~/.RData ~/workspace.RData

to move it aside and load later manually for inspection using load("~/workspace.RData").

Second most common cause of crashes on startup is a history file that was not created using the R.APP GUI. Again, move it aside to see if that's the issue:

     mv ~/.Rhistory ~/history.txt

Although we are trying to recover from invalid history files, they can still crash R.APP due to issues in the internal handling of strings in Mac OS X. We are currently working on preventing this issue.

If you did both of the above and R.APP still crashes, please select `1' in the menu after the crash (if you get the crash menu in the console) and send us the resulting crash report (see R.app Bugs above).

R.app GUI does not save the workspace!
======================================

When you quit the R.app GUI it asks you whether to save the workspace or not. There was a bug in R.app GUI 1.32 (shipped with the initial release of R 2.11.0) that did not save the workspace even if told to. If you use R.app GUI version 1.32 please make sure you upgrade to 1.33 (or higher) to avoid this bug. The current R on CRAN ships with the more recent R.app GUI version that does not exhibit the problem.

Why is the GUI not saving my history?
=====================================

In some recent versions of R there is a conflict between the history of R itself and the GUI such that the history file will be always empty. In R 2.11.1 the default has been changed such that the GUI will use .Rapp.history file whereas command line R will use .Rhistory so that they will not collide. If you have old preferences, go to Preferences -> Startup in the GUI and click on the Default button next to the R history file text box and close the preferences. This is a work-around until the internal R history and the history of the GUI are synchronized properly.