Background: Eclipse is an
open source Integrated Development Environment (IDE). As with Microsoft's Visual
Studio product, Eclipse is programming language-agnostic and supports any
language having a suitable plugin for the IDE platform. For Eclipse, the R
language plugin is StatET.
Figure 1 (above): Eclipse, StatET with R, and the R debugger (bottom window) at work.
The R debugger is an R package library and has its own graphical output window separate from Eclipse.
The following three (3) part procedure installs Eclipse onto a Windows platform
(XP or Windows 7) and adds StatET (R) language support. The three parts of the procedure are
(1)Install Eclipse, (2)Install StatET, (3)Configure Eclipse / R. We then follow
this procedure with tests to confirm the installation and configuration.
Part-I
Install
Eclipse-
-
Download the latest stable Eclipse release (I use Eclipse Classic which is
at version 3.5.2 (163 MB) as of 10-April-2010). For 64-bit Windows be sure to
download and install the 64-bit version of Eclipse AND install the 64-bit JRE
(Java Runtime Environment).
Once downloaded and extracted, copy the resultant Eclipse folder (for example,
eclipse-SDK-3.5.2-win32) to your desired installation location, such as
C:\Program Files\eclipse-SDK-3.5.2-win32.
Add a desktop shortcut to the Eclipse executable (Eclipse.exe) if you like.
NOTES: your system may already have Java installed, in which case you can skip
these Java installation steps. 64-bit Java runtime environments (JREs) are designated
explicitly on the java.com website as 64-bit, for example 'Windows
7/XP/Vista/2003/2008 (64-bit)' or similar.
If you do not see the 64-bit JRE offering for Windows then you are likely running 32-bit
Windows and should use the 32-bit JRE and Eclipse.
If you are running a 64-bit Windows and you still do not see the 64-bit
offerings on java.com then switch to another browser (64-bit).
If you are unsure if your Windows operating system (OS) is 32 or 64-bit, right
click 'My Computer' (Windows XP) and select 'Properties'. If the
operating system description does not include '64-bit' then your Windows OS is
32-bit. For Windows 7, click 'Start' and then right click 'Computer' and
select 'Properties'. If there is no mention of '64-bit' then your OS is 32-bit.
Part-II
Install
StatET-
With Eclipse installed and running (just FYI I have installed it under 32-bit XPP and 64-bit
Windows7, so it does work under these platforms) install
StatET, the R IDE plugin-
-
Copy the URL mentioned on the StatET installation page for the version of
Eclipse you are using. In this case (Eclipse V3.5.x) we use
http://download.walware.de/eclipse-3.5.
-
Paste the URL from step 1 into Eclipse-
A. From the Eclipse menu bar click Help -> Install New Software.
B. Click the 'Add' button. The "Add Site" dialog appears.
C. Type in a friendly name for your remote resource, such as StatET.
D. Paste the URL into the 'Location' box.
E. Click 'OK'.
F. Select (check) the package components that you want to install.
G. Click 'Next'.
H. A review screen showing your selection(s) displays. Click 'Next'.
I. Accept the license agreement (if you agree to the terms described there).
J. Click 'Finish'.
Now Eclipse will install StatET, but it will take a few minutes. During the installation
you may be asked to accept a digital certificate from Eclipse.org. This happens if you do
not already have a digital certificate from Eclipse.org installed on your computer.
If you want, examine the details of the digital certificate (click on the 'Details'
button to do so). What you want to be sure of is that the certificate was issued to Eclipse.org
Foundation, Inc and issued by a trusted third party such as VeriSign, Inc. Also check that
the validity dates are valid (active and not expired). If the digital certificate passes
these checks, it is pretty safe to accept the certificate.
When the installation completes, configure your R - Eclipse environment as shown next in Part-III.-
Part-III
Configure the StatET Eclipse plugin-
The StatET plugin enables Eclipse to connect to R. You may have been using R
console or a simple editor like notepad or wordpad to write and submit R
programs to R before. With Eclipse and the StatET plugin for R, you will use the
rich editing environment provided by Eclipse and the StatET plugin to write and
submit those programs to R from within the Eclipse IDE (Integrated Development
Environment). The result will be a better, less error-prone development
environment for your R software development. To make this happen we must first
tell the StatET R plugin for Eclipse about your existing R installation-
-
Install R, if you need to. NOTE: as far as Eclipse is concerned, it makes no
difference if you run 32 or 64-bit R. Just be sure that you identify 32 or
64-bit R to Eclipse, which we do in the next steps (among other things).
-
From the Eclipse menu bar click Help -> Cheat Sheets: StatET: R in Eclipse
to put up the official help. This is a handy, built-in guideline, but some of
the steps inaccurately describe the menu choices (and one reason why I wrote these
instructions). It is a good reference, though, for your later work, so keep it in mind.
Click the 'Cancel' button to close the Cheat Sheet Selection dialog.
-
From the Eclipse menu bar click Window -> Preferences: StatET : Run/Debug: R
Interaction:
Select 'New Console Inside Eclipse' for the 'Connector used to run R code'. Note
that this is the default so it might already be this way. This is how I run mine.
Be sure to click 'Apply' if you change the setting.
-
Back in the left pane click 'R Environments' (StatET : Run/Debug: R Environments,
which is directly above the 'R Interaction' of the previous step). The 'R
Environments' pane now appears on the right.
A. Click the pane's 'Add' button. The 'Add R Environment Configuration' dialog
appears.
B. Type in a friendly name in the 'Name' box, such as R.2.11.1 or whatever your
R version is, for example.
C. For the 'Location (R_HOME)' box, paste in the path to your R install
directory, for example C:\Program Files\R\R-2.11.1.
Make sure the 'Type' field
is set to your R type (32 or 64-bit).
D. Click 'OK' to save your changes and close the dialog, which returns us to the
'R Environments' pane, which now shows our newly created R environment.
E. Click 'Apply' and 'OK' to save and close the 'R Environments' pane.
-
From the Eclipse menu bar click Run -> Run Configurations. The 'Run
Configurations' dialog box appears.
A. In the left pane click 'R Console' and define a new console entry with a
friendly name in the 'Name' box, such as 'MyConsole'.
B. Under the 'Main' tab ensure that 'Launch Type' is set properly for your
configuration. If you are uncertain, choose 'Rterm' (this selection is
VERY IMPORTANT).
C. For 'Working Directory' just provide a path to your projects directory, for
example C:\d2\SOFTWARE_DEVELOPMENT\Research\R\Projects
D. No further changes are required, but you can check to make sure that the 'R
Environment' under the next tab ('R Config') is set to that environment you
named in Step.4 above.
E. Click 'Apply' and then 'Close' to close the dialog.
Testing
Testing the Eclipse/StatET/R IDE Configuration-
-
From the Eclipse menu bar click File -> New -> R-Project.
A 'New R-Project' dialog box appears, so give the new project a
name like 'test'.
NOTE: If you are not seeing file and project creation options that you
expect to see, make sure your Eclipse is set to the proper perspective.
For our work here we want StatET perspective. Switch Eclipse's perspective to StatET
by clicking 'Window' in the Eclipse menu bar and selecting "Open Perspective"
from the resultant drop-down list.
From there select 'Other' and choose 'StatET'.
Next, from the Eclipse menu bar, click File -> New -> R-Script File.
Name your new script and click 'Finish'.
A new script window appears in the Eclipse IDE.
-
Paste in or type some R test code, for example-
# TODO: Add comment
#
# Author: mark qu
################################################################
# some test code...
a = 2
b = 3
c = a+b
c
-
To run the script, click inside the R script window to give it focus. Then, from the
Eclipse menu bar, click Run -> Run : R Script in R Submitting Directly -OR- R
Script in R via Source. You can then execute by simply clicking Run -> Run.
You can also select the Run icon (green ball with the white triangle inside) from
the Eclipse toolbar
-
The code executes as expected.
> # TODO: Add comment
> #
> # Author: mark qu
> ################################################################
>
>
> # some test code...
> a = 2
> b = 3
>
> c = a+b
> c
[1] 5
>
Troubleshooting
Troubleshooting the Eclipse/StatET/R IDE Configuration-
If the simple test script (above, in R language) fails to run:
A. Be sure that the program (script) window has focus before clicking Run.
B. Check your Launch Type (see Part III, step 5).
C. Make sure you can start R by itself outside of Eclipse.
D. From the Eclipse menu bar, click Run -> Run Configurations : R Console : MyConsole
(or however you named it) and click the 'Run' button, then try again to run the
test script.
Figure 2 (above): Test script ready for execution. The next picture (Figure 3)
shows how to start an R console to send this script to for execution.
Figure 3 (above): Activating the 'MyConsole' R console that we defined earlier.
Click on the down arrow next to the execution icon (green ball with the white triangle) to
put up this menu selection box.
Figure 4 (above): 'MyConsole' R console active (note the bottom Console pane
information, verifing this).
Figure 5 (above): Selecting the execution method to be used to run the test script.
Figure 6 (above): Test script execution and results.
Figure 7 (above, optional): Loading the R debugger. Note the console command line at the bottom
of the Console pane. Just like in the traditional R GUI, use the library command to load the R
debugger. You must have the R debugger installed for this to work, of course.
Figure 8 (above): The loaded R debugger, ready for your buggy program :).
Figure 9 (above): Debugging with the R debugger under Eclipse StatET. Note the
mtrace debug statement, which kicks off the debug session upon the function, and the subsequent
function call that is then intercepted by the debugger at the automatic breakpoint at line 1
(breakpoint indicated by the red star). Here we single stepped through the function and are at
line 3, indicated by the green bar. Note from the Console window that we at this point examined
the contents of variable b.
-Mark Qu