Eclipse 外掛程式與配置快取不相容。

Eclipse 外掛程式會產生 Eclipse IDE 使用的檔案，因此可以將專案匯入 Eclipse (File - Import…​ - Existing Projects into Workspace)。

每當 eclipse 外掛程式套用至 War 或 Ear 專案時，就會自動套用 eclipse-wtp。對於公用程式專案 (即其他 Web 專案使用的 Java 專案)，您需要明確套用 eclipse-wtp 外掛程式。

eclipse 外掛程式實際產生哪些內容取決於使用的其他外掛程式

表 1. Eclipse 外掛程式行為
外掛程式 說明

無

產生最簡化的 .project 檔案。

Java

將 Java 配置新增至 .project。產生 .classpath 和 JDT 設定檔。

Groovy

將 Groovy 配置新增至 .project 檔案。

Scala

將 Scala 支援新增至 .project 和 .classpath 檔案。

War

將 Web 應用程式支援新增至 .project 檔案。

Ear

將 ear 應用程式支援新增至 .project 檔案。

eclipse-wtp 外掛程式會產生所有 WTP 設定檔，並增強 .project 檔案。如果套用了 Java 或 War，則會擴充 .classpath，以便為此公用程式程式庫或 Web 應用程式專案取得適當的封裝結構。

Eclipse 外掛程式均可自訂，並提供標準化的掛勾集，用於從產生的檔案新增和移除內容。

用法

若要使用 Eclipse 或 Eclipse WTP 外掛程式，請在您的建置腳本中加入下列其中一行

範例 1. 使用 Eclipse 外掛程式
build.gradle.kts
plugins {
    eclipse
}
build.gradle
plugins {
    id 'eclipse'
}
範例 2. 使用 Eclipse WTP 外掛程式
build.gradle.kts
plugins {
    `eclipse-wtp`
}
build.gradle
plugins {
    id 'eclipse-wtp'
}

注意： 在內部，eclipse-wtp 外掛程式也會套用 eclipse 外掛程式，因此您不需要同時套用兩者。

Eclipse 外掛程式都會為您的專案新增許多工作。您將使用的主要工作是 eclipse 和 cleanEclipse 工作。

工作

Eclipse 外掛程式會將以下顯示的工作新增至專案。

Eclipse 外掛程式工作

eclipse — Task

相依於：所有 Eclipse 配置檔案產生工作

產生所有 Eclipse 配置檔案

cleanEclipse — Delete

相依於：所有 Eclipse 配置檔案清除工作

移除所有 Eclipse 配置檔案

cleanEclipseProject — Delete

移除 .project 檔案。

cleanEclipseClasspath — Delete

移除 .classpath 檔案。

cleanEclipseJdt — Delete

移除 .settings/org.eclipse.jdt.core.prefs 檔案。

eclipseProject — GenerateEclipseProject

產生 .project 檔案。

eclipseClasspath — GenerateEclipseClasspath

產生 .classpath 檔案。

eclipseJdt — GenerateEclipseJdt

產生 .settings/org.eclipse.jdt.core.prefs 檔案。

Eclipse WTP 外掛程式 — 其他工作

cleanEclipseWtpComponent — Delete

移除 .settings/org.eclipse.wst.common.component 檔案。

cleanEclipseWtpFacet — Delete

移除 .settings/org.eclipse.wst.common.project.facet.core.xml 檔案。

eclipseWtpComponent — GenerateEclipseWtpComponent

產生 .settings/org.eclipse.wst.common.component 檔案。

eclipseWtpFacet — GenerateEclipseWtpFacet

產生 .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 檔案的區段也是產生內容的目標，將會根據特定區段進行修訂或覆寫。其餘區段將保持不變。

停用合併並完全重寫

若要完全重寫現有的 Eclipse 檔案，請執行清除工作及其對應的產生工作，例如「gradle cleanEclipse eclipse」(依此順序)。如果您想要將此設為預設行為，請將「tasks.eclipse.dependsOn(cleanEclipse)」新增至您的建置腳本。這樣就不需要明確執行清除工作。

此策略也可用於外掛程式會產生的個別檔案。例如，可以使用「gradle cleanEclipseClasspath eclipseClasspath」對「.classpath」檔案執行此操作。

掛勾至產生生命週期

Eclipse 外掛程式提供物件，為 Gradle 產生的 Eclipse 檔案區段建模。產生生命週期如下

  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 網域物件移除所有現有相依性

範例 3. 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 檔案的其他區段將保持不變或合併。.project 檔案中的 natures 也可以執行相同的操作

範例 4. Project 的部分覆寫
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 專案的所有相依性

範例 5. 匯出 Classpath 項目
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 的擴充功能彌補了很多不足，但這種方法不如操作網域物件方便。作為回報，您可以完全控制產生的檔案，包括網域物件未建模的區段。

範例 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 檔案、專案相依性等。每個類別路徑項目都可以有一個類別路徑屬性清單，其中屬性是字串鍵值組。有兩個與測試來源相關的類別路徑屬性：test 和 without_test_code，兩者都可以將 true 或 false 作為值。

如果來源目錄具有 test=true 類別路徑屬性，則內容會被視為測試來源。測試來源可以存取非測試來源，但非測試來源無法存取測試來源。同樣地，只有當 jar 檔案具有 test=true 類別路徑屬性時，測試來源才能參考 jar 檔案中的類別。對於專案相依性，如果存在 test=true 屬性，則目標專案中的類別對測試來源可見。如果存在 without_test_code=false 屬性，則目標專案的測試來源也可以存取。依預設，測試程式碼不可用 (可以認為是隱含地具有 without_test_code=true)。

產生 Eclipse 類別路徑時，下列規則適用於測試屬性宣告

  • 來源集和相依性配置會分類為測試，如果其名稱包含 'test' 子字串，不論大小寫。

  • JVM 測試套件外掛程式定義的所有來源集和相依性配置都會分類為測試。

  • 如果容器來源集是測試來源集，則來源目錄具有 test=true 類別路徑屬性。

  • 如果 jar 檔案和專案相依性僅存在於測試相依性配置中，則它們具有 test=true 屬性。

  • 如果目標專案套用 java-test-fixtures 外掛程式，則專案相依性具有 without_test_sources=false 屬性。

您可以自訂測試來源集和配置

範例 7. 自訂測試來源
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 屬性將測試來源公開給上游專案相依性。

範例 8. 自訂測試組件
build.gradle.kts
eclipse {
    classpath {
        containsTestFixtures = true
    }
}
build.gradle
eclipse {
    classpath {
        containsTestFixtures = true
    }
}

請注意，此配置也適用於 Buildship 專案的類別路徑。