IdeaModule

Table of Contents

Properties
Methods
Script blocks
Property details
Method details
Script block details
API Documentation:IdeaModule

Enables fine-tuning module details (*.iml file) of the IDEA plugin.

Example of use with a blend of most possible properties. Typically you don't have to configure this model directly because Gradle configures it for you. 

plugins {
    id 'java'
    id 'idea'
}

//for the sake of this example, let's introduce a 'performanceTestCompile' configuration
configurations {
  performanceTestCompile
  performanceTestCompile.extendsFrom(testCompile)
}

dependencies {
  //performanceTestCompile "some.interesting:dependency:1.0"
}

idea {

  //if you want parts of paths in resulting files (*.iml, etc.) to be replaced by variables (Files)
  pathVariables GRADLE_HOME: file('~/cool-software/gradle')

  module {
    //if for some reason you want to add an extra sourceDirs
    sourceDirs += file('some-extra-source-folder')

    //and some extra test source dirs
    testSources.from(file('some-extra-test-dir'))

    //and some extra resource dirs
    resourceDirs += file('some-extra-resource-dir')

    //and some extra test resource dirs
    testResources.from(file('some-extra-test-resource-dir'))

    //and hint to mark some of existing source dirs as generated sources
    generatedSourceDirs += file('some-extra-source-folder')

    //and some extra dirs that should be excluded by IDEA
    excludeDirs += file('some-extra-exclude-dir')

    //if you don't like the name Gradle has chosen
    name = 'some-better-name'

    //if you prefer different output folders
    inheritOutputDirs = false
    outputDir = file('muchBetterOutputDir')
    testOutputDir = file('muchBetterTestOutputDir')

    //if you prefer different SDK than the one inherited from IDEA project
    jdkName = '1.6'

    //put our custom test dependencies onto IDEA's TEST scope
    scopes.TEST.plus += [ configurations.performanceTestCompile ]

    //if 'content root' (as IDEA calls it) of the module is different
    contentRoot = file('my-module-content-root')

    //if you love browsing Javadoc
    downloadJavadoc = true

    //and hate reading sources :)
    downloadSources = false
  }
}

For tackling edge cases, users can perform advanced configuration on the resulting XML file. It is also possible to affect the way the IDEA plugin merges the existing configuration via beforeMerged and whenMerged closures.

beforeMerged and whenMerged closures receive a Module parameter

Examples of advanced configuration: 

plugins {
    id 'java'
    id 'idea'
}

idea {
  module {
    iml {
      //if you like to keep *.iml in a secret folder
      generateTo = file('secret-modules-folder')

      //if you want to mess with the resulting XML in whatever way you fancy
      withXml {
        def node = it.asNode()
        node.appendNode('iLoveGradle', 'true')
        node.appendNode('butAlso', 'I find increasing pleasure tinkering with output *.iml contents. Yeah!!!')
      }

      //closure executed after *.iml content is loaded from existing file
      //but before gradle build information is merged
      beforeMerged { module ->
        //if you want skip merging exclude dirs
        module.excludeFolders.clear()
      }

      //closure executed after *.iml content is loaded from existing file
      //and after gradle build information is merged
      whenMerged { module ->
        //you can tinker with Module
      }
    }
  }
}

Properties

PropertyDescription
contentRoot

The content root directory of the module.

downloadJavadoc

Whether to download and add javadoc associated with the dependency jars. Defaults to false.

downloadSources

Whether to download and add sources associated with the dependency jars. Defaults to true.

excludeDirs

Directories to be excluded.

generatedSourceDirs

The directories containing the generated sources (both production and test sources).

iml

See IdeaModule.iml(org.gradle.api.Action)

inheritOutputDirs

If true, output directories for this module will be located below the output directory for the project; otherwise, they will be set to the directories specified by IdeaModule.getOutputDir() and IdeaModule.getTestOutputDir().

jdkName

The JDK to use for this module. If null, the value of the existing or default ipr XML (inherited) is used. If it is set to inherited, the project SDK is used. Otherwise the SDK for the corresponding value of java version is used for this module.

languageLevel

The module specific language Level to use for this module. When null, the module will inherit the language level from the idea project.

name

Configures module name, that is the name of the *.iml file.

outputDir

The output directory for production classes. If null, no entry will be created.

outputFile

Configures output *.iml file. It's optional because the task should configure it correctly for you (including making sure it is unique in the multi-module build). If you really need to change the output file name (or the module name) it is much easier to do it via the moduleName property!

resourceDirs

The directories containing resources.

scopes

The keys of this map are the IDEA scopes. Each key points to another map that has two keys, plus and minus. The values of those keys are collections of Configuration objects. The files of the plus configurations are added minus the files from the minus configurations. See example below...

sourceDirs

The directories containing the production sources. For example see docs for IdeaModule

targetBytecodeVersion

The module specific bytecode version to use for this module. When null, the module will inherit the bytecode version from the idea project.

testOutputDir

The output directory for test classes. If null, no entry will be created.

testResourceDirs
Deprecated

The directories containing the test resources.

testResources

The complete and up-to-date collection of test resource directories. This should be preferred to IdeaModule.getTestResourceDirs() as it will include late changes to default directories.

testSourceDirs
Deprecated

The directories containing the test sources. Note that late changes to default test directories may NOT be reflected in this collection and IdeaModule.getTestSources() should be preferred. For example see docs for IdeaModule This field is @Deprecated, please use IdeaModule.getTestSources() instead.

testSources

The complete and up-to-date collection of test source directories This should be preferred to IdeaModule.getTestSourceDirs() as it will include late changes to default directories.

Methods

MethodDescription
iml(action)

Enables advanced configuration like tinkering with the output XML or affecting the way existing *.iml content is merged with gradle build information.

Script blocks

BlockDescription
iml

Enables advanced configuration like tinkering with the output XML or affecting the way existing *.iml content is merged with gradle build information.

Property details

File contentRoot

The content root directory of the module.

For example see docs for IdeaModule

Default with idea plugin:
project.projectDir

boolean downloadJavadoc

Whether to download and add javadoc associated with the dependency jars. Defaults to false.

For example see docs for IdeaModule

Default with idea plugin:
false

boolean downloadSources

Whether to download and add sources associated with the dependency jars. Defaults to true.

For example see docs for IdeaModule

Default with idea plugin:
true

Set<File> excludeDirs

Directories to be excluded.

For example see docs for IdeaModule

Default with idea plugin:
[project.layout.buildDirectory, project.file('.gradle')]

Set<File> generatedSourceDirs

The directories containing the generated sources (both production and test sources).

For example see docs for IdeaModule

Default with idea plugin:
[]

IdeaModuleIml iml (read-only)

See IdeaModule.iml(org.gradle.api.Action)

Boolean inheritOutputDirs

If true, output directories for this module will be located below the output directory for the project; otherwise, they will be set to the directories specified by IdeaModule.getOutputDir() and IdeaModule.getTestOutputDir().

For example see docs for IdeaModule

Default with idea plugin:
null
Default with idea and java plugin:
null

String jdkName

The JDK to use for this module. If null, the value of the existing or default ipr XML (inherited) is used. If it is set to inherited, the project SDK is used. Otherwise the SDK for the corresponding value of java version is used for this module.

For example see docs for IdeaModule

Default with idea plugin:
'inherited'

IdeaLanguageLevel languageLevel

The module specific language Level to use for this module. When null, the module will inherit the language level from the idea project.

The Idea module language level is based on the sourceCompatibility settings for the associated Gradle project.

Default with idea and java plugin:
project.sourceCompatibility

String name

Configures module name, that is the name of the *.iml file.

It's optional because the task should configure it correctly for you. By default it will try to use the project.name or prefix it with a part of a project.path to make sure the module name is unique in the scope of a multi-module build. The 'uniqueness' of a module name is required for correct import into IDEA and the task will make sure the name is unique.

since 1.0-milestone-2

If your project has problems with unique names it is recommended to always run gradle idea from the root, i.e. for all subprojects. If you run the generation of the IDEA module only for a single subproject then you may have different results because the unique names are calculated based on IDEA modules that are involved in the specific build run.

If you update the module names then make sure you run gradle idea from the root, e.g. for all subprojects, including generation of IDEA project. The reason is that there may be subprojects that depend on the subproject with amended module name. So you want them to be generated as well because the module dependencies need to refer to the amended project name. Basically, for non-trivial projects it is recommended to always run gradle idea from the root.

For example see docs for IdeaModule

Default with idea plugin:
${project.name} (sometimes prefixed with parts of ${project.path} to guarantee uniqueness)

File outputDir

The output directory for production classes. If null, no entry will be created.

For example see docs for IdeaModule

Default with idea plugin:
null
Default with idea and java plugin:
null

File outputFile

Configures output *.iml file. It's optional because the task should configure it correctly for you (including making sure it is unique in the multi-module build). If you really need to change the output file name (or the module name) it is much easier to do it via the moduleName property!

Please refer to documentation on moduleName property. In IntelliJ IDEA the module name is the same as the name of the *.iml file.

Default with idea plugin:
#name + '.iml'

Set<File> resourceDirs

The directories containing resources.

For example see docs for IdeaModule

Default with idea plugin:
[]
Default with idea and java plugin:
resource dirs from project.sourceSets.main.resources

The keys of this map are the IDEA scopes. Each key points to another map that has two keys, plus and minus. The values of those keys are collections of Configuration objects. The files of the plus configurations are added minus the files from the minus configurations. See example below...

Example how to use scopes property to enable 'performanceTestCompile' dependencies in the output *.iml file: 

plugins {
    id 'java'
    id 'idea'
}

configurations {
  performanceTestCompile
  performanceTestCompile.extendsFrom(testCompile)
}

dependencies {
  //performanceTestCompile "some.interesting:dependency:1.0"
}

idea {
  module {
    scopes.TEST.plus += [ configurations.performanceTestCompile ]
  }
}
Default with idea plugin:
[:]
Default with idea and java plugin:
  • COMPILE -> project.configurations.compileClasspath
  • RUNTIME -> project.configurations.runtimeClasspath - project.configurations.compileClasspath
  • TEST -> project.configurations.testRuntimeClasspath - project.configurations.runtimeClasspath
  • PROVIDED

Set<File> sourceDirs

The directories containing the production sources. For example see docs for IdeaModule

Default with idea plugin:
[]
Default with idea and java plugin:
project.sourceSets.main.allJava

JavaVersion targetBytecodeVersion

The module specific bytecode version to use for this module. When null, the module will inherit the bytecode version from the idea project.

The Idea module bytecode version is based on the targetCompatibility settings for the associated Gradle project.

Default with idea and java plugin:
project.targetCompatibility

File testOutputDir

The output directory for test classes. If null, no entry will be created.

For example see docs for IdeaModule

Default with idea plugin:
null
Default with idea and java plugin:
null

Set<File> testResourceDirs

Note: This property is deprecated and will be removed in the next major version of Gradle.

The directories containing the test resources.

For example see docs for IdeaModule This field is @Deprecated, please use IdeaModule.getTestResources() instead.

Default with idea plugin:
[]
Default with idea and java plugin:
resource dirs from project.sourceSets.test.resources

ConfigurableFileCollection testResources (read-only)

The complete and up-to-date collection of test resource directories. This should be preferred to IdeaModule.getTestResourceDirs() as it will include late changes to default directories.

Default with idea plugin:
[]
Default with idea and java plugin:
Based on resources in available test suites

Set<File> testSourceDirs

Note: This property is deprecated and will be removed in the next major version of Gradle.

The directories containing the test sources. Note that late changes to default test directories may NOT be reflected in this collection and IdeaModule.getTestSources() should be preferred. For example see docs for IdeaModule This field is @Deprecated, please use IdeaModule.getTestSources() instead.

Default with idea plugin:
[]
Default with idea and java plugin:
project.sourceSets.test.allJava

ConfigurableFileCollection testSources (read-only)

The complete and up-to-date collection of test source directories This should be preferred to IdeaModule.getTestSourceDirs() as it will include late changes to default directories.

Default with idea plugin:
[]
Default with idea and java plugin:
Based on source directories in available test suites

Method details

void iml(Action<? super IdeaModuleIml> action)

Enables advanced configuration like tinkering with the output XML or affecting the way existing *.iml content is merged with gradle build information.

For example see docs for IdeaModule.

Script block details

iml { }

Enables advanced configuration like tinkering with the output XML or affecting the way existing *.iml content is merged with gradle build information.

For example see docs for IdeaModule.

Delegates to:
IdeaModuleIml from iml