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.
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 (see Command line version of R), like on any other unix-like system, or via the Aqua GUI (see R with Aqua GUI). This second approach in using R for Mac OS X is mostly preferred by "traditional" Macintosh users.
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.
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 (see 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 (see Apple Developer Connection) In either cases be sure you have gcc version 3.3 just by typing in a Terminal window
gcc -vv
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 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
sudo tar -zxvf g77v3.4-bin.tar.gz -C /
rehash
It installs everything in /usr/local. The name of the .tar.gz archive can be different, see the related web page.
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 ftp://www.gnu.org. You need to modify the original file 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 -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 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
./configure
make
sudo make install
It installs everything in /usr/local.
These instructions apply to both Jaguar and Panther.
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.
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 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:
tar zxf tcl8.4.4-src.tar.gz
cd tcl8.4.4/unix/
./configure
make
sudo make install
For Tk: download the tk 8.4 sources, cd inside the folder where you have downloaded the archive and type:
tar zxf tk8.4.4-src.tar.gz
cd tk8.4.4/unix/
./configure
make
sudo make install
Once you have installed the AquaTclTk libraries and headers files you should configure R using this additional arguments
--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'
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.
Download the latest sources of R from CRAN. 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. Just type
./configure --with-blas='-framework vecLib' --with-lapack --with-aqua
make
This will configure R to be built as a Framework to be installed inside your /Library/Frameworks directory with the name
R.framework. 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 --with-blas='-framework vecLib' --with-lapack
--with-aqua --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.
A standard installation of R requires you have built it as a Framework. At this point just type (a root password will be required):
sudo make install
and all will be installed in /Library/Frameworks.
You can decide to change the R.framework destination by using the prefix option specifying the
final destination.
sudo make prefix=/where/you/want/R.framework/to/go install
As in the above, you don't need to specify the name R.framework in the path.
At the moment, there is nothing special to do to build the Aqua GUI. You just need to install it using
make install-aqua
and it will install the R.app application in the Applications folder on your system.
The install procedure fails if the R.framework has not been installed first.
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 (see 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 /usr/local/bin directory on your System, than 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'll 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.
The bin/macosx directory of a CRAN site contains a standard
Apple installer package named 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
bin/macosx/x.y there are prebuilt binary packages to
be used with R corresponding to the "x.y" release of
R. The installation of these packages is available through the
"Package" menu of the Aqua GUI (see Packages Menu).
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 (see The Menus).
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.
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 quartz() graphic device (see 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 File/Save as menu item (see Quartz device).
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 Tools menu item Change working directory. The current working directory is displayed on the main bar of the R Console window.
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 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.
When the R Console Window is resized, the R option width is set appropriately so that any future output will fit the window size. This behavior can be inhibited using the Preferences settings (see 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.
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 (see Preferences).
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 (see Preferences).
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.
Apart for standard functionalities, the only relevant item in this menu is the Edito Object which is an interface to
the R edit function.
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.
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).
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.
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.
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.
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.
You can set all the parameters of the quartz device for this tab. Please note: your changes only take effect
if you select the final checkbox, namely override the R quartz default settings.
This also apply to the Quartz window position option even if it is not a quartz parameter itself.
From this tab you can set the default repositories for the CRAN and Bioconductor urls. This will affect the
corresponding R options.
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 Console
application which you can find on every Mac OS X installation inside the directory /Applications/Utilities.
You can also set the startup working directory. This is very useful for having different sessions in different directories (see The current and startup working directories and How can I have a per session .Rprofile?).
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 http://www.economia.unimi.it/R.
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/.
You can also send specific Aqua GUI bugs directly to stefano.iacus@unimi.it
In any circumstances, in case of a crash, please report the crash.log for the R.bin application. You can get this crash.log using the Console.app located inside /Applications/Utilities.
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.
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.
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 (see 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.
If you decide to install packages from CRAN you should use the Packages menu of the GUI. In particular the sub-item 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.
You can also download any other package from the Internet yourself and decide to install it from source.
You have to use Packages/->Install form local file submenus. Where you can choose a standard package.tar.gz
tarball or the directory containing your package if you have the package in expanded form.
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.
The second difference is that, when you install packages from local file, it is assumed that the binary package is named
as package.tgz. This is to distinguish among source and binary archives.
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 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.
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.
On Windows, for example, packages come in a zipped format.
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
sudo R CMD INSTALL pkg_ver.tar.gz
By default, the user of R.app installs packages inside the Library/R/library directory
in his home directory, i.e. ~/Library/R/library.
If you install a package using the 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 ~/Library/R/library to the
list of libraries locations. You can do the following from inside R
.libPaths("~/Library/R/library")
or write this command in the .Rprofile file in your startup directory.
On some version of OS X the ~ symbol is not correctly expanded. You should preferably use this
version of the above command
.libPaths(path.expand("~/Library/R/library"))
If you have a version of RAqua.app installed on your system, it is likely that you have all the
packages installed in ~/Library/RAqua/library. You can add this library of packages in the .libPaths()
but most of them will probably not work as they were built for release 1.8.x of R.
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
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/).
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.
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.
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.
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 (see 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 (see 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.
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.
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
Sys.putenv("DISPLAY"=":0")
If you don't like the X11 GUI you would probably want to build R using the Aqua version of TclTk (see 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 Resources/bin directory of the R.framework
(usually /Library/Frameworks/R.framework), then type the following
sudo /Developer/Tools/Rez -t APPL Carbon.r -o R.bin
Here are few references that can be of interest for Mac OS X and/or developers.
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).
There is a page dedicated to the latest R-devel version of R. This page is located at 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.
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.
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).
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.
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.
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
system function, executes outside R in a Mac OS X shell. The package installation is done via
the system facility.
You have to use the Preferences to redirect the stderr and/or the stdout to the R Console (see Misc tab)
or you can look at the Console application inside /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 Console application.