Next: Introduction, Previous: (dir), Up: (dir)
Next: R.app, Previous: R for macOS FAQ, Up: R for macOS FAQ
This document contains a user guide to the R.APP version of R, and information on using R on macOS which supplements the main R manuals, the latest versions of which can be found at http://cran.r-project.org/manuals.html.
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 ‘R for macOS FAQ’ is rather incomplete at the moment and requires contributions from users. Anything specific to the R language can be found in the main 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 mailing list (after subscribing) as well as comments on this FAQ.
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 before asking for help on R-SIG-Mac!
Next: What machines does R for macOS run on?, Previous: Introduction, Up: Introduction
There is only one version of R for macOS. However, R on macOS can be used either on the command-line as on other Unix systems, or via the R.APP GUI (see R.app). The second approach is mostly preferred by Macintosh users.
Next: How can R for macOS be obtained and installed?, Previous: How many versions of R for macOS?, Up: Introduction
64-bit Intel-based Macs, that is any machine made since mid 2008.
As from R 4.1.0 there is a separate build for ARM-based Macs (known as ‘M1’ and ‘Apple Silicon’), although the Intel-based distribution works well under ‘Rosetta’ emulation.
Previous: What machines does R for macOS run on?, Up: Introduction
R is available on CRAN in the form of an Installer package containing the R framework and the R.APP GUI. The package is usually named R.pkg with an optional version number.
The installation is done by double-clicking on the Installer package. The Installer will guide you through the necessary steps. Note that it will require password or login of an account with administrator privileges. The installation can be customized, but the default is suitable for most users.
Snapshots of the R-patched and R-devel flavours are available at http://mac.R-project.org/, packaged in the same way.
Further details, including uninstallation and building R from the sources, are in the ‘R Installation and Administration Manual’.
Next: How to install packages, Previous: Introduction, Up: R for macOS FAQ
R.APP is the name of the GUI for macOS 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 Objective C) which links to embedded R installed as a framework.
Next: How to install the R.app, Previous: R.app, Up: R.app
R.APP is part of the binary distribution of R for macOS available from CRAN. That distribution consists of one package containing 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 macOS pages on CRAN for detail how to obtain such snapshots (currently at http://mac.R-project.org/).
Next: The R Console, Previous: How to get R.app, Up: 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 named R.pkg (optionally containing the version number). Download and double-click the package icon.
Please, carefully read the note on the usage of tcltk and Fortran on the bin/macosx directory of a CRAN site.
Next: General Features, Previous: How to install the R.app, Up: R.app
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).
Next: Copy and Paste, Previous: The R Console, Up: The R Console
The current design of the R Console is to have a single frame for input (user) and output (R).
Next: The current and startup working directories, Previous: The Input and the Output, Up: The R Console
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).
Next: Resizing the R Console, Previous: Copy and Paste, Up: The R Console
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 running, 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.
Next: R Console text colors, Previous: The current and startup working directories, Up: 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.
Previous: Resizing the R Console, Up: The R Console
Use the Preferences window to set the R Console text colors (see Preferences).
Next: The Menus, Previous: The R Console, Up: R.app
Next: Editor undo and line numbers, Previous: General Features, Up: General Features
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.
Next: Editor text completion, Previous: Editor, Up: General Features
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.
Next: Editor function list, Previous: Editor undo and line numbers, Up: General Features
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-.).
Next: Editor syntax coloring, Previous: Editor text completion, Up: General Features
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.
Next: Editor (internal and external), Previous: Editor function list, Up: General Features
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.
Next: Editor help, Previous: Editor syntax coloring, Up: General Features
By default, the editor used is incorporated into R.APP, the macOS 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.
Next: Drag & drop, Previous: Editor (internal and external), Up: General Features
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.
Next: Help system, Previous: Editor help, Up: General Features
Drag and drop of a directory on the R.APP icon while R.APP is not running will start R.APP and set the working directory. By default .RData and the history file (default name .Rapp.history) are fetched from this working directory. If a file is dropped on the R.APP icon while R.APP is not running, R.APP is started, the file is either restored (if it is a saved workspace), sourced into R.APP 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.APP is finished loading will crash R.APP.
While R.APP is running, drag & drop of a directory updates the working directory. Drag & drop of a file sources or opens the file in the selected editor. Double clicking on files bound to ("Open With ...") R, if R.APP is not running, R.APP is started and the file is sourced or opened in editor. If R.APP is running, the file is opened in the editor.
Next: History, Previous: Drag & drop, Up: General Features
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.
Next: Authentication and .libPaths, Previous: Help system, Up: General Features
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: Command-line R stores history in a file usually called .Rhistory. It is suggested to use a different name for the R.APP history file, and the default is .Rapp.history.
Note that the functions loadhistory(), savehistory() and
hence history() are not currently supported in R.APP.
Previous: History, Up: General Features
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 installation 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. (This is the same mechanism for personal library
directories described in the main R documentation, but with a location
specific to CRAN-like builds of R on macOS.)
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 directories, for non-admin users the personal library directory will be used.
Next: Preferences, Previous: General Features, Up: R.app
The Application menu is the first one after the main Apple Menu: it is
labelled R.
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 macOS is available (you need an Internet connection), 3. you can access the Preferences (see Preferences).
Next: Misc Menu, Previous: Application Menu, Up: The Menus
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 Edit Object which is an interface to the R edit
function.
Next: Workspace Menu, Previous: Misc Menu, Up: The Menus
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.
Next: Packages Menu, Previous: Misc Menu, Up: The Menus
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 Browse workspace which invokes the
browseEnv() function in R. This will open a window with a
summary description of the objects in your workspace. Recursive objects
(like lists, data.frame etc) can be expanded (one level only though).
Next: The Help Menu, Previous: Workspace Menu, Up: The Menus
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 macOS 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 macOS. If you don’t know how to build R itself from source, 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 macOS 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.
Note that packages which do not contain C, C++, Fortran … code which needs to be compiled can be compiled from their sources with no additional tools.
For more information on this topic see also How to install packages.
Previous: Packages Menu, Up: The Menus
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 macOS (What’s new in this version). There are also interfaces to the R help and help.search functions as well as the example function.
Next: R.app Bugs, Previous: The Menus, Up: R.app
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.
Previous: Preferences, Up: Preferences
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.
Next: Syntax Colors, Previous: Startup, Up: Startup
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).
Next: Console Colors, Previous: Editor Preferences, Up: Startup
Enables to select the syntax colors.
Next: Quartz window, Previous: Syntax Colors, Up: Startup
Enables to select the input/output colors in R Console.
Previous: Console Colors, Up: Startup
Currently the the Quartz preference pane is not being used.
Previous: Preferences, Up: R.app
On Unix systems a bug report can be generated using the function
bug.report(). Alternatively the bug report can be submitted to
the Web page at http://bugs.R-project.org/.
Before you file 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 the mailing list
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).
Next: R and external applications, Previous: R.app, Up: R for macOS FAQ
You have several options for installing new packages on your system. We
discuss here only the GUI interface to the standard R functions like
install.packages(). For the R functions see the standard R
documentation.
Next: Installation of packages, Previous: How to install packages, Up: How to install packages
GUI provides direct access/download/installation of packages located on
CRAN, the Bioconductor repositories 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.
Next: Installation of source packages, Previous: Which kind of packages can I install using the GUI, Up: How to install packages
R for macOS 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 OS. CRAN and Bioconductor
repositories offer R packages in binary form for the last released
R version. Unlike on other Unix systems, CRAN R for macOS
installs binary packages by default, i.e. install.packages will
look first 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 may be necessary for that, see see Installation of source packages for details. For most users binary packages are sufficient (if available and current).
On macOS packages can be installed in three ways:
install.packages command in R
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.
Next: Where are the packages I’ve installed?, Previous: Installation of packages, Up: How to install packages
Source packages which do not contain compiled code can (with rare exceptions) be installed with no additional tools.
Packages with compiled code (or some with Unix scripts) need the tools used to build R itself discussed in the ‘R Installation and Administation Manual’, and these will need to be in the ‘PATH’ as seen from R.APP or command-line R. For R.APP you may need to add e.g. /usr/local/bin and it is usually most convenient to use command-line R.
If using a CRAN binary install of R the compilers may not be in the same place or have the same names as on the CRAN build machine. Look at file /Library/Frameworks/R.framework/Resources/etc/Makeconf, which will contain lines like
CC = clang -mmacosx-version-min=10.13 CXX = clang++ -mmacosx-version-min=10.13 -std=gnu++14 FC = gfortran -mmacosx-version-min=10.13 OBJC = clang -mmacosx-version-min=10.13 OBJCXX = clang++ -mmacosx-version-min=10.13
(for Intel, similar for ARM). You can either edit that file, or override settings in file ~/.R/Makevars: see the section ‘Customizing package compilation’ of the ‘R Installation and Administration Manual’.
Previous: Installation of source packages, Up: How to install packages
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 personal packages in
their ~/Library/R/x86_64/x.y/library directory where x.y denotes
the R version without the patch level (such as 3.0) – see the startup
preferences in R.APP. (For ARM, replace x86_64 by arm64.)
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 personal library tree.
If you 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()
Next: Quartz device, Previous: How to install packages, Up: R for macOS FAQ
Next: External editors, Previous: R and external applications, Up: R and external applications
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 first
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
Next: Finder actions, Previous: AppleScript support, Up: R and external applications
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/).
Previous: External editors, Up: R and external applications
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 is up to the user to do the right
thing.
If R is not yet running this action causes R to startup.
Next: Tcl/Tk issues, Previous: R and external applications, Up: R for macOS FAQ
The quartz() device is the native graphic device in R for Mac OS
X. Its name derives from Apple’s Quartz Technology which is essentially
similar to PDF rendering.
The quartz() device can be used from R.APP or a suitable build of R
running at the Mac console. Where supported it is the default graphics
device.
Next: Saving the image, Previous: Quartz device, Up: Quartz device
The quartz device allows for interaction. You can use both
identify and locator functions. To break the
sequence you should right/control-click or hit the ESC key.
Next: Copying the image into the clipboard, Previous: Interactive mode, Up: Quartz device
You can save the content of the quartz device window into a PDF file,
via the R menu when the device window has focus. This is a simple
way to export high quality graphics from R into other applications on
macOS as graphics is PDF-based (so are almost all applications
available). For other solutions, see (see Copying the image into the clipboard) and the quartz.save function.
Previous: Saving the image, Up: Quartz device
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 version 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.
Next: Internationalization of the R.app, Previous: Quartz device, Up: R for macOS FAQ
Each binary distribution of R available through CRAN is built to use the X11 implementation of Tcl/Tk. Of course a X windows server has to be started first: this should happen automatically on macOS, provided it has been installed (it needs a separate install from http://xquartz.macosforge.org). The first time things are done in the X server there can be a long delay whilst a font cache is constructed; starting the server can take several seconds.
If you don’t like the X11 style of widgets and use command-line R you would probably want to build R using the Aqua version of Tcl/Tk (see the ‘R Installation and Administration Manual’). Note, however, that such builds do not work when used in the R.APP GUI.
Next: Additional resources, Previous: Tcl/Tk issues, Up: R for macOS FAQ
R and the R.APP GUI support for internationalization. Among other things this means that messages and GUI elements can be translated into various languages. R.APP automatically detects the user’s settings in the Language & Region section of the System Preferences and uses that information to offer translated messages and GUI if available.
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. If you don’t know what Terminal is you can use this R command instead:
system("defaults write org.R-project.R force.LANG en_US.UTF-8")
but do not forget to quit R and start R.APP again afterwards. Please note that you must always use ‘.UTF-8’ version of the locale, otherwise R.APP will not work properly.
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 at http://developer.r-project.org/Translations30.html.
Next: Acknowledgments, Previous: Internationalization of the R.app, Up: R for macOS FAQ
Here are few references that can be of interest for macOS and/or developers.
Next: The R for macOS Developer page, Previous: Additional resources, Up: Additional resources
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): however more recently these have been distributed through the App Store.
Previous: Apple Developer Connection, Up: Additional resources
There is a page dedicated to development versions for R for macOS. This page is located at http://mac.R-project.org/ 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.
Next: Miscellaneous questions, Previous: Additional resources, Up: R for macOS FAQ
Special thanks go to Jan de Leeuw, Byron Ellis and Thomas Lumley in random order. Last but not least Apple for amazing OS and GUI.
Previous: Acknowledgments, Up: R for macOS FAQ
Next: What happens if I drag a file on the R icon?, Previous: Miscellaneous questions, Up: Miscellaneous questions
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).
Next: How can I interrupt lengthy operations or output?, Previous: How can I have a per session .Rprofile?, Up: Miscellaneous questions
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.
Next: I see spurious error messages when starting R!, Previous: What happens if I drag a file on the R icon?, Up: Miscellaneous questions
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
(There may be some delay in stopping as R queues reacting to interrupts until safe points in the code.)
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).
Next: Which BLAS is used and how can it be changed?, Previous: How can I interrupt lengthy operations or output?, Up: Miscellaneous questions
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
upgrades (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.
Next: I don’t see a thing when installing packages!, Previous: I see spurious error messages when starting R!, Up: Miscellaneous questions
The BLAS library used by R depends on the way R was compiled (see ‘R Installation and Administration’ 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 the R BLAS: this 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.
The BLAS library used is displayed in sessionInfo().
Next: Why are there faint lines in image plots?, Previous: Which BLAS is used and how can it be changed?, Up: Miscellaneous questions
The output is not produced continuously during the package installation. 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.
Next: Why doesn’t R GUI support keyboard shortcut XYZ ?, Previous: I don’t see a thing when installing packages!, Up: Miscellaneous questions
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 rectangles 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 rectangles to pixel boundaries of the screen, but Preview does not.
The same effect occurs in any plot with adjacent, filled polygons without border.
Next: What is the difference between the CRAN build and a vanilla build?, Previous: Why are there faint lines in image plots?, Up: Miscellaneous questions
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 satisfied with the default Emacs-like key bindings that
macOS provides, Apple allows you to extend them arbitrarily. For more
details see Apple’s documentation on
Key Bindings. There are also many 3rd-party pages on key bindings
customization, search for StandardKeyBinding.dict.
Next: Why is R.home() in the R framework not versioned?, Previous: Why doesn’t R GUI support keyboard shortcut XYZ ?, Up: Miscellaneous questions
The CRAN build of R is slightly 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 binary packages. Only the CRAN build is
guaranteed to be compatible with the package binaries on CRAN (or
Bioconductor). The exact flags used by CRAN are avaiable in the
R SVN repository of the CRAN build system as conf.xxx
files. For R 4.0.0 and higher this is
https://svn.r-project.org/R-dev-web/trunk/QA/Simon/R4
Also the CRAN build includes libraries that are required
to run R inside the framework. Static libraries used by CRAN R
and packages are available in
https://mac.R-project.org/bin
Next: R.app GUI crashes on startup!, Previous: What is the difference between the CRAN build and a vanilla build?, Up: Miscellaneous questions
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/4.2/Resources. This is how framework versioning works
in macOS and is defined by Apple (see
Framework Anatomy).
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. Finally, if such an R start script
happens to get copied and the R version changes, it will stop working.
Next: Why is the GUI not saving my history?, Previous: Why is R.home() in the R framework not versioned?, Up: Miscellaneous questions
If your R.APP GUI crashes on startup, there are two common causes for this: a saved workspace or a corrupted history file. (Another is a mismatch between R.APP and R if either has been updated).
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: for the default file this could be done by
mv ~/.Rapp.history ~/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 macOS. 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 see R.app Bugs above).
Next: I get “command not found” in the GUI yet it works in the Terminal – why?, Previous: R.app GUI crashes on startup!, Up: Miscellaneous questions
R.APP will by default save the history in a .Rapp.history file
whereas command line R will use .Rhistory. So the saved
history is only used in subsequent R.APP sessions and not command-line
R, and conversely.
Note that calling savehistory() in R.APP does not currently
save the history of the R.APP session: this means that
history() will show an empty window.
Next: I see no text in a Quartz plot!, Previous: Why is the GUI not saving my history?, Up: Miscellaneous questions
When executing system commands (for example directly via system or indirectly via functions that call other programs such as install.packages) the locations in which the shell is looking for programs is governed by the PATH environment variable. That variable may be set differently for R started from an interactive shell and for R started in the GUI. You can use Sys.getenv("PATH") to verify the current setting.
When R is started from a shell (e.g., on the command line of the Terminal), it will inherit settings from that shell. Those are typically modified by shell-specific configuration files, such as .profile or .bashrc. Those apply only to the shell, not to the system as a whole. In addition, some installers (such as MacTeX) will modify global shell settings to make user’s life more comfortable on the command line, but, again, those do not apply to programs not started from the shell – such as GUIs. See Apple Technical Q&A QA1067 for what Apple says about the topic.
In order to standardize your PATH setting in R, you can set it in
your .Renviron file (in your home directory – see ?Startup
in R for details on how R uses configuration files on startup). This
setting will apply to R regardless of how it is started. You can also
add more elaborate constructs to .Rprofile instead if you wish to
selectively modify the existing PATH variable via
Sys.getenv and Sys.setenv.
Next: I cannot attach debugger to R, Previous: I get “command not found” in the GUI yet it works in the Terminal – why?, Up: Miscellaneous questions
Typically this means that you have corrupted fonts in your system. Open
the Font Book application (in Applications) and check the
fonts that you are using (for example the default font in Quartz is
currently “Arial”). Corrupted fonts will have no glyphs (text will not
appear as it should), remove such fonts.
Previous: I see no text in a Quartz plot!, Up: Miscellaneous questions
R processes installed using Apple installer cannot be attached to by debuggers. This is a limitation introduced by Apple as a security measure. Since January 2020 Apple requires all notarized applications to use “Hardened Runtime” https://developer.apple.com/documentation/security/hardened_runtime and one of the implications is that such processes cannot be tampered with by debuggers. Therefore official R installers have to use hardened runtime as Apple will no longer allow installation of software that is not notarized.
In order to debug R code or packages, you can use R binaries that don’t
use hardened runtime and are not notarized. Such binaries are available
in tar-balls at https://mac.R-project.org/ and can be installed
by unpacking into /, e.g.:
curl -LO http://mac.r-project.org/high-sierra/R-4.2-branch/x86_64/R-4.2-branch.tar.gz tar fxz R-4.2-branch.tar.gz -C /
If you are not the administrator, you may have to use sudo tar ....
NOTE: R releases since 4.2.0 include an entitlement in the hardened runtime which allows debugging, so the above issue should not occur in R releases since R 4.2.0.