| <?xml version="1.0" encoding="UTF-8"?> | |
| <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" | |
| "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [ | |
| <!ENTITY imgroot "images/overview-and-setup/eclipse_setup_files/" > | |
| <!ENTITY % uimaents SYSTEM "../../target/docbook-shared/entities.ent" > | |
| %uimaents; | |
| ]> | |
| <!-- | |
| Licensed to the Apache Software Foundation (ASF) under one | |
| or more contributor license agreements. See the NOTICE file | |
| distributed with this work for additional information | |
| regarding copyright ownership. The ASF licenses this file | |
| to you under the Apache License, Version 2.0 (the | |
| "License"); you may not use this file except in compliance | |
| with the License. You may obtain a copy of the License at | |
| http://www.apache.org/licenses/LICENSE-2.0 | |
| Unless required by applicable law or agreed to in writing, | |
| software distributed under the License is distributed on an | |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
| KIND, either express or implied. See the License for the | |
| specific language governing permissions and limitations | |
| under the License. | |
| --> | |
| <chapter id="ugr.ovv.eclipse_setup"> | |
| <title>Setting up the Eclipse IDE to work with UIMA</title> | |
| <titleabbrev>Eclipse IDE setup for UIMA</titleabbrev> | |
| <para>This chapter describes how to set up the UIMA SDK to work with Eclipse. Eclipse (<ulink | |
| url="&url_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.</para> | |
| <para>If you are not planning on using the UIMA SDK with Eclipse, you may skip this chapter and | |
| read <olink targetdoc="&uima_docs_tutorial_guides;"/> | |
| <olink targetdoc="&uima_docs_tutorial_guides;" targetptr="ugr.tug.aae"/> | |
| next.</para> | |
| <para>This chapter provides instructions for | |
| <itemizedlist spacing="compact"><listitem><para>installing Eclipse, </para> | |
| </listitem> | |
| <listitem><para>installing the UIMA SDK's Eclipse plugins into your Eclipse | |
| environment, and </para></listitem> | |
| <listitem><para>importing the example UIMA code into an Eclipse project. </para> | |
| </listitem></itemizedlist></para> | |
| <para>The UIMA Eclipse plugins are designed to be used with Eclipse version 3.1 or | |
| later. | |
| </para> | |
| <note><para>You will need to run Eclipse using a Java at the 1.8 level, in order | |
| to use the UIMA Eclipse plugins.</para></note> | |
| <section id="ugr.ovv.eclipse_setup.installation"> | |
| <title>Installation</title> | |
| <section id="ugr.ovv.eclipse_setup.install_eclipse"> | |
| <title>Install Eclipse</title> | |
| <itemizedlist spacing="compact"><listitem><para>Go to <ulink | |
| url="&url_eclipse;"/> and follow the instructions there to download Eclipse. | |
| </para></listitem> | |
| <listitem><para>We recommend using the latest release level. | |
| Navigate to the Eclipse Release version you | |
| want and download the archive for your platform.</para></listitem> | |
| <listitem><para>Unzip the archive to install Eclipse somewhere, e.g., c:\</para> | |
| </listitem> | |
| <listitem><para>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.</para></listitem></itemizedlist> | |
| <para>The first time Eclipse starts up it will take a bit longer as it completes its | |
| installation. A <quote>welcome</quote> 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.</para> | |
| </section> | |
| <section id="ugr.ovv.eclipse_setup.install_uima_eclipse_plugins"> | |
| <title>Installing the UIMA Eclipse Plugins</title> | |
| <para>The best way to do this is to use the Eclipse Install New Software mechanism, because that will | |
| insure that all needed prerequisites are also installed. See below for an alternative, | |
| manual approach.</para> | |
| <note><para>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. </para></note> | |
| <para>To use the Eclipse Install New Software mechanism, start Eclipse, and then pick the menu | |
| <command>Help → Install new software...</command>. In the next page, enter | |
| the following URL in the "Work with" box and press enter: | |
| <itemizedlist> | |
| <listitem><para></para><code>https://www.apache.org/dist/uima/eclipse-update-site/</code> or</listitem> | |
| <listitem><para></para><code>https://www.apache.org/dist/uima/eclipse-update-site-uv3/</code>.</listitem> | |
| </itemizedlist> | |
| Choose the 2nd if you are working with core UIMA Java SDK at version 3 or later. | |
| .</para> | |
| <para>Now select the plugin tools you wish to install, and click Next, and follow the | |
| remaining panels to install the UIMA plugins. </para> | |
| </section> | |
| <!-- | |
| <section id="ugr.ovv.eclipse_setup.install_emf"> | |
| <title>Manual Install additional Eclipse component: EMF</title> | |
| <para>You can skip this section if you installed EMF using the above process.</para> | |
| <warning><para>EMF comes in many versions; <emphasis role="bold">you must install | |
| the version that corresponds to the level of Eclipse that you are running.</emphasis> | |
| 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.</para></warning> | |
| <para>Before installing EMF using these instructions, please go to <ulink | |
| url="&url_emf;"/> 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. </para> | |
| <para> 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. </para> | |
| <para>Activate the software feature finding by using the menu: Help → Software | |
| Updates → Find and Install. Select <quote>Search for new features to | |
| install</quote>, push <quote>Next</quote>. Specify the update sites to use to | |
| search for EMF, making sure the <quote>Ignore features not applicable to this | |
| environment</quote> box is checked (at the bottom of the dialog), and push | |
| <quote>Finish</quote>. 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. </para> | |
| <para>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.</para> | |
| <informalfigure> | |
| <mediaobject> | |
| <imageobject> | |
| <imagedata width="4in" format="JPG" fileref="&imgroot;image002.jpg"/> | |
| </imageobject> | |
| <textobject><phrase>Screenshot showing search results for EMF</phrase> | |
| </textobject> | |
| </mediaobject> | |
| </informalfigure> | |
| <para>Click <quote>Next</quote>. Then pick Eclipse Modeling Framework (EMF), and | |
| push <quote>Next</quote>, accept any licensing agreements, etc., until it | |
| finishes the installation. It may say it's an <quote>unsigned feature</quote>; | |
| proceed by clicking <quote>Install</quote>. If it recommends restarting, you may | |
| do that.</para> | |
| <para>This will install EMF, without any extras. (If you want the whole EMF system, | |
| including source and documentation, you can pick the <quote>EMF SDK</quote> and the | |
| <quote>Examples for Eclipse Modeling Framework</quote>.)</para> | |
| <section id="ugr.ovv.eclipse_setup.install_emf_shortcut"> | |
| <title>EMF Installation Shortcut for Eclipse 3.2</title> | |
| <para>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. | |
| <orderedlist> | |
| <listitem><para> From the Eclipse menu, select Help/Software Updates/Find | |
| and Install.../Search for new features to install. </para></listitem> | |
| <listitem><para> Check the "[release name] discovery site", push "Next". </para> | |
| </listitem> | |
| <listitem><para> Select a convenient mirror site. </para></listitem> | |
| <listitem><para> Check the EMF box under "Models and model development" | |
| </para></listitem> | |
| <listitem><para> Follow the instructions for the rest of the install. </para> | |
| </listitem> | |
| </orderedlist> </para> | |
| </section> | |
| </section> | |
| --> | |
| <section id="ugr.ovv.eclipse_setup.install_uima_sdk"> | |
| <title>Install the UIMA SDK</title> | |
| <para>If you haven't already done so, please download and install the UIMA SDK from | |
| <ulink url="&url_apache_uima_download;"/>. Be sure to set the environmental variable | |
| UIMA_HOME pointing to the root of the installed UIMA SDK and run the | |
| <literal>adjustExamplePaths.bat</literal> or <literal>adjustExamplePaths.sh</literal> | |
| script, as explained in the README.</para> | |
| <para>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.</para> | |
| </section> | |
| <section id="ugr.ovv.eclipse_setup.install_uima_eclipse_plugins_manually"> | |
| <title>Installing the UIMA Eclipse Plugins, manually</title> | |
| <para>If you installed the UIMA plugins using the update mechanism above, please skip this section.</para> | |
| <para>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%/dropins directory (%ECLIPSE_HOME% is where you | |
| installed Eclipse).</para> | |
| </section> | |
| <section id="ugr.ovv.eclipse_setup.start_eclipse"> | |
| <title>Start Eclipse</title> | |
| <para>If you have Eclipse running, restart it (shut it down, and start it again) using | |
| the | |
| <code>-clean</code> option; you can do this by running the command | |
| <command>eclipse -clean</command> (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.</para> | |
| <section id="ugr.ovv.eclipse_setup.special_startup_parameter_clean"> | |
| <title>Special startup parameter for Eclipse: -clean</title> | |
| <para>If you have modified the plugin structure (by copying or files directly in the | |
| file system) after you started it for the first time, please include | |
| the <quote>-clean</quote> parameter in the startup arguments to Eclipse, | |
| <emphasis>one time</emphasis> (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.</para> | |
| </section> | |
| </section> | |
| </section> | |
| <section id="ugr.ovv.eclipse_setup.example_code"> | |
| <title>Setting up Eclipse to view Example Code</title> | |
| <para>Later chapters refer to example code. Here's how to create a special project in Eclipse to | |
| hold the examples.</para> | |
| <itemizedlist spacing="compact"><listitem><para>In Eclipse, if the Java | |
| perspective is not already open, switch to it by going to Window → Open Perspective | |
| → Java.</para></listitem> | |
| <listitem><para>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: | |
| <itemizedlist><listitem><para>Go to Window → Preferences → Java | |
| → Build Path → Classpath Variables.</para></listitem> | |
| <listitem><para>Click <quote>New</quote></para></listitem> | |
| <listitem><para>Enter UIMA_HOME (all capitals, exactly as written) in the | |
| <quote>Name</quote> field.</para></listitem> | |
| <listitem><para>Enter your installation directory (e.g. <literal>C:/Program | |
| Files/apache-uima</literal>) in the <quote>Path</quote> field</para> | |
| </listitem> | |
| <listitem><para>Click <quote>OK</quote> in the <quote>New Variable | |
| Entry</quote> dialog</para></listitem> | |
| <listitem><para>Click <quote>OK</quote> in the <quote>Preferences</quote> | |
| dialog</para></listitem> | |
| <listitem><para>If it asks you if you want to do a full build, click | |
| <quote>Yes</quote> </para></listitem></itemizedlist></para> | |
| </listitem> | |
| <listitem><para>Select the File → Import menu option</para></listitem> | |
| <listitem><para>Select <quote>General/Existing Project into Workspace</quote> and click | |
| the <quote>Next</quote> button.</para></listitem> | |
| <listitem><para>Click <quote>Browse</quote> and browse to the | |
| %UIMA_HOME%/examples directory</para></listitem> | |
| <listitem><para>Click <quote>Finish.</quote> This will create a new project called | |
| <quote>uimaj-examples</quote> in your Eclipse workspace. There should be no | |
| compilation errors. </para></listitem></itemizedlist> | |
| <para>To verify that you have set up the project correctly, check that there are no error | |
| messages in the <quote>Problems</quote> view.</para> | |
| </section> | |
| <section id="ugr.ovv.eclipse_setup.adding_source"> | |
| <title>Adding the UIMA source code to the jar files</title> | |
| <note><para>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).</para></note> | |
| <para>Otherwise, 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 directly 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: | |
| </para> | |
| <itemizedlist> | |
| <listitem> | |
| <para> | |
| Download and unpack the UIMA source distribution. | |
| </para> | |
| </listitem> | |
| <listitem> | |
| <para> | |
| 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). | |
| </para> | |
| </listitem> | |
| <listitem> | |
| <para>"cd" to the root directory of the source distribution</para> | |
| </listitem> | |
| <listitem> | |
| <para> | |
| Execute the <command>src\main\readme_src\addSourceToJars</command> script in the root directory of the | |
| source distribution. | |
| </para> | |
| </listitem> | |
| </itemizedlist> | |
| <para> | |
| 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. | |
| </para> | |
| </section> | |
| <section id="ugr.ovv.eclipse_setup.linking_uima_javadocs"> | |
| <title>Attaching UIMA Javadocs</title> | |
| <para>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. | |
| </para> | |
| <note><para>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.</para></note> | |
| <para>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 <quote>F2</quote> to make the hover "stick", or | |
| <quote>Shift-F2</quote> to open the default | |
| web-browser on your system to let you browse the entire Javadoc information | |
| for that element. | |
| </para> | |
| <para>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. | |
| </para> | |
| <para>Eclipse also has a Javadoc "view" which you can show, using the Window → | |
| Show View → Javadoc.</para> | |
| <para>See <olink targetdoc="&uima_docs_ref;"/> | |
| <olink targetdoc="&uima_docs_ref;" targetptr="ugr.ref.javadocs.libraries"/> | |
| 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.</para> | |
| <para>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. | |
| </para> | |
| <para>Here's a screenshot of what you should see when you hover your mouse pointer over the | |
| class name <quote>CAS</quote> in the source code. | |
| </para> | |
| <informalfigure> | |
| <mediaobject> | |
| <imageobject> | |
| <imagedata width="5.7in" format="JPG" fileref="&imgroot;image004.jpg"/> | |
| </imageobject> | |
| <textobject><phrase>Screenshot of mouse-over for UIMA APIs</phrase> | |
| </textobject> | |
| </mediaobject> | |
| </informalfigure> | |
| </section> | |
| <section id="ugr.ovv.eclipse_setup.running_external_tools_from_eclipse"> | |
| <title>Running external tools from Eclipse</title> | |
| <para>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.</para> | |
| <para>To run these tools from Eclipse:</para> | |
| <itemizedlist spacing="compact"><listitem><para>If the Java perspective is not | |
| already open, switch to it by going to Window → Open Perspective → | |
| Java.</para></listitem> | |
| <listitem><para>Go to Run → Run... </para></listitem> | |
| <listitem><para>In the window that appears, select <quote>UIMA CPE GUI</quote>, | |
| <quote>UIMA CAS Visual Debugger</quote>, <quote>UIMA JCasGen</quote>, or | |
| <quote>UIMA Document Analyzer</quote> | |
| 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).</para></listitem> | |
| <listitem><para>Press the <quote>Run</quote> button. The tools should start. Close | |
| the tools by clicking the <quote>X</quote> in the upper right corner on the GUI. | |
| </para></listitem></itemizedlist> | |
| <para>For instructions on using the Document Analyzer and CPE Configurator, | |
| in the <olink targetdoc="&uima_docs_tools;"/> book see <olink | |
| targetdoc="&uima_docs_tools;" targetptr="ugr.tools.doc_analyzer"/>, and | |
| <olink targetdoc="&uima_docs_tools;" targetptr="ugr.tools.cpe"/> For | |
| instructions on using the CAS Visual Debugger and JCasGen, see <olink | |
| targetdoc="&uima_docs_tools;" targetptr="ugr.tools.cvd"/> and | |
| <olink targetdoc="&uima_docs_tools;" targetptr="ugr.tools.jcasgen"/></para> | |
| </section> | |
| </chapter> |