Eclipse

This plugin provides integration of the build system features in Eclipse.

Dependencies

• compile and runtime are mandatory
• Supports for commons-attributes and config-conffolder are implemented

Declaration

Here is an example of how to use the eclipse plugin:

  <plugin name="eclipse">
    <attribute name="eclipse.workspace.path" value="workspace"/>
    <!-- External tools prefix -->
    <attribute name="eclipse.prefix" value="MyProject_"/>
    <!-- Eclipse targets -->
    <attribute name="eclipse.tools" value="eclipse.generate"/>
    <!-- compile targets -->
    <attribute name="eclipse.tools" value="clean.module,jars"/>
    <!-- junit targets -->
    <attribute name="eclipse.tools" value="junit.startdev.all"/>
    <!-- reports targets -->
    <attribute name="eclipse.tools" value="javadoc,checkstyle"/>
    <!-- j2ee-war and j2ee-war-tomcat targets -->
    <attribute name="eclipse.tools" value="create.war.module.eu,deploy.war.module.eu"/>
    <!-- binrelease targets -->
    <attribute name="eclipse.tools" value="binrelease.module"/>
  </plugin>

If you do not use some plugins, the corresponding targets should be removed from eclipse.tools attributes. You can also limit the list to mostly used targets.

Usage

First of all, it is necessary to use the build system Ant version. In Eclipse, open Window-> Preferences, Ant->Runtime->Classpath and set Ant Home to your current Ant directory (1.6.5 or later).

At project configuration, the plugin generates .project and .classpath files for each module, the corresponding Eclipse projects must be imported into Eclipse if they have not been imported yet or refreshed if they are already in Eclipse.

To ease the importation of multiple projects into Eclipse, the "Multi Project Import/Export" Eclipse plugin can be used. This plugin can be found on the web.

Some targets cannot be included in Eclipse at configuration, to work-around this limitation, you have to invoke eclipse.generate to create runtime shortcuts. In case of a change in shortcuts, the workspace must be refreshed to include new external tools. This can be done for example by restarting Eclipse (or the workspace).

Ant targets are inserted in external tools:

• as a normal target if it does not apply to a module,
• or as a shortcut with module and execution unit names,
• or as a generic target (like clean.module for instance) that applies to the current module (selected project in Eclipse).

With BinRelease plugin

The global binrelease.default.excludes attribute should be set to java/**,.classpath,.project,.externalToolBuilders/**.

If you are interested in keeping java sources for documentation and debug in Eclipse, you can set it to .classpath,.project,.externalToolBuilders/**.

With Checkstyle plugin

The checkclipse plugin enables Checkstyle warnings in your Eclipse workbench.

• Download the plugin from http://www.mvmsoft.de/content/plugins/checkclipse/checkclipse.htm
• Unzip the file where your Eclipse is installed in folder plugins. After unzipping it you should have a folder de.mvmsoft.checkclipse_x.y.z in the plugins folder.
• Restart Eclipse.
• Open Window/Preferences. You should see now a entry Checkclipse on the left. Click on it.

• Set the checkboxes like in picture above.
• Set the field Checkstyle Configuration File with the path of the file checkstyle_el4ant_checks.xml which can be found in folder etc of your EL4Ant project.
• Inside this Checkstyle Configuration File properties can be defined. To resolve these properties you have to copy the properties file checkstyle_el4ant.properties which can also be found in folder etc into another directory as the EL4Ant project is. We recommend to create a folder el4ant into directory from eclipse and copy this file into. This copy is necessary, because you have to adapt the property file to your local folder structure, because otherwise the Checkclipse plugin could not find the el4ant_java_header_file. Open the copied properties file in an editor and change the property el4ant_java_header_file to your local folder structure, i.e. el4ant_java_header_file=D:/Projects/EL4Ant/etc/el4ant_java_header. Be aware that you use / and NOT \ for the path. FYI: The file el4ant_java_header which is needed here is situated in the same directory as the checkstyle_el4ant_checks.xml (folder etc).
• Close window Preferences by pushing button Ok. Now the workspace should be rebuilt and checkstyle checks should be made.

Note: To have warnings displayed in view Problems you have to adapt the filter of this view. Just push the filter button (upper right of the view) and check entry de.mvmsoft.checkclipse.CheckclipseMarker.

Features

• At configure-time, it creates the .project and .classpath files for each module that is declared and whose directory exists on disk. This way, one Eclipse project is created per module.
• At configure-time, it registers external tools in Eclipse to call build system targets directly from within Eclipse.
• At configure-time, a builder is automatically installed for modules that uses Commons Attributes (see commons-attributes plugin), to call the Ant target commons-attributes.module. This way, commons attributes are automatically generated and compiled when Eclipse builds the project.
• The generated .classpath file only refers to existing java/ and conf/ (see config-conffolder plugin) on disk when configuring or else Eclipse build fails.
• The target eclipse.generate registers Eclipse configurations to run and debug runnable module execution units. It is then possible to run and debug applications in Eclipse with the same environment (classpath, system properties,...) as if it was run from the command line.
• To ease development, inline documentation and debugging are improved thanks to the automatic registration of sources associated to classes. If a jar file myjar-1.3.jar is declared as dependency, the plugin expects the sources of the classes to be in the file lib/src/myjar-1.3-src.zip (and download it from online repositories if configured)

Targets

• eclipse.generate generates the Eclipse run/debug configurations for all the runnable module execution units.
• eclipse.generate.module generates the Eclipse run/debug configurations for all the runnable execution units of a specific module.
• eclipse.generate.module.eu generates the Eclipse run/debug configurations for a specific runnable module execution unit.

Attributes

Global

• eclipse.workspace.path is the path to the Eclipse workspace directory. If this attribute is not defined, the Eclipse plugin won't be able to automatically register Eclipse external tools and to define runnable/debuggable applications in Eclipse. Mandatory, no default value.
• eclipse.prefix is the prefix used to register runtime targets and external tools. Default is EL4Ant.
• eclipse.tools is a comma-separated list of Ant targets to publish in Eclipse as external tools. They must be available in your generated build.xml

Per module

• eclipse.project.type is the type of the Eclipse project to create for this module; this attribute is optional and accepts the following values:
  • java is used for a Java project (default value)
  • pde is used for a plugin development project for the eclipse rich client platform

Known bugs

• If you have removed some targets from the eclipse.tools attributes or change the eclipse.prefix value, you have to clean old entries manually from Run->External Tools->External Tools... and Run->Run... with the delete button.
• Runtime targets for JUnit modules (with the JUnit command creator) does not work. You have to use junit.startdev.all to generate reports but the JUnit progress bar is not shown in Eclipse.
• Running JUnit test cases with the Eclipse menu (all tests from a project or a single test case) does not consider command line modifications applied by declared runtime hooks.

After a new project configuration with commons attributes enabled, Eclipse build fails with this kind of message:

Errors during build.
  Errors running builder "Integrated External Tool Builder" on project aModule.
  Resource is out of sync with the file system: /aModule/.externalToolBuilders/el4ant_Commons Attributes Builder.launch.

The fastest way to work-around this issue is to refresh all projects (select all projects, right-click, Refresh) and then build again.

• When configuring CheckStyle, if the removal of the Sun Checks fails, you have to refresh all Eclipse projects first.

ToDo

• Integrate cleanly JUnit targets to include runtime hooks and also enable debugging.
• The commons attributes generation process could be faster by creating an Eclipse plugin that does the job directly without calling an Ant task.
• Improve access to project.xml and other files from the project base directory in Eclipse. Currently, the menu File->Open External File... must be used.