Package org.gradle.plugins.ide.idea.model

Class IdeaModule

  • public abstract class IdeaModule
extends java.lang.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. 

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

    • Method Detail

      • getName

        public java.lang.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​(java.lang.String name)

      • getSourceDirs

        public java.util.Set<java.io.File> getSourceDirs()
        The directories containing the production sources. For example see docs for IdeaModule

      • setSourceDirs

        public void setSourceDirs​(java.util.Set<java.io.File> sourceDirs)

      • getGeneratedSourceDirs

        public java.util.Set<java.io.File> getGeneratedSourceDirs()
        The directories containing the generated sources (both production and test sources).

        For example see docs for IdeaModule

      • setGeneratedSourceDirs

        public void setGeneratedSourceDirs​(java.util.Set<java.io.File> generatedSourceDirs)

      • getScopes

        public java.util.Map<java.lang.String,​java.util.Map<java.lang.String,​java.util.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: 

         plugins {
     id 'java'
     id 'idea'
 }

 configurations {
   performanceTestCompile
   performanceTestCompile.extendsFrom(testCompile)
 }

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

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

      • setScopes

        public void setScopes​(java.util.Map<java.lang.String,​java.util.Map<java.lang.String,​java.util.Collection<Configuration>>> scopes)

      • isDownloadSources

        public boolean isDownloadSources()
        Whether to download and add sources associated with the dependency jars. Defaults to true.

        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. Defaults to false.

        For example see docs for IdeaModule

      • setDownloadJavadoc

        public void setDownloadJavadoc​(boolean downloadJavadoc)

      • getContentRoot

        public java.io.File getContentRoot()
        The content root directory of the module.

        For example see docs for IdeaModule

      • setContentRoot

        public void setContentRoot​(java.io.File contentRoot)

      • getTestSourceDirs

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

      • setTestSourceDirs

        @Deprecated
public void setTestSourceDirs​(java.util.Set<java.io.File> testSourceDirs)
        Deprecated.
        This field is @Deprecated, please use getTestSources() instead to access the new collection property.

      • getTestSources

        public ConfigurableFileCollection getTestSources()
        The complete and up-to-date collection of test source directories This should be preferred to getTestSourceDirs() as it will include late changes to default directories.
        Returns:
        lazily configurable collection of test source directories
        Since:
        7.4

      • getResourceDirs

        public java.util.Set<java.io.File> getResourceDirs()
        The directories containing resources.

        For example see docs for IdeaModule

        Since:
        4.7

      • setResourceDirs

        public void setResourceDirs​(java.util.Set<java.io.File> resourceDirs)
        Sets the directories containing resources.

        For example see docs for IdeaModule

        Since:
        4.7

      • getTestResourceDirs

        @Deprecated
public java.util.Set<java.io.File> getTestResourceDirs()
        Deprecated.
        The directories containing the test resources.

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

        Since:
        4.7

      • setTestResourceDirs

        @Deprecated
public void setTestResourceDirs​(java.util.Set<java.io.File> testResourceDirs)
        Deprecated.
        Sets the directories containing the test resources.

        For example see docs for IdeaModule This field is @Deprecated, please use getTestResources() instead to access the new collection property.

        Since:
        4.7

      • getTestResources

        public ConfigurableFileCollection getTestResources()
        The complete and up-to-date collection of test resource directories. This should be preferred to getTestResourceDirs() as it will include late changes to default directories.
        Returns:
        lazily configurable collection of test resource directories
        Since:
        7.4

      • getExcludeDirs

        public java.util.Set<java.io.File> getExcludeDirs()
        Directories to be excluded.

        For example see docs for IdeaModule

      • setExcludeDirs

        public void setExcludeDirs​(java.util.Set<java.io.File> excludeDirs)

      • getInheritOutputDirs

        public java.lang.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​(java.lang.Boolean inheritOutputDirs)

      • getOutputDir

        public java.io.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​(java.io.File outputDir)

      • getTestOutputDir

        public java.io.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​(java.io.File testOutputDir)

      • getPathVariables

        public java.util.Map<java.lang.String,​java.io.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​(java.util.Map<java.lang.String,​java.io.File> pathVariables)

      • getJdkName

        public java.lang.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​(java.lang.String jdkName)

      • getLanguageLevel

        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

        public void setLanguageLevel​(IdeaLanguageLevel languageLevel)

      • getTargetBytecodeVersion

        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

        public void setTargetBytecodeVersion​(JavaVersion targetBytecodeVersion)

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

      • 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 java.util.Map<java.lang.String,​java.lang.Iterable<java.io.File>> getSingleEntryLibraries()

      • setSingleEntryLibraries

        public void setSingleEntryLibraries​(java.util.Map<java.lang.String,​java.lang.Iterable<java.io.File>> singleEntryLibraries)

      • iml

        public void iml​(@DelegatesTo(IdeaModuleIml.class)
                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 java.io.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​(java.io.File newOutputFile)

      • resolveDependencies

        public java.util.Set<Dependency> resolveDependencies()
        Resolves and returns the module's dependencies.
        Returns:
        dependencies

      • mergeXmlModule

        public void mergeXmlModule​(Module xmlModule)