Large projects often come with an independent (usually ant based) build system – so that the project can be built effectively in different situations. For programmers working on these projects, this often means setting up the IDE to work with these build systems. While working with development teams, I have seen way too many examples of the IDE not setup to take advantage of some of their features. Especially these days, IDE’s absolutely rock, so if you are not taking advantage of them then you are likely putting yourself at a disadvantage.

Below are a set of steps that you can follow to configure Eclipse to effectively work on your project:

1) Ensure your build system is working

The first part has nothing to do with your IDE. But before trying to take advantage of all the cool Eclipse features you need to get the basics working first. Depending on the setup, some build systems might need to not only have certain software not running, but also have both the code checked out in particular directories and also have software installed in other fixed directories. Once you have your build system setup, you can configure to use Eclipse with the project.

2) Project setup in Eclipse

To setup your project in Eclipse, launch Eclipse and choose a location for the workspace – the location does not matter as much. Once Eclipse starts go to the File menu, choose New, and select Java Project. Give the project a name, and tell Eclipse to Create project from existing source, and type in the project directory.

At this point you should be able to edit files from within Eclipse, and have the benefit of having multiple files opened in the various tabs. You can also try Ctrl+Shift+R to quickly open a file. Eclipse does not yet know about the source code in the project, so you will not see syntax highlighting yet – for that you will need to get to step 4.

3) Using the Build system from within Eclipse

Now that you have your build system working, you can choose to not have a separate window open for just running the build. Integrating Ant builds into Eclipse is easy – just find the build.xml, right click on it, and in the dropdown menu, go to Run As then Ant Build. This is the same as doing ant local – if you want to run another ant target just click on the Ant Build… option instead. The build output will be shown in the Eclipse Console window.

Quickly find build.xml using Ctrl+Shift+r

Once you have started an ant build you should be able to run it again easily by finding it in the Eclipse toolbar – look for the green circle containing a white arrow pointing right and having a red suitcase with the text Run project_name build.xml shown when you hover the mouse over it. Clicking on the drop down should show the various build configurations that you might have created.

Caution: One common error cause when running ant tasks is when there are multiple ant targets that you want to execute. Make sure that you not only select the ant targets from the configuration dialog but that you also verify that the Target execution order is correct.

4) Using Eclipse’s Build System

Once you are able to get the external build system working, you can use Eclipse – atleast for compiling the Java source files that you modify. On configuring Eclipse, it can not only provide syntax highlighting but also parse any changes even before you save the files so that you can fix code errors immediately. Setting this up means telling Eclipse (a) where your Java code is and (b) where your libraries (jar files) are for building the files.

To configure Eclipse’s build system, right click on the Project (which you will be able to see in the Project Explorer, the Package Explorer, or the Navigator views) and select Properties. Once there click on Java Build Path on the left hand side and to setup your Java code source location make sure that the Source tab is selected. Here you can add one or more of your folders so that Eclipse can compile them. Next click on the Libraries tab and add all the jar files that might be needed in the compilation process. Once that is done, hit OK and let Eclipse build the project. If there are any errors (shown in the Problems view) then they will need to be fixed.

run previously created build configurations

5) Debugging in Eclipse

Beyond having Eclipse help in managing editing code and compiling it, you can also use the great debugger that comes integrated into Eclipse. To do so you would first need to launch your application with remote debugging enabled. The details depend on how you launch the app, but it mostly boils down to starting the JVM with -Xdebug and -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=1044 (see here for jvm launching details).

Once you launch the JVM, you need to create a remote debugging instance from within Eclipse. Go to the main menu, select Run, choose Debug Configurations…, select Remote Java Application in the left side and click on the New launch configuration button at the top of the left side. The degug configuration will need a name, and all you need to do is select the project that you will be debugging (so that Eclipse knows where to map the code stepping to), and then to click on the Apply button. With this configuration setup you should be able to connect to any launched instance by running the debug configuration.

6) Fixing bugs while debugging….

One of the nice things of modern IDE’s is that if while debugging and stepping through your Java code you find a bug, you can just edit it and continue executing the code with the new changes. Even while working with an externally launched application you can easily setup Eclipse to do hot code replacements as needed. To do this, all you need to do is have the class files generated by Eclipse’s builder to be placed in the correct directory. You can change these build settings by right clicking on the project, select Properties, then Java Build Path and Source to make sure the Default output folder is in the same directory as the external build system is placing the .class files (thus letting Eclipse to take your changes over-write the older class files).

7) Document integration

Ok, now that you have gotten Eclipse working well for your project, the next step would be document the steps so that the rest of the team can benefit from your experience. (perhaps you can use this article as a template to start).