Chapter 67. The IDEA Plugin

Table of Contents

67.1. Usage
67.2. Tasks
67.3. Configuration
67.4. Customizing the generated files
67.5. Further things to consider

The IDEA plugin generates files that are used by IntelliJ IDEA, thus making it possible to open the project from IDEA (File - Open Project). Both external dependencies (including associated source and Javadoc files) and project dependencies are considered.

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

Table 67.1. IDEA plugin behavior

Plugin Description

None

Generates an IDEA module file. Also generates an IDEA project and workspace file if the project is the root project.

Java

Adds Java configuration to the module and project files.

One focus of the IDEA plugin is to be open to customization. The plugin provides a standardized set of hooks for adding and removing content from the generated files.

67.1. Usage

To use the IDEA plugin, include this in your build script:

Example 67.1. Using the IDEA plugin

build.gradle

apply plugin: 'idea'

The IDEA plugin adds a number of tasks to your project. The main tasks that you will use are the idea and cleanIdea tasks.

67.2. Tasks

The IDEA plugin adds the tasks shown below to a project. Notice that the clean task does not depend on the cleanIdeaWorkspace task. This is because the workspace typically contains a lot of user specific temporary data and it is not desirable to manipulate it outside IDEA.

Table 67.2. IDEA plugin - Tasks

Task name Depends on Type Description

idea

ideaProject, ideaModule, ideaWorkspace

-

Generates all IDEA configuration files

cleanIdea

cleanIdeaProject, cleanIdeaModule

Delete

Removes all IDEA configuration files

cleanIdeaProject

-

Delete

Removes the IDEA project file

cleanIdeaModule

-

Delete

Removes the IDEA module file

cleanIdeaWorkspace

-

Delete

Removes the IDEA workspace file

ideaProject

-

GenerateIdeaProject

Generates the .ipr file. This task is only added to the root project.

ideaModule

-

GenerateIdeaModule

Generates the .iml file

ideaWorkspace

-

GenerateIdeaWorkspace

Generates the .iws file. This task is only added to the root project.

67.3. Configuration

Table 67.3. Configuration of the idea plugin

Model Reference name Description

IdeaModel

idea

Top level element that enables configuration of the idea plugin in a DSL-friendly fashion

IdeaProject

idea.project

Allows configuring project information

IdeaModule

idea.module

Allows configuring module information

IdeaWorkspace

idea.workspace

Allows configuring the workspace XML

67.4. Customizing the generated files

The IDEA plugin provides hooks and behavior for customizing the generated content. The workspace file can effectively only be manipulated via the withXml hook because its corresponding domain object is essentially empty.

The tasks recognize existing IDEA files, and merge them with the generated content.

67.4.1. Merging

Sections of existing IDEA 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.

Disabling merging with a complete overwrite

To completely rewrite existing IDEA files, execute a clean task together with its corresponding generation task, like “gradle cleanIdea idea” (in that order). If you want to make this the default behavior, add “tasks.idea.dependsOn(cleanIdea)” 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 plugin would generate. For instance, this can be done for the “.iml” file with “gradle cleanIdeaModule ideaModule”.

67.4.2. Hooking into the generation lifecycle

The plugin provides objects modeling the sections of the metadata 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 model types:

Table 67.4. Idea plugin hooks

Model beforeMerged { arg → } argument type whenMerged { arg → } argument type withXml { arg → } argument type

IdeaProject

Project

Project

XmlProvider

IdeaModule

Module

Module

XmlProvider

IdeaWorkspace

Workspace

Workspace

XmlProvider

Partial rewrite of existing content

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

Example 67.2. Partial Rewrite for Module

build.gradle

idea.module.iml {
    beforeMerged { module ->
        module.dependencies.clear()
    }
}

The resulting module 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 module file will be either left as-is or merged. The same could be done for the module paths in the project file:

Example 67.3. Partial Rewrite for Project

build.gradle

idea.project.ipr {
    beforeMerged { project ->
        project.modulePaths.clear()
    }
}

Modifying the fully populated domain objects

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

Example 67.4. Export Dependencies

build.gradle

idea.module.iml {
    whenMerged { module ->
        module.dependencies*.exported = true
    }
}

Modifying the XML representation

The withXml hook allows you 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 67.5. Customizing the XML

build.gradle

idea.project.ipr {
    withXml { provider ->
        provider.node.component
                .find { it.@name == 'VcsDirectoryMappings' }
                .mapping.@vcs = 'Git'
    }
}

67.5. Further things to consider

The paths of dependencies in the generated IDEA files are absolute. If you manually define a path variable pointing to the Gradle dependency cache, IDEA will automatically replace the absolute dependency paths with this path variable. you can configure this path variable via the “idea.pathVariables” property, so that it can do a proper merge without creating duplicates.