Chapter 65. The Eclipse Plugins

Table of Contents

65.1. Usage
65.2. Tasks
65.3. Configuration
65.4. Customizing the generated files

The Eclipse plugins generate files that are used by the Eclipse IDE, thus making it possible to import the project into Eclipse (File - Import... - Existing Projects into Workspace). Both external dependencies (including associated source and Javadoc files) and project dependencies are considered.

Since version 1.0-milestone-4 of Gradle, the WTP-generating code was refactored into a separate plugin called eclipse-wtp. So if you are interested in WTP integration then only apply the eclipse-wtp plugin. Otherwise applying the eclipse plugin is enough. This change was requested by Eclipse users who take advantage of the war or ear plugins, but who don't use Eclipse WTP. Internally, the eclipse-wtp plugin also applies the eclipse plugin so you don't need to apply both of those plugins.

What exactly the eclipse plugin generates depends on which other plugins are used:

Table 65.1. Eclipse plugin behavior

PluginDescription
NoneGenerates minimal .project file.
JavaAdds Java configuration to .project. Generates .classpath and JDT settings file.
GroovyAdds Groovy configuration to .project file.
ScalaAdds Scala support to .project and .classpath files.
WarAdds web application support to .project file.
EarAdds ear application support to .project file.

However, the eclipse-wtp plugin always generates all WTP settings files and enhances the .project file. If a Java or War is applied, .classpath will be extended to get a proper packaging structure for this utility library or web application project.

Both Eclipse plugins are open to customization and provide a standardized set of hooks for adding and removing content from the generated files.

65.1. Usage

To use either the Eclipse or the Eclipse WTP plugin, include one of the lines in your build script:

Example 65.1. Using the Eclipse plugin

build.gradle

apply plugin: 'eclipse'

Example 65.2. Using the Eclipse WTP plugin

build.gradle

apply plugin: 'eclipse-wtp'

Note: Internally, the eclipse-wtp plugin also applies the eclipse plugin so you don't need to apply both.

Both Eclipse plugins add a number of tasks to your projects. The main tasks that you will use are the eclipse and cleanEclipse tasks.

65.2. Tasks

The Eclipse plugins add the tasks shown below to a project.

Table 65.2. Eclipse plugin - tasks

Task name Depends on Type Description
eclipse all Eclipse configuration file generation tasks Task Generates all Eclipse configuration files
cleanEclipse all Eclipse configuration file clean tasks Delete Removes all Eclipse configuration files
cleanEclipseProject - Delete Removes the .project file.
cleanEclipseClasspath - Delete Removes the .classpath file.
cleanEclipseJdt - Delete Removes the .settings/org.eclipse.jdt.core.prefs file.
eclipseProject - GenerateEclipseProject Generates the .project file.
eclipseClasspath - GenerateEclipseClasspath Generates the .classpath file.
eclipseJdt - GenerateEclipseJdt Generates the .settings/org.eclipse.jdt.core.prefs file.

Table 65.3. Eclipse WTP plugin - additional tasks

Task name Depends on Type Description
cleanEclipseWtpComponent - Delete Removes the .settings/org.eclipse.wst.common.component file.
cleanEclipseWtpFacet - Delete Removes the .settings/org.eclipse.wst.common.project.facet.core.xml file.
eclipseWtpComponent - GenerateEclipseWtpComponent Generates the .settings/org.eclipse.wst.common.component file.
eclipseWtpFacet - GenerateEclipseWtpFacet Generates the .settings/org.eclipse.wst.common.project.facet.core.xml file.

65.3. Configuration

Table 65.4. Configuration of the Eclipse plugins

Model Reference name Description
EclipseModel eclipse Top level element that enables configuration of the Eclipse plugin in a DSL-friendly fashion.
EclipseProject eclipse.project Allows configuring project information
EclipseClasspath eclipse.classpath Allows configuring classpath information.
EclipseJdt eclipse.jdt Allows configuring jdt information (source/target Java compatibility).
EclipseWtpComponent eclipse.wtp.component Allows configuring wtp component information only if eclipse-wtp plugin was applied.
EclipseWtpFacet eclipse.wtp.facet Allows configuring wtp facet information only if eclipse-wtp plugin was applied.

65.4. Customizing the generated files

The Eclipse plugins allow you to customize the generated metadata files. The plugins provide a DSL for configuring model objects that model the Eclipse view of the project. These model objects are then merged with the existing Eclipse XML metadata to ultimately generate new metadata. The model objects provide lower level hooks for working with domain objects representing the file content before and after merging with the model configuration. They also provide a very low level hook for working directly with the raw XML for adjustment before it is persisted, for fine tuning and configuration that the Eclipse and Eclipse WTP plugins do not model.

65.4.1. Merging

Sections of existing Eclipse files that are also the target of generated content will be amended or overwritten, depending on the particular section. The remaining sections will be left as-is.

65.4.1.1. Disabling merging with a complete rewrite

To completely rewrite existing Eclipse files, execute a clean task together with its corresponding generation task, like “gradle cleanEclipse eclipse” (in that order). If you want to make this the default behavior, add “tasks.eclipse.dependsOn(cleanEclipse)” to your build script. This makes it unnecessary to execute the clean task explicitly.

This strategy can also be used for individual files that the plugins would generate. For instance, this can be done for the “.classpath” file with “gradle cleanEclipseClasspath eclipseClasspath”.

65.4.2. Hooking into the generation lifecycle

The Eclipse plugins provide objects modeling the sections of the Eclipse files that are generated by Gradle. The generation lifecycle is as follows:

  1. The file is read; or a default version provided by Gradle is used if it does not exist
  2. The beforeMerged hook is executed with a domain object representing the existing file
  3. The existing content is merged with the configuration inferred from the Gradle build or defined explicitly in the eclipse DSL
  4. The whenMerged hook is executed with a domain object representing contents of the file to be persisted
  5. The withXml hook is executed with a raw representation of the XML that will be persisted
  6. The final XML is persisted

The following table lists the domain object used for each of the Eclipse model types:

Table 65.5. Advanced configuration hooks

Model beforeMerged { arg -> } argument type whenMerged { arg -> } argument type withXml { arg -> } argument type withProperties { arg -> } argument type
EclipseProject Project Project XmlProvider -
EclipseClasspath Classpath Classpath XmlProvider -
EclipseJdt Jdt Jdt - java.util.Properties
EclipseWtpComponent WtpComponent WtpComponent XmlProvider -
EclipseWtpFacet WtpFacet WtpFacet XmlProvider -

65.4.2.1. Partial overwrite of existing content

A complete overwrite causes all existing content to be discarded, thereby losing any changes made directly in the IDE. Alternatively, the beforeMerged hook makes it possible to overwrite just certain parts of the existing content. The following example removes all existing dependencies from the Classpath domain object:

Example 65.3. Partial Overwrite for Classpath

build.gradle

eclipse.classpath.file {
    beforeMerged { classpath ->
        classpath.entries.removeAll { entry -> entry.kind == 'lib' || entry.kind == 'var' }
    }
}


The resulting .classpath file will only contain Gradle-generated dependency entries, but not any other dependency entries that may have been present in the original file. (In the case of dependency entries, this is also the default behavior.) Other sections of the .classpath file will be either left as-is or merged. The same could be done for the natures in the .project file:

Example 65.4. Partial Overwrite for Project

build.gradle

eclipse.project.file.beforeMerged { project ->
    project.natures.clear()
}


65.4.2.2. Modifying the fully populated domain objects

The whenMerged hook allows to manipulate the fully populated domain objects. Often this is the preferred way to customize Eclipse files. Here is how you would export all the dependencies of an Eclipse project:

Example 65.5. Export Dependencies

build.gradle

eclipse.classpath.file {
    whenMerged { classpath ->
        classpath.entries.findAll { entry -> entry.kind == 'lib' }*.exported = false
    }
}


65.4.2.3. Modifying the XML representation

The withXmlhook allows to manipulate the in-memory XML representation just before the file gets written to disk. Although Groovy's XML support makes up for a lot, this approach is less convenient than manipulating the domain objects. In return, you get total control over the generated file, including sections not modeled by the domain objects.

Example 65.6. Customizing the XML

build.gradle

apply plugin: 'eclipse-wtp'

eclipse.wtp.facet.file.withXml { provider ->
    provider.asNode().fixed.find { it.@facet == 'jst.java' }.@facet = 'jst2.java'
}