IdeaModule (Gradle API 4.8)
Date: 2018-06-04

org.gradle.plugins.ide.idea.model

## Class IdeaModule

- java.lang.Object
- - org.gradle.plugins.ide.idea.model.IdeaModule

-     public class IdeaModule
      extends Object

  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.

       apply plugin: 'java'
       apply plugin: '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
           testSourceDirs += file('some-extra-test-dir')

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

           //and some extra test resource dirs
           testResourceDirs += 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:

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

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `IdeaModule(Project project, IdeaModuleIml iml)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `File` | `getContentRoot()` The content root directory of the module.
    `Set<File>` | `getExcludeDirs()` Directories to be excluded.
    `Set<File>` | `getGeneratedSourceDirs()` The directories containing the generated sources (both production and test sources).
    `IdeaModuleIml` | `getIml()` See `iml(Action)`
    `Boolean` | `getInheritOutputDirs()` 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 `getOutputDir()` and `getTestOutputDir()`.
    `String` | `getJdkName()` The JDK to use for this module.
    `IdeaLanguageLevel` | `getLanguageLevel()` The module specific language Level to use for this module.
    `String` | `getName()` Configures module name, that is the name of the *.iml file.
    `File` | `getOutputDir()` The output directory for production classes.
    `File` | `getOutputFile()` Configures output *.iml file.
    `PathFactory` | `getPathFactory()`
    `Map<String,File>` | `getPathVariables()` The variables to be used for replacing absolute paths in the iml entries.
    `Project` | `getProject()` An owner of this IDEA module.
    `Set<File>` | `getResourceDirs()` The directories containing resources.
    `ScalaPlatform` | `getScalaPlatform()` The Scala version used by this module.
    `Map<String,Map<String,Collection<Configuration>>>` | `getScopes()` The keys of this map are the IDEA scopes.
    `Map<String,Iterable<File>>` | `getSingleEntryLibraries()`
    `Set<File>` | `getSourceDirs()` The directories containing the production sources.
    `JavaVersion` | `getTargetBytecodeVersion()` The module specific bytecode version to use for this module.
    `File` | `getTestOutputDir()` The output directory for test classes.
    `Set<File>` | `getTestResourceDirs()` The directories containing the test resources.
    `Set<File>` | `getTestSourceDirs()` The directories containing the test sources.
    `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.
    `void` | `iml(Closure closure)` Enables advanced configuration like tinkering with the output XML or affecting the way existing *.iml content is merged with gradle build information.
    `boolean` | `isDownloadJavadoc()` Whether to download and add javadoc associated with the dependency jars.
    `boolean` | `isDownloadSources()` Whether to download and add sources associated with the dependency jars.
    `boolean` | `isOffline()` If true then external artifacts (e.g.
    `void` | `mergeXmlModule(Module xmlModule)`
    `Set<Dependency>` | `resolveDependencies()` Resolves and returns the module's dependencies.
    `void` | `setContentRoot(File contentRoot)`
    `void` | `setDownloadJavadoc(boolean downloadJavadoc)`
    `void` | `setDownloadSources(boolean downloadSources)`
    `void` | `setExcludeDirs(Set<File> excludeDirs)`
    `void` | `setGeneratedSourceDirs(Set<File> generatedSourceDirs)`
    `void` | `setInheritOutputDirs(Boolean inheritOutputDirs)`
    `void` | `setJdkName(String jdkName)`
    `void` | `setLanguageLevel(IdeaLanguageLevel languageLevel)`
    `void` | `setName(String name)`
    `void` | `setOffline(boolean offline)`
    `void` | `setOutputDir(File outputDir)`
    `void` | `setOutputFile(File newOutputFile)`
    `void` | `setPathFactory(PathFactory pathFactory)`
    `void` | `setPathVariables(Map<String,File> pathVariables)`
    `void` | `setResourceDirs(Set<File> resourceDirs)` Sets the directories containing resources.
    `void` | `setScalaPlatform(ScalaPlatform scalaPlatform)`
    `void` | `setScopes(Map<String,Map<String,Collection<Configuration>>> scopes)`
    `void` | `setSingleEntryLibraries(Map<String,Iterable<File>> singleEntryLibraries)`
    `void` | `setSourceDirs(Set<File> sourceDirs)`
    `void` | `setTargetBytecodeVersion(JavaVersion targetBytecodeVersion)`
    `void` | `setTestOutputDir(File testOutputDir)`
    `void` | `setTestResourceDirs(Set<File> testResourceDirs)` Sets the directories containing the test resources.
    `void` | `setTestSourceDirs(Set<File> testSourceDirs)`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### IdeaModule

          public IdeaModule(Project project,
                            IdeaModuleIml iml)

  - ### Method Detail

    - #### getName

          public String getName()

      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`

    - #### setName

          public void setName(String name)

    - #### getSourceDirs

          public Set<File> getSourceDirs()

      The directories containing the production sources.

      For backward-compatibility it is set of directories containing the production sources from `project.sourceSets.main.allSource`.

      Starting with Gradle 5.0 it is set of directories containing the production sources from `project.sourceSets.main.allJava`. For example see docs for `IdeaModule`

    - #### setSourceDirs

          public void setSourceDirs(Set<File> sourceDirs)

    - #### getGeneratedSourceDirs

          @Incubating
          public Set<File> getGeneratedSourceDirs()

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

      For example see docs for `IdeaModule`

    - #### setGeneratedSourceDirs

          @Incubating
          public void setGeneratedSourceDirs(Set<File> generatedSourceDirs)

    - #### getScopes

          public Map<String,Map<String,Collection<Configuration>>> getScopes()

      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:

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

           configurations {
             performanceTestCompile
             performanceTestCompile.extendsFrom(testCompile)
           }

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

           idea {
             module {
               scopes.TEST.plus += [ configurations.performanceTestCompile ]
             }
           }

    - #### setScopes

          public void setScopes(Map<String,Map<String,Collection<Configuration>>> scopes)

    - #### isDownloadSources

          public boolean isDownloadSources()

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

      For example see docs for `IdeaModule`

    - #### setDownloadSources

          public void setDownloadSources(boolean downloadSources)

    - #### isDownloadJavadoc

          public boolean isDownloadJavadoc()

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

      For example see docs for `IdeaModule`

    - #### setDownloadJavadoc

          public void setDownloadJavadoc(boolean downloadJavadoc)

    - #### getContentRoot

          public File getContentRoot()

      The content root directory of the module.

      For example see docs for `IdeaModule`

    - #### setContentRoot

          public void setContentRoot(File contentRoot)

    - #### getTestSourceDirs

          public Set<File> getTestSourceDirs()

      The directories containing the test sources.

      For backward-compatibility it is set of directories containing the test sources from `project.sourceSets.test.allSource`.

      Starting with Gradle 5.0 it is set of directories containing the test sources from `project.sourceSets.test.allJava`. For example see docs for `IdeaModule`

    - #### setTestSourceDirs

          public void setTestSourceDirs(Set<File> testSourceDirs)

    - #### getResourceDirs

          @Incubating
          public Set<File> getResourceDirs()

      The directories containing resources.

      For example see docs for `IdeaModule`

      Since:
        4.7

    - #### setResourceDirs

          @Incubating
          public void setResourceDirs(Set<File> resourceDirs)

      Sets the directories containing resources.

      For example see docs for `IdeaModule`

      Since:
        4.7

    - #### getTestResourceDirs

          @Incubating
          public Set<File> getTestResourceDirs()

      The directories containing the test resources.

      For example see docs for `IdeaModule`

      Since:
        4.7

    - #### setTestResourceDirs

          @Incubating
          public void setTestResourceDirs(Set<File> testResourceDirs)

      Sets the directories containing the test resources.

      For example see docs for `IdeaModule`

      Since:
        4.7

    - #### getExcludeDirs

          public Set<File> getExcludeDirs()

      Directories to be excluded.

      For example see docs for `IdeaModule`

    - #### setExcludeDirs

          public void setExcludeDirs(Set<File> excludeDirs)

    - #### getInheritOutputDirs

          public Boolean getInheritOutputDirs()

      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 `getOutputDir()` and `getTestOutputDir()`.

      For example see docs for `IdeaModule`

    - #### setInheritOutputDirs

          public void setInheritOutputDirs(Boolean inheritOutputDirs)

    - #### getOutputDir

          public File getOutputDir()

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

      For example see docs for `IdeaModule`

    - #### setOutputDir

          public void setOutputDir(File outputDir)

    - #### getTestOutputDir

          public File getTestOutputDir()

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

      For example see docs for `IdeaModule`

    - #### setTestOutputDir

          public void setTestOutputDir(File testOutputDir)

    - #### getPathVariables

          public Map<String,File> getPathVariables()

      The variables to be used for replacing absolute paths in the iml entries. For example, you might add a `GRADLE_USER_HOME` variable to point to the Gradle user home dir.

      For example see docs for `IdeaModule`

    - #### setPathVariables

          public void setPathVariables(Map<String,File> pathVariables)

    - #### getJdkName

          public String getJdkName()

      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`

    - #### setJdkName

          public void setJdkName(String jdkName)

    - #### getLanguageLevel

          @Incubating
          public IdeaLanguageLevel getLanguageLevel()

      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.

    - #### setLanguageLevel

          @Incubating
          public void setLanguageLevel(IdeaLanguageLevel languageLevel)

    - #### getTargetBytecodeVersion

          @Incubating
          public JavaVersion getTargetBytecodeVersion()

      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.

    - #### setTargetBytecodeVersion

          @Incubating
          public void setTargetBytecodeVersion(JavaVersion targetBytecodeVersion)

    - #### getScalaPlatform

          @Incubating
          public ScalaPlatform getScalaPlatform()

      The Scala version used by this module.

    - #### setScalaPlatform

          @Incubating
          public void setScalaPlatform(ScalaPlatform scalaPlatform)

    - #### getIml

          public IdeaModuleIml getIml()

      See `iml(Action)`

    - #### getProject

          public Project getProject()

      An owner of this IDEA module.

      If IdeaModule requires some information from gradle this field should not be used for this purpose. IdeaModule instances should be configured with all necessary information by the plugin or user.

    - #### getPathFactory

          public PathFactory getPathFactory()

    - #### setPathFactory

          public void setPathFactory(PathFactory pathFactory)

    - #### isOffline

          public boolean isOffline()

      If true then external artifacts (e.g. those found in repositories) will not be included in the resulting classpath (only project and local file dependencies will be included).

    - #### setOffline

          public void setOffline(boolean offline)

    - #### getSingleEntryLibraries

          public Map<String,Iterable<File>> getSingleEntryLibraries()

    - #### setSingleEntryLibraries

          public void setSingleEntryLibraries(Map<String,Iterable<File>> singleEntryLibraries)

    - #### iml

          public void iml(Closure closure)

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

    - #### iml

          public 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`.

      Since:
        3.5

    - #### getOutputFile

          public File getOutputFile()

      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.

    - #### setOutputFile

          public void setOutputFile(File newOutputFile)

    - #### resolveDependencies

          public Set<Dependency> resolveDependencies()

      Resolves and returns the module's dependencies.
      Returns:
        dependencies

    - #### mergeXmlModule

          public void mergeXmlModule(Module xmlModule)