The Eclipse plugin generates files that are used by the Eclipse IDE, thus making it possible to import the project into Eclipse ( - - ). Both external dependencies (including associated source and javadoc files) and project dependencies are considered.
Since 1.0-milestone-4 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 eclipse
plugin is enough.
This change was requested by Eclipse users who take advantage of war
or ear
plugin
but they don't use Eclipse WTP. Internally, eclipse-wtp
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 36.1. Eclipse plugin behavior
Plugin | Description |
None | Generates minimal .project file. |
Java | Adds Java configuration to .project .
Generates .classpath and JDT settings file. |
Groovy | Adds Groovy configuration to .project file. |
Scala | Adds Scala support to .project file. |
War | Adds web application support to .project file.
Generates WTP settings files only if eclipse-wtp plugin was applied. |
Ear | Adds ear application support to .project file.
Generates WTP settings files only if eclipse-wtp plugin was applied. |
The Eclipse plugin is open to customization and provides a standardized set of hooks for adding and removing content from the generated files.
To use the Eclipse plugin, include this in your build script:
The Eclipse plugin adds a number of tasks to your projects. The main tasks that you will use
are the eclipse
and cleanEclipse
tasks.
The Eclipse plugin adds the tasks shown below to a project.
Table 36.2. Eclipse plugin - tasks
Task name | Depends on | Type | Description |
eclipse
|
eclipseProject , eclipseClasspath , eclipseJdt ,
eclipseWtpComponent , cleanEclipseWtpFacet |
Task |
Generates all Eclipse configuration files |
cleanEclipse
|
cleanEclipseProject , cleanEclipseClasspath , cleanEclipseJdt ,
cleanEclipseWtpComponent , cleanEclipseWtpFacet
|
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. |
cleanEclipseWtpComponent
|
-
|
Delete |
Removes the .settings/org.eclipse.wst.common.component file. |
cleanEclipseWtpFacet
|
-
|
Delete
|
Removes the .settings/org.eclipse.wst.common.component file.
|
eclipseProject
|
-
|
GenerateEclipseProject |
Generates the .project file. |
eclipseClasspath
|
-
|
GenerateEclipseClasspath |
Generates the .classpath file. |
eclipseJdt
|
-
|
GenerateEclipseJdt |
Generates the .settings/org.eclipse.jdt.core.prefs file. |
eclipseWtpComponent
|
-
|
GenerateEclipseWtpComponent |
Generates the .settings/org.eclipse.wst.common.component file only if eclipse-wtp plugin was applied. |
eclipseWtpFacet
|
-
|
GenerateEclipseWtpFacet
|
Generates the .settings/org.eclipse.wst.common.project.facet.core.xml file only if eclipse-wtp plugin was applied. |
Table 36.3. Configuration of the Eclipse plugin
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. |
The Eclipse plugin allows you to customise the generated metadata files. The plugin provides 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 plugin does not model.
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.
To completely overwrite existing Eclipse files, execute a clean task together with its corresponding generation task,
for example 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.
Complete overwrite works equally well for individual files, for example by executing gradle cleanEclipseClasspath eclipseClasspath
.
The Eclipse plugin provides objects modeling the sections of the Eclipse files that are generated by Gradle. The generation lifecycle is as follows:
beforeMerged
hook is executed with a domain object representing the existing filewhenMerged
hook is executed with a domain object representing contents of the file to be persistedwithXml
hook is executed with a raw representation of the xml that will be persistedThe following table lists the domain object used for each of the Eclipse model types:
Table 36.4. Advanced configuration hooks
Model | beforeMerged { arg -> } argument type |
whenMerged { arg -> } argument type |
withXml { arg -> } argument type |
EclipseProject |
Project |
Project |
XmlProvider |
EclipseClasspath |
Classpath |
Classpath |
XmlProvider |
EclipseJdt |
Jdt |
Jdt |
|
EclipseWtpComponent |
WtpComponent |
WtpComponent |
XmlProvider |
EclipseWtpFacet |
WtpFacet |
WtpFacet |
XmlProvider |
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 36.2. 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 36.3. Partial Overwrite for Project
build.gradle
eclipse.project.file.beforeMerged { project -> project.natures.clear() }
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 36.4. Export Dependencies
build.gradle
eclipse.classpath.file {
whenMerged { classpath ->
classpath.entries.findAll { entry -> entry.kind == 'lib' }*.exported = false
}
}
The withXml
hook 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 36.5. 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' }