Eclipse 插件与 配置缓存 不兼容。

Eclipse 插件生成的文件供 Eclipse IDE 使用,从而可以将项目导入到 Eclipse 中 (File - Import…​ - Existing Projects into Workspace)。

eclipse 插件应用于 WarEar 项目时,会自动应用 eclipse-wtp 插件。对于实用程序项目 (即其他 Web 项目使用的 Java 项目),您需要显式应用 eclipse-wtp 插件。

eclipse 插件具体生成哪些文件取决于使用的其他插件

表 1. Eclipse 插件行为
插件 描述

生成最小的 .project 文件。

Java

.project 添加 Java 配置。生成 .classpath 和 JDT 设置文件。

Groovy

.project 文件添加 Groovy 配置。

Scala

.project.classpath 文件添加 Scala 支持。

War

.project 文件添加 Web 应用程序支持。

Ear

.project 文件添加 ear 应用程序支持。

eclipse-wtp 插件生成所有 WTP 设置文件并增强 .project 文件。如果应用了 JavaWar,则会扩展 .classpath 以获得此实用程序库或 Web 应用程序项目的正确打包结构。

Eclipse 插件都支持自定义,并提供了一组标准化的钩子,用于在生成的文件中添加和删除内容。

用法

要使用 Eclipse 或 Eclipse WTP 插件,请在您的构建脚本中包含以下行之一

build.gradle.kts
plugins {
    eclipse
}
build.gradle
plugins {
    id 'eclipse'
}
build.gradle.kts
plugins {
    `eclipse-wtp`
}
build.gradle
plugins {
    id 'eclipse-wtp'
}

注意: 在内部,eclipse-wtp 插件也应用了 eclipse 插件,因此您无需同时应用两者。

Eclipse 插件都向您的项目添加了许多 task。您将使用的主要 task 是 eclipsecleanEclipse task。

Task

Eclipse 插件将以下 task 添加到项目中。

Eclipse 插件 task

eclipseTask

依赖于:所有 Eclipse 配置文件生成 task

生成所有 Eclipse 配置文件

cleanEclipseDelete

依赖于:所有 Eclipse 配置文件清理 task

删除所有 Eclipse 配置文件

cleanEclipseProjectDelete

删除 .project 文件。

cleanEclipseClasspathDelete

删除 .classpath 文件。

cleanEclipseJdtDelete

删除 .settings/org.eclipse.jdt.core.prefs 文件。

eclipseProjectGenerateEclipseProject

生成 .project 文件。

eclipseClasspathGenerateEclipseClasspath

生成 .classpath 文件。

eclipseJdtGenerateEclipseJdt

生成 .settings/org.eclipse.jdt.core.prefs 文件。

Eclipse WTP 插件 — 附加 task

cleanEclipseWtpComponentDelete

删除 .settings/org.eclipse.wst.common.component 文件。

cleanEclipseWtpFacetDelete

删除 .settings/org.eclipse.wst.common.project.facet.core.xml 文件。

eclipseWtpComponentGenerateEclipseWtpComponent

生成 .settings/org.eclipse.wst.common.component 文件。

eclipseWtpFacetGenerateEclipseWtpFacet

生成 .settings/org.eclipse.wst.common.project.facet.core.xml 文件。

配置

表 2. Eclipse 插件的配置
模型 引用名称 描述

EclipseModel

eclipse

顶级元素,可以 DSL 友好的方式配置 Eclipse 插件。

EclipseProject

eclipse.project

允许配置项目信息

EclipseClasspath

eclipse.classpath

允许配置类路径信息。

EclipseJdt

eclipse.jdt

允许配置 jdt 信息(源/目标 Java 兼容性)。

EclipseWtpComponent

eclipse.wtp.component

仅当应用了 eclipse-wtp 插件时,才允许配置 wtp 组件信息。

EclipseWtpFacet

eclipse.wtp.facet

仅当应用了 eclipse-wtp 插件时,才允许配置 wtp facet 信息。

自定义生成的文件

Eclipse 插件允许您自定义生成的元数据文件。这些插件提供了一个 DSL,用于配置对项目的 Eclipse 视图进行建模的模型对象。然后,这些模型对象与现有的 Eclipse XML 元数据合并,最终生成新的元数据。模型对象提供较低级别的钩子,用于处理表示与模型配置合并之前和之后的文件内容的域对象。它们还提供了一个非常低级别的钩子,用于直接处理原始 XML,以便在持久化之前进行调整,从而对 Eclipse 和 Eclipse WTP 插件未建模的微调和配置进行调整。

合并

现有 Eclipse 文件中也是生成内容目标的 sections 将被修改或覆盖,具体取决于特定的 section。其余 sections 将保持原样。

禁用合并并完全重写

要完全重写现有的 Eclipse 文件,请执行清理 task 及其对应的生成 task,例如 “gradle cleanEclipse eclipse”(按此顺序)。如果您想将此作为默认行为,请在您的构建脚本中添加 “tasks.eclipse.dependsOn(cleanEclipse)”。这样就不必显式执行清理 task。

此策略也可用于插件将生成的单个文件。例如,可以使用 “gradle cleanEclipseClasspath eclipseClasspath” 对 “.classpath” 文件执行此操作。

挂钩到生成生命周期

Eclipse 插件提供对 Gradle 生成的 Eclipse 文件 sections 进行建模的对象。生成生命周期如下

  1. 读取文件;或者如果文件不存在,则使用 Gradle 提供的默认版本

  2. 执行 beforeMerged 钩子,并使用表示现有文件的域对象

  3. 现有内容与从 Gradle 构建推断或在 eclipse DSL 中显式定义的配置合并

  4. 执行 whenMerged 钩子,并使用表示要持久化的文件内容的域对象

  5. 执行 withXml 钩子,并使用将要持久化的 XML 的原始表示形式

  6. 持久化最终的 XML

高级配置钩子

以下列表涵盖了每个 Eclipse 模型类型使用的域对象

EclipseProject
EclipseClasspath
EclipseWtpComponent
EclipseWtpFacet
EclipseJdt
  • beforeMerged { Jdt arg -> …​ }

  • whenMerged { Jdt arg -> …​ }

  • withProperties { arg -> } 参数类型 ⇒ java.util.Properties

部分覆盖现有内容

完全覆盖会导致所有现有内容被丢弃,从而丢失直接在 IDE 中所做的任何更改。或者,beforeMerged 钩子可以仅覆盖现有内容的某些部分。以下示例从 Classpath 域对象中删除所有现有依赖项

build.gradle.kts
import org.gradle.plugins.ide.eclipse.model.Classpath

eclipse.classpath.file {
    beforeMerged(Action<Classpath> {
        entries.removeAll { entry -> entry.kind == "lib" || entry.kind == "var" }
    })
}
build.gradle
eclipse.classpath.file {
    beforeMerged { classpath ->
        classpath.entries.removeAll { entry -> entry.kind == 'lib' || entry.kind == 'var' }
    }
}

生成的 .classpath 文件将仅包含 Gradle 生成的依赖项条目,而不包含原始文件中可能存在的任何其他依赖项条目。(对于依赖项条目,这也是默认行为。).classpath 文件的其他 sections 将保持原样或合并。对于 .project 文件中的 natures 也可以执行相同的操作

build.gradle.kts
import org.gradle.plugins.ide.eclipse.model.Project

eclipse.project.file.beforeMerged(Action<Project> {
    natures.clear()
})
build.gradle
eclipse.project.file.beforeMerged { project ->
    project.natures.clear()
}

修改完全填充的域对象

whenMerged 钩子允许操作完全填充的域对象。这通常是自定义 Eclipse 文件的首选方法。以下是如何导出 Eclipse 项目的所有依赖项

build.gradle.kts
import org.gradle.plugins.ide.eclipse.model.AbstractClasspathEntry
import org.gradle.plugins.ide.eclipse.model.Classpath

eclipse.classpath.file {
    whenMerged(Action<Classpath> { ->
        entries.filter { entry -> entry.kind == "lib" }
            .forEach { (it as AbstractClasspathEntry).isExported = false }
    })
}
build.gradle
eclipse.classpath.file {
    whenMerged { classpath ->
        classpath.entries.findAll { entry -> entry.kind == 'lib' }*.exported = false
    }
}

修改 XML 表示形式

withXml 钩子允许在文件写入磁盘之前操作内存中的 XML 表示形式。尽管 Groovy 的 XML 支持和 Kotlin 的扩展函数弥补了很多不足,但这种方法不如操作域对象方便。作为回报,您可以完全控制生成的文件,包括域对象未建模的 sections。

示例 6. 自定义 XML
build.gradle.kts
import org.w3c.dom.Element

eclipse.wtp.facet.file.withXml(Action<XmlProvider> {
    fun Element.firstElement(predicate: Element.() -> Boolean) =
        childNodes
            .run { (0 until length).map(::item) }
            .filterIsInstance<Element>()
            .first { it.predicate() }

    asElement()
        .firstElement { tagName === "fixed" && getAttribute("facet") == "jst.java" }
        .setAttribute("facet", "jst2.java")
})
build.gradle
eclipse.wtp.facet.file.withXml { provider ->
    provider.asNode().fixed.find { it.@facet == 'jst.java' }.@facet = 'jst2.java'
}

分离测试类路径条目

Eclipse 每个项目仅定义一个类路径,这意味着 Gradle 项目的映射方式存在限制。Eclipse 4.8 引入了 测试源 的概念。此功能允许 Eclipse 插件在测试源和非测试源之间定义更好的分离。

Eclipse 类路径由类路径条目组成:源目录、jar 文件、项目依赖项等。每个类路径条目都可以具有类路径属性列表,其中属性是字符串键值对。有两个与测试源相关的类路径属性:testwithout_test_code,它们的值可以是 truefalse

如果源目录具有 test=true 类路径属性,则该目录的内容被视为测试源。测试源可以访问非测试源,但非测试源不能访问测试源。同样,测试源只能引用 jar 文件中的类,前提是该 jar 文件具有 test=true 类路径属性。对于项目依赖项,如果存在 test=true 属性,则目标项目中的类对测试源可见。如果存在 without_test_code=false 属性,则目标项目的测试源也可以访问。默认情况下,测试代码不可用(可以认为隐式具有 without_test_code=true)。

生成 Eclipse 类路径时,以下规则适用于 test 属性声明

  • 如果源集和依赖项配置的名称包含 'test' 子字符串(不区分大小写),则将其归类为测试。

  • JVM 测试套件插件定义的所有源集和依赖项配置都归类为测试。

  • 如果容器源集是测试源集,则源目录具有 test=true 类路径属性。

  • 如果 jar 文件和项目依赖项仅存在于测试依赖项配置中,则它们具有 test=true 属性。

  • 如果目标项目应用了 java-test-fixtures 插件,则项目依赖项具有 without_test_sources=false 属性。

您可以自定义测试源集和配置

build.gradle.kts
eclipse {
    classpath {
        testSourceSets = testSourceSets.get() + setOf(integTest)
        testConfigurations = testConfigurations.get() + setOf(functional)
    }
}
build.gradle
eclipse {
    classpath {
        testSourceSets = testSourceSets.get() + [sourceSets.integTest]
        testConfigurations = testConfigurations.get() + [configurations.functional]
    }
}
在这种情况下,请考虑从手动定义其他测试源集迁移到使用 JVM 测试套件插件

您还可以自定义项目是否应通过 containsTestFixtures 属性向上游项目依赖项公开测试源。

build.gradle.kts
eclipse {
    classpath {
        containsTestFixtures = true
    }
}
build.gradle
eclipse {
    classpath {
        containsTestFixtures = true
    }
}

请注意,此配置也适用于 Buildship 项目的类路径。