IDEA 外掛程式 - Gradle 建構系統

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

IDEA 外掛程式產生 IntelliJ IDEA 使用的檔案，因此可以從 IDEA 開啟專案 (檔案 - 開啟專案)。外部依賴 (包括相關的原始碼和 Javadoc 檔案) 和專案依賴都會被考慮。

如果您只想將 Gradle 專案載入 IntelliJ IDEA，請使用 IDE 的匯入功能。您不需要套用此外掛程式即可將專案匯入 IDEA，但如果您這樣做，匯入將會考慮您擁有的任何額外 IDEA 配置，這些配置不會直接修改產生的檔案 — 有關更多詳細資訊，請參閱配置章節。

IDEA 外掛程式具體產生什麼取決於使用了哪些其他外掛程式

總是: 產生 IDEA 模組檔案。如果專案是根專案，也會產生 IDEA 專案和工作區檔案。
Java 外掛程式: 此外，還會將 Java 配置新增到 IDEA 模組和專案檔案。

IDEA 外掛程式的一個重點是開放自訂。此外掛程式提供了一組標準化的掛鉤，用於從產生的檔案中新增和移除內容。

用法

若要使用 IDEA 外掛程式，請將其包含在您的建置腳本中

範例 1. 使用 IDEA 外掛程式

build.gradle.kts

plugins {
    idea
}

build.gradle

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 — GenerateIdeaProject: 產生 .ipr 檔案。此任務僅新增到根專案。
ideaModule — GenerateIdeaModule: 產生 .iml 檔案
ideaWorkspace — GenerateIdeaWorkspace: 產生 .iws 檔案。此任務僅新增到根專案。

配置

此外掛程式新增了一些配置選項，可讓您自訂其產生的 IDEA 專案和模組檔案。這些選項採用模型屬性和直接修改產生檔案的較低層級機制的形式。例如，您可以新增原始碼和資源目錄，以及注入您自己的 XML 片段。前一種配置類型會受到 IDEA 匯入功能的支援，而後一種則不會。

以下是您可以使用的配置屬性

idea — IdeaModel: 頂層元素，可以 DSL 友善的方式配置 idea 外掛程式
idea.project IdeaProject: 允許配置專案資訊
idea.module IdeaModule: 允許配置模組資訊
idea.workspace IdeaWorkspace: 允許配置工作區 XML

請參閱這些類型的連結，以取得使用這些配置屬性的範例。

自訂產生的檔案

IDEA 外掛程式提供了掛鉤和行為，以便以更受控且詳細的方式自訂產生的內容。此外，withXml 掛鉤是修改工作區檔案的唯一實用方法，因為其對應的網域物件本質上是空的。

我們在本節中討論的技術不適用於 IDEA 的匯入功能

這些任務會識別現有的 IDEA 檔案，並將它們與產生的內容合併。

合併

現有 IDEA 檔案中也是產生內容目標的部分將會被修改或覆寫，具體取決於特定部分。其餘部分將保持不變。

停用合併以進行完全覆寫

若要完全重寫現有的 IDEA 檔案，請將清除任務與其對應的產生任務一起執行，例如「gradle cleanIdea idea」(依此順序)。如果您想將其設為預設行為，請將「tasks.idea.dependsOn(cleanIdea)」新增到您的建置腳本中。這樣就不需要明確執行清除任務。

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

掛鉤到產生生命週期

此外掛程式提供了建模 Gradle 產生之元數據檔案區段的物件。產生生命週期如下

讀取檔案；或者，如果檔案不存在，則使用 Gradle 提供的預設版本
使用代表現有檔案的網域物件執行 beforeMerged 掛鉤
現有內容與從 Gradle 建置推斷或在 eclipse DSL 中明確定義的配置合併
使用代表要保存的檔案內容的網域物件執行 whenMerged 掛鉤
使用將被保存之 XML 的原始表示執行 withXml 掛鉤
最終 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 掛鉤可以僅覆寫現有內容的某些部分。以下範例從 Module 網域物件中移除所有現有的依賴關係

範例 2. 模組的部分重寫

build.gradle.kts

import org.gradle.plugins.ide.idea.model.Module

idea.module.iml {
    beforeMerged(Action<Module> {
        dependencies.clear()
    })
}

build.gradle

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

產生的模組檔案將僅包含 Gradle 產生的依賴關係項目，但不包含原始檔案中可能存在的任何其他依賴關係項目。(在依賴關係項目的情況下，這也是預設行為。) 模組檔案的其他部分將保持不變或合併。專案檔案中的模組路徑也可以執行相同的操作

範例 3. 專案的部分重寫

build.gradle.kts

import org.gradle.plugins.ide.idea.model.Project

idea.project.ipr {
    beforeMerged(Action<Project> {
        modulePaths.clear()
    })
}

build.gradle

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

修改完全填充的網域物件

whenMerged 掛鉤可讓您操作完全填充的網域物件。通常，這是自訂 IDEA 檔案的首選方式。以下是如何匯出 IDEA 模組的所有依賴關係

範例 4. 匯出依賴關係

build.gradle.kts

import org.gradle.plugins.ide.idea.model.Module
import org.gradle.plugins.ide.idea.model.ModuleDependency

idea.module.iml {
    whenMerged(Action<Module> {
        dependencies.forEach {
            (it as ModuleDependency).isExported = true
        }
    })
}

build.gradle

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

修改 XML 表示

withXml 掛鉤可讓您在檔案寫入磁碟之前操作記憶體中的 XML 表示。雖然 Groovy 的 XML 支援和 Kotlin 的擴充功能彌補了很多不足，但這種方法不如操作網域物件方便。作為回報，您可以完全控制產生的檔案，包括網域物件未建模的部分。

範例 5. 自訂 XML

build.gradle.kts

import org.w3c.dom.Element

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

        asElement()
            .firstElement { tagName == "component" && getAttribute("name") == "VcsDirectoryMappings" }
            .firstElement { tagName == "mapping" }
            .setAttribute("vcs", "Git")
    })
}

build.gradle

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

識別額外的測試目錄

當將此外掛程式與 Java 外掛程式一起使用時，在新增額外的原始碼集之後，您可能希望告知 IDEA 它們何時包含測試原始碼而不是生產原始碼，以便 IDE 可以適當地處理目錄。這可以透過使用此外掛程式的 Module 區塊來完成。

範例 6. 在 SourceSets 中識別額外的測試目錄

build.gradle.kts

sourceSets {
    create("intTest") {
        java {
            setSrcDirs(listOf("src/integration"))
        }
    }
}

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

build.gradle

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

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

當使用 JVM Test Suite 外掛程式時，測試原始碼將會自動正確識別。

進一步需要考慮的事項

產生的 IDEA 檔案中依賴關係的路徑是絕對路徑。如果您手動定義指向 Gradle 依賴關係快取的路徑變數，IDEA 會自動將絕對依賴關係路徑替換為此路徑變數。您可以透過「idea.pathVariables」屬性配置此路徑變數，以便它可以執行適當的合併而不會建立重複項目。

此頁面是否對您有幫助？