The Eclipse plugin generates files that are used by Eclipse IDE, thus making it possible to import the project into Eclipse ( - - ). Both external and project dependencies are considered.
The Eclipse plugin will create different files depending on the other plugins used. If used together with
the Java plugin, .project
and .classpath
files will be generated. If used with the War plugin, additional wtp files
will be generated.
To use the Eclipse plugin, include in your build script:
There are several tasks (presented in Table 28.1, “Eclipse plugin - tasks”) that the Eclipse plugin provides. Some tasks
are preconfigured to use the GRADLE_CACHE
eclipse classpath variable. To make use of this variable
you need to define it in Eclipse pointing to <USER_HOME>/.gradle/cache
.
In a future release of Gradle this will be automated (Issue GRADLE-1074).
The Eclipse plugin adds the tasks shown below to a project.
Table 28.1. Eclipse plugin - tasks
Task name | Depends on | Type | Description |
eclipse
|
eclipseProject , eclipseClasspath , eclipseWtp
|
-
|
Generates all the eclipse configuration files |
cleanEclipse
|
cleanEclipseProject , cleanEclipseClasspath , cleanEclipseWtp
|
Delete
|
Removes all eclipse configuration files |
cleanEclipseProject
|
-
|
Delete
|
Removes the eclipse project file |
cleanEclipseClasspath
|
-
|
Delete
|
Removes the eclipse classpath file |
cleanEclipseWtp
|
-
|
Delete
|
Removes the eclipse .settings directory |
eclipseProject
|
-
|
EclipseProject
|
Generates the eclipse project file. |
eclipseClasspath
|
-
|
EclipseClasspath
|
Generates the Eclipse classpath file. |
eclipseWtp
|
-
|
EclipseWtp
|
Generates the org.eclipse.wst.common.component and
org.eclipse.wst.common.project.facet.core files. |
Table 28.2. EclipseProject task
Property | Type | Default Value | Description |
projectName
|
String |
project.name
|
The name of the Eclipse project. Must not be null. |
comment
|
String | null | 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 this Eclipse project. |
Table 28.3. EclipseClasspath task
Property | Type | Default Value | Description |
sourceSets
|
DomainObjectContainer |
sourceSets
|
The source sets which source directories should 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, which files are to be transformed into classpath entries. |
minusConfigurations
|
Set<Configuration> |
empty set
|
The configurations which files are to be excluded from the classpath entries. |
downloadSources
|
boolean | true | Whether to download sources for the external dependencies. |
downloadJavadoc
|
boolean | false | Whether to download javadoc for the external dependencies. |
variables
|
Map<String,String> |
[GRADLE_CACHE: <path to gradle cache>]
|
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 28.4. EclipseWtp task
Property | Type | Default Value | Description |
sourceSets
|
DomainObjectContainer |
sourceSets
|
The source sets which source directories should be added to the Eclipse classpath. |
deployName
|
String |
project.name
|
The deploy name to be used in the org.eclipse.wst.common.component file. |
plusConfigurations
|
Set<Configuration> |
[configurations.testRuntime]
|
The configurations, which files are to be transformed into classpath entries. |
minusConfigurations
|
Set<Configuration> |
[configurations.providedRuntime]
|
The configurations which files are to be excluded from the classpath entries. |
variables
|
Map<String,String> |
[GRADLE_CACHE: <path to gradle cache>]
|
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. |
facets
|
List<Facet> |
jst.java and jst.web facet |
The facets to be added as installed elements to the org.eclipse.wst.common.project.facet.core file. |
Table 28.5. Task Hooks
Method | EclipseProject Task Argument | EclipseClasspath Task Argument | EclipseWtp Task Argument | Description |
|
Project
|
Classpath
|
Wtp
|
Gets called directly after the domain objects have been populated with the content of the existing XML file (if there is one). |
|
Project
|
Classpath
|
Wtp
|
Gets called after the domain objects have been populated with the content of the existing XML file and the content from the build script. |
|
XmlProvider
|
XmlProvider
|
['org.eclipse.wst.common.component': groovy.util.Node, 'org.eclipse.wst.common.project.facet.core': groovy.util.Node]
|
The root node of the XML just before the XML is written to disk. |
All the tasks of the eclipse plugin provide the same hooks and behavior for customizing the generated content.
The tasks recognize existing eclipse files. If an eclipse project, classpath or wtp file does not exists, default values are used. Otherwise the existing ones are merged.
The first option to customize the Eclipse files is to have an existing Eclipse file before the tasks are run. Existing files will be merged together with the generated content. Any section of the existing Eclipse files that are not the target of generated content will neither be changed nor removed.
If you want Gradle to completely overwrite existing Eclipse files you can specify this on the command line by
executing something like gradle cleanEclipse eclipse
or gradle cleanEclipseClasspath eclipseClasspath
.
You can specify this also in the build script. Just make the generating tasks depending on the deleting tasks. You can tailor this
to your needs. You could make the eclipse
task dependent on the cleanEclipse
task. If you only want
to overwrite for example the classpath files you simply make the eclipseClasspath
task dependent on the
cleanEclipseClasspath
task.
The Eclipse plugin provides a couple of domain classes that model the Eclipse files. But only the sections that are autogenerated by Gradle. The generation lifecycle is the following. If there is an existing Eclipse file, its whole XML is parsed and stored in memory. Then the domain objects are populated with the relevant content of the the existing XML. After that the build script information is used to further populate those objects (e.g. add additional dependencies). Then all sections modelled by the domain objects are removed from the XML in memory. After that the domain objects are used to inject their content into the XML. Finally the XML is written to disk. The lifecycle provides hooks to modify the result according to your needs.
Doing a complete overwrite removes all your manual customizations.
This might be not what you want.
Therefore Gradle provides the option for a partial overwrite. You can hook into the phase just after the existing
Eclipse files have populated the domain objects. You could then for example remove all the dependencies
from the classpath
object.
Example 28.2. Partial Overwrite for Module
build.gradle
eclipseClasspath { beforeConfigured { classpath -> classpath.entries.removeAll { entry -> entry.kind == 'lib' || entry.kind == 'var' } } }
The generated XML will have all sections of the existing Eclipse classpath file,
except for the dependencies, where only the information of the build script is used. You could do something
similar for the project file.
Example 28.3. Partial Overwrite for Project
build.gradle
eclipseProject { beforeConfigured { project -> project.natures.clear() } }
You can also hook into the phase after the existing Eclipse files and the build script metadata have
populated the domain objects. You could then for example disable export of all the dependencies
of the module
object.
Example 28.4. Export Dependencies
build.gradle
eclipseClasspath {
whenConfigured { classpath ->
classpath.entries.findAll { entry -> entry.kind == 'lib' }*.exported = false
}
}
You can also hook into the phase after the XML DOM is fully populated but not written to disk. That hook provides total control over what is generated.
Example 28.5. Customizing the XML
build.gradle
eclipseWtp { withXml { xml -> xml.'org.eclipse.wst.commons.project.facet.core'.fixed.find { it.@facet == 'jst.java' }.@facet = 'jst2.java' } }