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.
What exactly the Eclipse plugin generates depends on which other plugins are used:
Table 27.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. |
One focus of the Eclipse plugin is to be open to customization. Each task 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
andcleanEclipse
tasks.
The Eclipse plugin adds the tasks shown below to a project.
Table 27.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 |
Generates the .project file. |
cleanEclipseClasspath
|
-
|
Delete |
Generates 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
|
-
|
EclipseProject |
Generates the .project file. |
eclipseClasspath
|
-
|
EclipseClasspath |
Generates the .classpath file. |
eclipseJdt
|
-
|
EclipseJdt |
Generates the .settings/org.eclipse.jdt.core.prefs file. |
eclipseWtpComponent
|
-
|
EclipseWtpComponent |
Generates the .settings/org.eclipse.wst.common.component file. |
eclipseWtpFacet
|
-
|
EclipseWtpFacet
|
Generates the .settings/org.eclipse.wst.common.project.facet.core.xml file. |
Table 27.3. EclipseProject task
Property | Type | Default Value | Description |
projectName
|
String
|
project.name |
The name of the Eclipse project. Must not be null. |
comment
|
String
|
project.description |
A comment for the Eclipse project. |
referencedProjects
|
Set<String>
|
empty set | The referenced projects of the Eclipse project. |
natures
|
List<String>
|
The default is an empty set. Applying Java, Groovy, Scala or War plugin will add additional natures. | The natures of the Eclipse project. |
buildCommands
|
List<BuildCommand>
|
The default is an empty set. Applying Java, Groovy, Scala or War plugin will add additional build commands. | The build commands of the Eclipse project. |
links
|
Set<Link>
|
empty set | The links for the Eclipse project. |
Table 27.4. EclipseClasspath task
Property | Type | Default Value | Description |
sourceSets
|
Iterable<SourceSet> |
sourceSets
|
The source sets whose source directories are to be added to the Eclipse classpath. |
containers
|
Set<String>
|
empty set | The containers to be added to the Eclipse classpath. |
plusConfigurations
|
Set<Configuration>
|
[configurations.testRuntime] |
The configurations whose files are to be transformed into classpath entries. |
minusConfigurations
|
Set<Configuration>
|
empty set | The configurations whose files are to be excluded from the classpath entries. |
downloadSources
|
boolean
|
true
|
Whether to download sources for external dependencies. |
downloadJavadoc
|
boolean
|
false
|
Whether to download javadoc for external dependencies. |
variables
|
Map<String,File>
|
[:] |
If the beginning of the absolute path of a library matches a value of a variable, a variable entry is created. The matching part of the library path is replaced with the variable name. |
Table 27.5. EclipseWtpComponent task
Property | Type | Default Value | Description |
sourceDirs
|
Set<File> |
<td>The source directories of sourceSets.main </td>
|
The source sets whose source directories are to be added to the Eclipse classpath. |
deployName
|
String
|
project.name |
The deploy name to be used. |
plusConfigurations
|
Set<Configuration>
|
[configurations.testRuntime] |
The configurations whose files are to be transformed into classpath entries. |
minusConfigurations
|
Set<Configuration>
|
[configurations.providedRuntime] |
The configurations whose files are to be excluded from the classpath entries. |
variables
|
Map<String,File>
|
[:] |
If the beginning of the absolute path of a library matches a value of a variable, a variable entry is created. The matching part of the library path is replaced with the variable name. |
Table 27.6. EclipseWtpFacet task
Property | Type | Default Value | Description |
facets
|
List<Facet>
|
jst.java
and
jst.web
facet
|
The facets to be added as installed elements. |
Table 27.7. Task Hooks
Method | EclipseProject Task Argument | EclipseClasspath Task Argument | EclipseWtpComponent Task Argument | EclipseWtpFacet Task Argument | Description |
|
Project |
Classpath |
WtpComponent |
WtpFacet |
Called after the domain objects have been populated with relevant content of the existing XML file (if there is one). |
|
Project |
Classpath |
WtpComponent |
WtpFacet |
Called after the domain objects have been populated with content from Gradle's build model. |
|
XmlProvider |
XmlProvider |
XmlProvider |
XmlProvider |
Called before the XML file is written to disk. |
All Eclipse tasks provide the same hooks and behavior for customizing the generated content.
The tasks recognize existing Eclipse files, and merge them with the generated content.
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 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 executinggradle cleanEclipseClasspath eclipseClasspath
.
The Eclipse plugin provides domain classes modeling the sections of the Eclipse files that are autogenerated by Gradle. The generation lifecycle is as follows:
beforeConfigured
hook is executedwhenConfigured
hook is executedwithXml
hook is executed
A complete overwrite causes all existing content to be discarded,
thereby losing any changes made directly in the IDE. The beforeConfigured
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 27.2. Partial Overwrite for Classpath
build.gradle
eclipseClasspath { beforeConfigured { 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 27.3. Partial Overwrite for Project
build.gradle
eclipseProject { beforeConfigured { project -> project.natures.clear() } }
The whenConfigured
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 27.4. Export Dependencies
build.gradle
eclipseClasspath {
whenConfigured { 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 27.5. Customizing the XML
build.gradle
eclipseWtpFacet { withXml { provider -> provider.asNode().fixed.find { it.@facet == 'jst.java' }.@facet = 'jst2.java' } }