Setting up Eclipse

jawi edited this page Aug 14, 2012 · 1 revision

This tutorial will guide you into setting up a local Eclipse environment for testing/developing purposes.


For developing on OLS using Eclipse, you need:

  • A recent Java JDK, at least Java 6;
    • Ensure that there's an environment setting named JAVA_HOME that points to your JDK, for example, JAVA_HOME=C:\Program Files\Java\jdk1.7.0_05;
  • A recent Eclipse, for example, Eclipse Juno with the following plugins:
    • EGit, install it by hand using the Eclipse Marketplace if necessary;
    • m2eclipse, can also be found in the Eclipse Marketplace;
  • Not strictly needed, but for convenience, you probably also want to install version 1.8+ of Apache ANT.

Setting up Eclipse

Start Eclipse, and let it create a new workspace for you, e.g, C:\Sources\ols or /home/user/src/ols.

Now we're ready to import the sources from the OLS GitHub repository. Due to a bug in the m2eclipse egit connector, we're unable to use the Maven import functionality. We have to use the following workaround:

  1. File -> Import... -> Projects from Git;
  2. Select URI;
  3. In "Source Git Repository" view, enter git:// in the URI field (all other fields will be prefilled automatically by this) and hit next;
  4. In the "Branch Selection" step, you can choose which branches you want to check out. For the bare minimum, only select the "master" branch and hit next;
  5. Now, tell Eclipse where the sources should be stored on your local machine, enter a valid directory name (or use the default) and hit finish;
  6. The "New Project" wizard is started, but we cancel this wizard.

The Git repository is already cloned onto your machine. As all projects are Maven projects, we start a new import:

  1. File -> Import... -> Existing Maven Projects;
  2. Set the "root directory" to your local Git repository directory, after a while a lot of projects should appear in the "Projects" listing;
  3. Make sure all projects are selected, and hit Finish;
  4. A warning dialog is presented about possible build errors, which can be ignored by pressing "OK".

After a while, the projects explorer will list all imported projects of the OLS client.

Building all projects in Eclipse

To build all Maven projects in Eclipse, you need to create a new "Run Configuration":

  1. Hit the small triangle besides the green run icon, and select the "Run Configurations..." option;
  2. Select the "Maven Build" item, and hit the 'New' button as denoted on the right side;
  3. Give this configuration a sensible name, like "Maven Build All";
  4. As "Base Directory", select the directory from the workspace that contains all project, like ${workspace_loc:/ols};
  5. As "Goals" enter "install", or "clean install";
  6. Hit "Run" to start your build.

Running the OLS client from Eclipse

After a Maven build is performed, a complete client installation is created in ols.distribution/target/ols-X.Y.Z-full/ols-X.Y.Z. You can either run the run.bat directly from that directory, or create a run configuration in Eclipse:

  1. Add a new "Run Configuration" for a "Java Application";
  2. Give it a sensible name, like "Run OLS client";
  3. Let "Project" point to the runner (or nl.lxtreme.ols.runner) project;
  4. As "Main Class" enter nl.lxtreme.ols.runner.Runner;
  5. On the "Arguments" tab, override the "Working Directory", and let it point to ols.distribution/target/ols-X.Y.Z-full/ols-X.Y.Z;
  6. Hit "Run" to start the OLS client.

Alternatively, this run configuration can also be used to debug the OLS client from Eclipse.

Working on/with the OLS client

If you're working only on a single project, you might want to create a new run configuration for a Maven build in which the "Base Directory" points to that particular project. Note that this only will create an artifact for your project, but this will not copy it to your plugins directory! You need to do this by hand after the build is finished. For example, when working on the tool.uart plugin, simply copy tool.uart/target/uart-1.0.0.jar to ols.distribution/target/ols-X.Y.Z-full/ols-X.Y.Z/plugins is sufficient. You can even do this while the client is running, as it is capable of handling runtime modifications.

Frequently Asked Questions

That is a lot of steps to work on the OLS client
True, the current build set up is far from being very helpful in normal development. In fact, developing for OSGi in Eclipse can be done far more easier using BndTools. For progress on this, see;

The Maven build fails with a message about JAVA_HOME not set
You need to set the JAVA_HOME environment setting to your local JDK installation directory and restart Eclipse to allow the embedded Maven runtime to pick it up;

When debugging your client, I do not see the sources of project XXX
You need to tell Eclipse where to look for the sources. Hit the "Edit Source Lookup Path" in the file you want to view, and click on the "Add..." button. Select "Java Project" and hit "OK". A list of all projects is presented, in which you can add one or simply all projects to the source lookup path. After making your selection and hitting "OK", the view should show the actual source code.

Eclipse sucks! Can I use Idea/NetBeans/Emacs/VI/...?
You can, but then you are on your own. I personally prefer Eclipse as it is an IDE I'm mostly accustomed to, if you want to use an alternative, go ahead.