# Setting up the Eclipse IDE to work with UIMA

Eclipse IDE setup for UIMA

This chapter describes how to set up the UIMA SDK to work with Eclipse. Eclipse () is a popular open-source Integrated Development Environment for many things, including Java. The UIMA SDK does not require that you use Eclipse. However, we recommend that you do use Eclipse because some useful UIMA SDK tools run as plug-ins to the Eclipse platform and because the UIMA SDK examples are provided in a form that's easy to import into your Eclipse environment.

If you are not planning on using the UIMA SDK with Eclipse, you may skip this chapter and read next.

This chapter provides instructions for

- installing Eclipse,

- installing the UIMA SDK's Eclipse plugins into your Eclipse environment, and

- importing the example UIMA code into an Eclipse project.

The UIMA Eclipse plugins are designed to be used with Eclipse version 3.1 or later.

You will need to run Eclipse using a Java at the 1.5 or later level, in order to use the UIMA Eclipse plugins.

## Installation

### Install Eclipse

- Go to and follow the instructions there to download Eclipse.

- We recommend using the latest release level (not an Integration level). Navigate to the Eclipse Release version you want and download the archive for your platform.

- Unzip the archive to install Eclipse somewhere, e.g., c:\

- Eclipse has a bit of a learning curve. If you plan to make significant use of Eclipse, check out the tutorial under the help menu. It is well worth the effort. There are also books you can get that describe Eclipse and its use.

The first time Eclipse starts up it will take a bit longer as it completes its installation. A welcome page will come up. After you are through reading the welcome information, click on the arrow to exit the welcome page and get to the main Eclipse screens.

### Installing the UIMA Eclipse Plugins

The best way to do this is to use the Eclipse Update mechanism, because that will insure that all needed prerequisites are also installed. See below for an alternative, manual approach.

If your computer is on an internet connection which uses a proxy server, you can configure Eclipse to know about that. Put your proxy settings into Eclipse using the Eclipse preferences by accessing the menus: Window → Preferences... → Install/Update, and Enable HTTP proxy connection under the Proxy Settings with the information about your proxy.

To use the Eclipse Update mechanism, start Eclipse, and then pick the menu `Help → Install new software...`. In the next page, enter the following URL in the "Work with" box and press enter: http://www.apache.org/dist/uima/eclipse-update-site/.

Now select the plugin tools you wish to install, and click Next, and follow the remaining panels to install the UIMA plugins.

### Install the UIMA SDK

If you haven't already done so, please download and install the UIMA SDK from . Be sure to set the environmental variable UIMA_HOME pointing to the root of the installed UIMA SDK and run the `adjustExamplePaths.bat` or `adjustExamplePaths.sh` script, as explained in the README.

The environmental parameter UIMA_HOME is used by the command-line scripts in the %UIMA_HOME%/bin directory as well as by eclipse run configurations in the uimaj-examples sample project.

### Installing the UIMA Eclipse Plugins, manually

If you installed the UIMA plugins using the update mechanism above, please skip this section.

If you are unable to use the Eclipse Update mechanism to install the UIMA plugins, you can do this manually. In the directory %UIMA_HOME%/eclipsePlugins (The environment variable %UIMA_HOME% is where you installed the UIMA SDK), you will see a set of folders. Copy these to your %ECLIPSE_HOME%/eclipse/plugins directory (%ECLIPSE_HOME% is where you installed Eclipse).

### Start Eclipse

If you have Eclipse running, restart it (shut it down, and start it again) using the `-clean` option; you can do this by running the command `eclipse -clean` (see explanation in the next section) in the directory where you installed Eclipse. You may want to set up a desktop shortcut at this point for Eclipse.

#### Special startup parameter for Eclipse: -clean

If you have modified the plugin structure (by copying or files directly in the file system) in Eclipse 3.x after you started it for the first time, please include the -clean parameter in the startup arguments to Eclipse, one time (after any plugin modifications were done). This is needed because Eclipse may not notice the changes you made, otherwise. This parameter forces Eclipse to reexamine all of its plugins at startup and recompute any cached information about them.

## Setting up Eclipse to view Example Code

Later chapters refer to example code. You can create a special project in Eclipse to hold the examples. Here's how:

- In Eclipse, if the Java perspective is not already open, switch to it by going to Window → Open Perspective → Java.

- Set up a class path variable named UIMA_HOME, whose value is the directory where you installed the UIMA SDK. This is done as follows:

  - Go to Window → Preferences → Java → Build Path → Classpath Variables.

  - Click New

  - Enter UIMA_HOME (all capitals, exactly as written) in the Name field.

  - Enter your installation directory (e.g. `C:/Program Files/apache-uima`) in the Path field

  - Click OK in the New Variable Entry dialog

  - Click OK in the Preferences dialog

  - If it asks you if you want to do a full build, click Yes

- Select the File → Import menu option

- Select General/Existing Project into Workspace and click the Next button.

- Click Browse and browse to the %UIMA_HOME%/ directory

- Click Finish. This will create a new project called uimaj-examples in your Eclipse workspace. There should be no compilation errors.

To verify that you have set up the project correctly, check that there are no error messages in the Problems view.

## Adding the UIMA source code to the jar files

If you are running a current version of Eclipse, and have the m2e (Maven extensions for Eclipse) plugin installed, Eclipse should be able to automatically download the source for the jars, so you may not need to do anything special (it does take a few seconds, and you need an internet connection).

If you would like to be able to jump to the UIMA source code in Eclipse or to step through it with the debugger, you can add the UIMA source code to the jar files. This is done via a shell script that comes with the source distribution. To add the source code to the jars, you need to:

- Download and unpack the UIMA source distribution.

- Download and install the UIMA binary distribution (the UIMA_HOME environment variable needs to be set to point to where you installed the UIMA binary distribution).

- "cd" to the root directory of the source distribution

- Execute the `src\main\readme_src\addSourceToJars` script in the root directory of the source distribution.

This adds the source code to the jar files, and it will then be automatically available from Eclipse. There is no further Eclipse setup required.

## Attaching UIMA Javadocs

The binary distribution also includes the UIMA Javadocs. They are attached to the UIMA library Jar files in the uima-examples project described above. You can attach the Javadocs to your own project as well.

If you attached the source as described in the previous section, you don't need to attach the Javadocs because the source includes the Javadoc comments.

Attaching the Javadocs enables Javadoc help for UIMA APIs. After they are attached, if you hover your mouse over a certain UIMA api element, the corresponding Javadoc will appear. You can then press F2 to make the hover "stick", or Shift-F2 to open the default web-browser on your system to let you browse the entire Javadoc information for that element.

If this pop-up behavior is something you don't want, you can turn it off in the Eclipse preferences, in the menu Window → Preferences → Java → Editors → hovers.

Eclipse also has a Javadoc "view" which you can show, using the Window → Show View → Javadoc.

See for information on how to set up a UIMA "library" with the Javadocs attached, which can be reused for other projects in your Eclipse workspace.

You can attach the Javadocs to each UIMA library jar you think you might be interested in. It makes most sense for the uima-core.jar, you'll probably use the core APIs most of all.

Here's a screenshot of what you should see when you hover your mouse pointer over the class name CAS in the source code.

Screenshot of mouse-over for UIMA APIs

## Running external tools from Eclipse

You can run many tools without using Eclipse at all, by using the shell scripts in the UIMA SDK's bin directory. In addition, many tools can be run from inside Eclipse; examples are the Document Analyzer, CPE Configurator, CAS Visual Debugger, and JCasGen. The uimaj-examples project provides Eclipse launch configurations that make this easy to do.

To run these tools from Eclipse:

- If the Java perspective is not already open, switch to it by going to Window → Open Perspective → Java.

- Go to Run → Run...

- In the window that appears, select UIMA CPE GUI, UIMA CAS Visual Debugger, UIMA JCasGen, or UIMA Document Analyzer from the list of run configurations on the left. (If you don't see, these, please select the uimaj-examples project and do a Menu → File → Refresh).

- Press the Run button. The tools should start. Close the tools by clicking the X in the upper right corner on the GUI.

For instructions on using the Document Analyzer and CPE Configurator, in the book see , and For instructions on using the CAS Visual Debugger and JCasGen, see and