# IdeaModule

API Documentation: | `IdeaModule`

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

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

    apply plugin: 'java'
    apply plugin: 'idea'

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

    dependencies {
      //provided "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
        testSourceDirs += file('some-extra-test-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 that inherited from IDEA project
        jdkName = '1.6'

        //if you need to put 'provided' dependencies on the classpath
        scopes.PROVIDED.plus += [ configurations.provided ]

        //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 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 `Module` object

Examples of advanced configuration:

    apply plugin: 'java'
    apply plugin: '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

Property | Description
`contentRoot` | The content root directory of the module.
`downloadJavadoc` | Whether to download and add javadoc associated with the dependency jars.
`downloadSources` | Whether to download and add sources associated with the dependency jars.
`excludeDirs` | `ConventionProperty` for the directories to be excluded.
`iml` | See `IdeaModule.iml{}`
`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 #outputDir and #testOutputDir.
`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
`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!
`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.
`testOutputDir` | The output directory for test classes. If `null`, no entry will be created.
`testSourceDirs` | The directories containing the test sources.

### Methods

No methods

### Script blocks

Block | Description
`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.

For example see docs for `IdeaModule`

Default with `idea` plugin:
  `false`

#### `boolean` `downloadSources`

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

For example see docs for `IdeaModule`

Default with `idea` plugin:
  `true`

#### ``Set`<`File`>` `excludeDirs`

`ConventionProperty` for the directories to be excluded.

For example see docs for `IdeaModule`

Default with `idea` plugin:
  `[project.buildDir, project.file('.gradle')]`

#### `IdeaModuleIml` `iml` (read-only)

See `IdeaModule.iml{}`

#### `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 #outputDir and #testOutputDir.

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

#### `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 uniqeness)`

#### `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'`

#### ``Map`<`String`, `Map`<`String`, `Collection`<`Configuration`>>>` `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...

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

    apply plugin: 'java'
    apply plugin: 'idea'

    configurations {
      provided
      provided.extendsFrom(compile)
    }

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

    idea {
      module {
        scopes.PROVIDED.plus += [ configurations.provided ]
      }
    }

Default with `idea` plugin:
  `[:]`
Default with `idea` and `java` plugin:
  - `COMPILE` -> `project.configurations.compile`
  - `RUNTIME` -> `project.configurations.runtime - project.configurations.compile`
  - `TEST` -> `project.configurations.testRuntime - project.configurations.runtime`
  - `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:
  source dirs from `project.sourceSets.main.allSource`

#### `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`>` `testSourceDirs`

The directories containing the test sources.

For example see docs for `IdeaModule`

Default with `idea` plugin:
  `[]`
Default with `idea` and `java` plugin:
  source dirs from `project.sourceSets.test.allSource`

### 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`