# Chapter 28. The Eclipse Plugin

The Eclipse plugin generates files that are used by Eclipse IDE, thus making it possible to import the project into Eclipse (File - Import... - Existing Projects into Workspace). 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.

## 28.1. Usage

To use the Eclipse plugin, include in your build script:

Example 28.1. Using the Eclipse plugin

`build.gradle`

    apply plugin: 'eclipse'

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).

## 28.2. Tasks

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
``beforeConfigured { arg -> }`` | `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).
``whenConfigured { arg -> }`` | `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.
``withXml { arg -> }`` | `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.

## 28.3. Customizing the generated files

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.

### 28.3.1. Merging

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.

#### 28.3.1.1. Disabling merging with a complete overwrite

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.

### 28.3.2. Hooking into the generation lifecycle

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.

#### 28.3.2.1. Partial Overwrite

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()
        }
    }

#### 28.3.2.2. Modifying the fully populated domain objects

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
        }
    }

#### 28.3.2.3. Modifying the XML

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'
        }
    }