【idea实用系列7】Gradle构建项目中IDEA插件

【idea实用系列7】Gradle构建项目中IDEA插件

使用

要使用IDEA插件，请在构建脚本中包含以下内容：

plugins {
    id 'idea'
}

IDEA插件会为项目添加一些任务。idea任务为项目生成一个IDEA模块文件。当项目是根项目时，idea任务还会生成一个IDEA项目和工作空间。IDEA项目包括Gradle构建中每个项目的模块。

当项目是根项目时，IDEA插件还会添加一个openIdea任务。此任务生成IDEA配置文件并在IDEA中打开结果。这意味着您只需从根项目运行./gradlew openIdea即可方便地生成并打开IDEA项目。

IDEA插件还为项目添加了**cleanIdea任务**。该任务将删除已生成的文件（如果存在）。

任务

IDEA插件向项目添加了以下任务。请注意，clean任务不依赖于cleanIdeaWorkspace任务。这是因为工作空间通常包含许多用户特定的临时数据，并且不希望在IDEA之外对其进行操作。

• idea：依赖：ideaProject、ideaModule、ideaWorkspace。生成所有IDEA配置文件。
• openIdea：依赖：idea。生成所有IDEA配置文件并在IDEA中打开项目。
• cleanIdea：依赖：cleanIdeaProject、cleanIdeaModule。删除所有IDEA配置文件。
• cleanIdeaProject：删除IDEA项目文件。
• cleanIdeaModule：删除IDEA模块文件。
• cleanIdeaWorkspace：删除IDEA工作空间文件。
• ideaProject：生成.ipr文件。仅添加到根项目。
• ideaModule：生成.iml文件。
• ideaWorkspace：生成.iws文件。仅添加到根项目。

配置

该插件添加了一些配置选项，可以自定义生成的IDEA项目和模块文件。这些配置选项既可以是模型属性，也可以是直接修改生成文件的较低级别机制。例如，您可以添加源目录和资源目录，以及注入自己的XML片段。前一种类型的配置会受到IDEA导入功能的支持，而后者则不受支持。

以下是您可以使用的配置属性：

• idea：IdeaModel。顶级元素，用于以DSL友好的方式配置IDEA插件。
• idea.project：IdeaProject。允许配置项目信息。
• idea.module：IdeaModule。允许配置模块信息。
• idea.workspace：IdeaWorkspace。允许配置工作区XML。

请点击类型链接查看如何使用这些配置属性的示例。

自定义生成的文件

IDEA插件提供了钩子和行为，以更加灵活和详细地自定义生成的内容。此外，withXml钩子是修改工作空间文件的唯一实际方法。

这一节讨论的技术与IDEA的导入功能不兼容

任务会识别现有的IDEA文件，并将它们与生成的内容合并。

合并

现有IDEA文件中与生成内容目标相同的部分将被修改或覆盖，具体取决于特定部分。其余部分将保持不变。

禁用合并并进行完全覆盖

要完全重写现有的IDEA文件，请执行带有相应生成任务的clean任务，例如"gradle cleanIdea idea"（按照顺序执行）。如果要使此成为默认行为，请在构建脚本中添加"tasks.idea.dependsOn(cleanIdea)"。这样就不需要显式执行clean任务了。

也可以对插件将生成的个别文件使用此策略。例如，可以通过"gradle cleanIdeaModule ideaModule"来完成".iml"文件的操作。

钩入生成生命周期

该插件提供了用于表示Gradle生成的元数据文件部分的对象模型。生成生命周期如下：

1. 读取文件；如果文件不存在，则使用Gradle提供的默认版本。
2. 执行beforeMerged钩子，使用表示现有文件的领域对象。
3. 将现有内容与从Gradle构建中推断出的配置或在eclipseDSL中明确定义的配置合并。
4. 执行whenMerged钩子，使用表示将要持久化的文件内容的领域对象。
5. 执行withXml钩子，使用将要持久化的XML的原始表示形式。
6. 持久化最终的XML。

下面是每种模型类型使用的领域对象：

• IdeaProject

  • beforeMerged { Project arg -> … }
  • whenMerged { Project arg -> … }
  • withXml { XmlProvider arg -> … }

• IdeaModule

  • beforeMerged { Module arg -> … }
  • whenMerged { Module arg -> … }
  • withXml { XmlProvider arg -> … }

• IdeaWorkspace

  • beforeMerged { Workspace arg -> … }
  • whenMerged { Workspace arg -> … }
  • withXml { XmlProvider arg -> … }

部分重写现有内容

"完全重写"会导致丢失所有现有内容，从而丢失在IDE中直接进行的任何更改。beforeMerged钩子使得可以仅覆盖现有内容的某些部分。以下示例从模块领域对象中删除了所有现有依赖项：

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

生成的模块文件将只包含由Gradle生成的依赖项条目，而不包含原始文件中可能存在的任何其他依赖项条目。（对于依赖项条目，这也是默认行为。）模块文件的其他部分将保持不变或合并。在项目文件中可以执行相同的操作：

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

修改完全填充的领域对象

whenMerged钩子允许您操纵完全填充的领域对象。通常，这是自定义IDEA文件的首选方法。以下示例导出了IDEA模块的所有依赖项：

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

修改XML表示形式

withXml钩子允许您在文件写入磁盘之前操纵内存中的XML表示形式。虽然Groovy的XML支持和Kotlin的扩展函数很强大，但这种方法比操纵领域对象更不方便。作为回报，您可以完全控制生成的文件，包括领域对象未建模的部分。

以下示例演示了如何自定义XML：

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

识别附加的测试目录

当与Java插件一起使用此插件时，在添加其他源集后，您可能希望通知IDEA它们包含的是测试源而不是生产源，以便IDE可以适当地处理这些目录。可以通过使用该插件的Module块来实现。例如：

build.gradle
sourceSets {
    intTest {
        java {
            srcDirs = ['src/integration']
        }
    }
}

idea {
    module {
        testSources.from(sourceSets.intTest.java.srcDirs)
    }
}

使用JVM Test Suite插件时，测试源将自动正确识别。

其他事项

生成的IDEA文件中的依赖路径是绝对路径。如果手动定义了指向Gradle依赖缓存的路径变量，则IDEA会自动将绝对依赖路径替换为此路径变量。您可以通过"idea.pathVariables"属性配置此路径变量，以便在不创建重复项的情况下进行正确合并。

参考链接