# 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 → Software Updates → Find and Install...`. On the next page, select the option to Search for new features to install, and press the `Next` button. On the next panel, update sites to visit, press the "Add a new remote site" button and enter the URL http://www.apache.org/dist/uima/eclipse-update-site, and press OK. On the previous page will now appear this new Site, and it should be checked.

Also check the Europa (or Callisto) Discovery Site, which is where the EMF core plugins are (EMF stands for Eclipse Modeling Framework; it is an add-on to Eclipse, and is used by some of the UIMA Eclipse tooling).

Now click finish, and follow the remaining panels to install the UIMA plugins. If you do not have a compatible level of EMF installed, when you select the UIMA plugins, you will get a message saying it needs EMF. To add EMF to the list of plugins to be downloaded, just expand the Discovery Site entry by clicking it's little "plus" sign and then push the "Select Required" button on the right of the panel. This will select the part of EMF that is needed.

### Manual Install additional Eclipse component: EMF

You can skip this section if you installed EMF using the above process.

EMF comes in many versions; you must install the version that corresponds to the level of Eclipse that you are running. This is automatically done for you if you install it using the Eclipse update mechanism, described below. If you separately download an EMF package, you will need to verify it is the version that corresponds to the level of Eclipse you are running, before installing it.

Before installing EMF using these instructions, please go to and read the installation instructions, and then click on the "Update Manager" link to see what url to use in the next step, where you use the built-in facilities in Eclipse to find and install new features.

The exact way to install EMF changes from time to time. In the next few paragraphs, we try to give instructions that should work for most versions. Please see the end of this section for shortcut instructions for the current version of Eclipse at the time of this writing, Eclipse 3.3.

Activate the software feature finding by using the menu: Help → Software Updates → Find and Install. Select Search for new features to install, push Next. Specify the update sites to use to search for EMF, making sure the Ignore features not applicable to this environment box is checked (at the bottom of the dialog), and push Finish. A good site to use is one of the Discovery Sites (e.g. Callisto or Europa) - which has a collection of Eclipse components including EMF.

This will launch a search for updates to Eclipse; it may show a list of update site mirrors – click OK. When it finishes, it shows a list of possible updates in an expandable tree. Expand the tree nodes to find EMF SDK. The specific level may vary from the level shown below as newer versions are released.

Screenshot showing search results for EMF

Click Next. Then pick Eclipse Modeling Framework (EMF), and push Next, accept any licensing agreements, etc., until it finishes the installation. It may say it's an unsigned feature; proceed by clicking Install. If it recommends restarting, you may do that.

This will install EMF, without any extras. (If you want the whole EMF system, including source and documentation, you can pick the EMF SDK and the Examples for Eclipse Modeling Framework.)

#### EMF Installation Shortcut for Eclipse 3.2

Since Eclipse 3.2, all major Eclipse sub-projects coordinate their release timeframes and publish the consolidated releases. The code name for 3.2 was Callisto, the one for 3.3 is Europa. You can easily install EMF via the release discovery site as follows.

1. From the Eclipse menu, select Help/Software Updates/Find and Install.../Search for new features to install.

2. Check the "[release name] discovery site", push "Next".

3. Select a convenient mirror site.

4. Check the EMF box under "Models and model development"

5. Follow the instructions for the rest of the install.

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