Revision as of 12:22, August 30, 2013

Instructions for setting up Eclipse for working with Protege using maven

Under construction

This would be better if we could do this using mvn eclipse:eclipse. But when I tried this the resulting plugin projects were all messed up. So after a lot of experimentation I came up with another more manual approach.

On the other hand, mvn eclipse:eclipse works very well with the owl api and I think that this is a fun and easy way of including the owlapi sources.

Prerequisites

To follow these directions you will need the following tools:

• Eclipse (of course) with
  • the Plugin Development tools included. As indicated here, the plugin development environment comes with the Java EE or the RCP/Plugin versions of eclipse.
  • the Eclipse Subversive plugin, though this is only required if you want to do svn updates using eclipse. Note that there is another similar but different plugin (from Tigris I believe). I don't know if these plugins interfere with one another if they are both loaded.
• A tool for checking out a git repository. This is useful for getting the owlapi sources and setting up owlapi projects.
• Optionally the bnd tool. This is useful for creating owlapi bundles from the owlapi sources. If you use a version of the owlapi that has an osgi bundle version in maven central then you won't need this.
• The maven build tool.

These directions are based on a preconfigured workspace which you can use for the build.

Configuring Eclipse

This is just one method of setting up eclipse and so feel free to adjust the approach to suit your preferences. When I first set up eclipse this way, I decided to have the Protege source tree be in a separate but parallel directory to the eclipse workspace. I decided that I like this arrangement because, as you will see, it ensures that the eclipse workspace files don't show up as modifications to the Protege source tree sources.

Temporary workaround here

When the explanation, client and server projects are checked into maven this step will not be necessary. For now, in some directory other perform the following operations:

            git clone https://github.com/protegeproject/org.protege.explanation
            cd org.protege.explanation
            mvn clean install
            cd ..

            git clone https://github.com/protegeproject/org.protege.owl.server
            cd org.protege.owl.server
            mvn clean install
            cd ..

            git clone https://github.com/protegeproject/org.protege.editor.owl.client
            cd org.protege.editor.owl.client
            mvn clean install
            cd ..

I generally do this in the protege5-workspace directory that I use later. Temporary workaround here

The first step in this process is to check-out the Protege sources. The method for doing this is going to change in the very near future. For now you need to checkout the nosubmodules branch of the git repository [1]. You can use any client that you like to perform the ckeck-out but for my command line client the command is as follows:

            git clone --branch nosubmodules https://github.com/protegeproject/protege protege5

Now we build Protege using the maven command:

    cd protege5
    mvn clean install

This takes a little while to run (about a minute on my computer) so now would be a good time to go get a cup of coffee. By running this, we have built a fully functional copy of Protege (in a directory with a name like protege-distribution/target/protege-distribution-5.0.0-beta-04-bin/Protege) and we have arranged that any generated source directories needed by the build are present.

Now we can set up the projects for eclipse. To do this first download a zip file that contains the eclipse information. This zip file can be found here. Unzip this file into the protege5 directory. Note that in addition to including the usual .project and .classpath files, this zip file also contains the META-INF/MANIFEST.MF files. These manifest files are duplicates of the manifest files that are included in the bundles that are created by the mvn build scripts.

Now we start eclipse to create a workspace. This step can actually be done while the maven install step abbove is running. In my example, I created the workspace in a separate directory, protege5-workspace that is at the same level as the protege5 directory that I just created. In this first run of eclipse, all that I plan to do is to setup a parameter that points to the local maven repository. To do this, click on Window->Preferences (Eclipse->Preferences on a mac), select General->Workspace->Linked Resources and click on the button that defines a new path variable.

In this window configure the M2_REPO variable so that it points to the local maven repository which is usually (always?) located at '.m2/repository' in your home directory. This allows me to set up the eclipse projects so that they do not require pointers to system specific locations. The system specific location of the repository is set once in the eclipse workspace rather than several times in each project.

First you need to import the owl api as an eclipse plugin project. Click on File->Import... and select Plug-in Development->Plug-ins and Fragments.

In the next screen you can set the directory to import from to be

            protege5/protege-distribution/target/protege-distribution-5.0.0.beta-04-bin/Protege/plugins.

Finally on the next screen, you can select the OWL api for import.

Now we can import the eclipse projects from the protege5 directory. From the file menu click Import, select General/Existing Projects into Workspace, and click next:

In the next screen, make sure that "Select root directory" is selected, browse to the protege5 directory that we were working on before, select the plugins that you want to include and click finish:

At the moment there are not too many projects to select here but as we work on this the maven-eclipse-projects.zip file will include more of these. A good initial selection of three projects to include are org.protege.common, org.protege.editor.core.application and org.protege.editor.owl. At this point in the "Problems" view there will be a single compilation error:

Access restriction: The method render() from the type RDFRendererBase is not accessible due to restriction on required library org.semanticweb.owl.owlapi/owlapi-distribution.jar

I don't know what this error means yet but it appears to be harmless.

Running Protege

Running Protege using the eclipse OSGi support

This is the easiest type of runnable to create, run and debug. But there are two issues with this approach. First, if you are running mac os x, it won't work. The Mac has some long standing problems with java and eclipse and there appear to be troubles. But it works just fine on linux and windows. Second, this type of runnable may hide or change issues that would occur when the plugin is run in a true Protege deployment. I don't know exactly what eclipse does to make this type of runnable work but suffice it to say that eclipse is being a bit tricky. It is a good idea to at least occasionally the runnable in a more Protege-like environment such as is created by runnable that I describe in the next section.

• Create a new OSGi runnable
• Select all the Workspace plugins that you want.
• Deselect all the Target Platform plugins
• Click "Add Required Bundles"

Then add some jvm options to specify a logger and memory such as, for example:

-Declipse.ignoreApp=true -Dosgi.noShutdown=true
-Xmx2048M
-Dlog4j.configuration=file:${workspace_loc:org.protege.editor.owl/log4j.xml}

This setup is generating an exception for me

org.osgi.framework.BundleException: Could not find bundle: org.eclipse.equinox.console
	at org.eclipse.osgi.framework.internal.core.ConsoleManager.checkForConsoleBundle(ConsoleManager.java:211)
	at org.eclipse.core.runtime.adaptor.EclipseStarter.startup(EclipseStarter.java:297)
	at org.eclipse.core.runtime.adaptor.EclipseStarter.run(EclipseStarter.java:176)
	at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
	at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)
	at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
	at java.lang.reflect.Method.invoke(Method.java:606)
	at org.eclipse.equinox.launcher.Main.invokeFramework(Main.java:629)
	at org.eclipse.equinox.launcher.Main.basicRun(Main.java:584)
	at org.eclipse.equinox.launcher.Main.run(Main.java:1438)
	at org.eclipse.equinox.launcher.Main.main(Main.java:1414) 

When I tried to fix this I got into some problems but it doesn't seem too important.

On a linux machine this works perfectly but on the mac it failed with the exception

               java.lang.UnsupportedClassVersionError: org/protege/editor/owl/ProtegeOWL : Unsupported major.minor version 51.0

This is a serious problem but if it only happens on the mac it may be irrelevant because historically the macs have been unable to run swing programs in eclipse-OSGi mode even after the bug about the problem was closed.

Adding OWL api projects

       git clone git://owlapi.git.sourceforge.net/gitroot/owlapi/owlapi
       cd owlapi
       mvn -Declipse.workspace=../protege5-workspace eclipse:add-maven-repo
       mvn eclipse:clean eclipse:eclipse

Import the Existing projects into workspace.

Add your own plugin