Gradle 1.12用户指南翻译——第三十八章. Eclipse 插件

本文由CSDN博客万一博主翻译，其他章节的翻译请参见：

http://blog.csdn.net/column/details/gradle-translation.html

翻译项目请关注Github上的地址：

https://github.com/msdx/gradledoc

本文翻译所在分支：

https://github.com/msdx/gradledoc/tree/1.12。

直接浏览双语版的文档请访问：

http://gradledoc.qiniudn.com/1.12/userguide/userguide.html。

另外，Android 手机用户可通过我写的一个程序浏览文档，带缓存功能的，目前0.2.1版本兼容 android 2.2以上系统，地址如下：

http://www.wandoujia.com/apps/com.githang.gradledoc

翻译不易，转载请注明本文在CSDN博客上的出处：

http://blog.csdn.net/maosidiaoxian/article/details/46963851

关于我对Gradle的翻译，以Github上的项目及http://gradledoc.qiniudn.com 上的文档为准。如有发现翻译有误的地方，将首先在以上两个地方更新。因时间精力问题，博客中发表的译文基本不会同步修改。

第三十八章. Eclipse 插件

Eclipse 插件生成Eclipse
IDE所使用的文件，从而让项目能够导入 Eclipse （File - Import... - Existing
Projects into Workspace）。它考虑到了外部依赖项 （包括相关联的源文件和 javadoc 文件） 和项目依赖项。

从 1.0-里程碑-4 开始，WTP-generating 代码被重构为一个单独的插件，叫做eclipse-wtp。所以如果你对
WTP 集成有兴趣，可以只应用eclipse-wtp插件。否则应用eclipse插件就足够了。这种变化是Eclipse用户要求的，他们想利用war或ear插件，但又不想用
Eclipse WTP。在内部，eclipse
wtp也应用了eclipse插件，所以你不需要同时应用这两个插件。

Eclipse 插件生成的内容完全取决于使用了哪些其他的插件：

表 38.1. Eclipse 插件行为

插件	描述
None	生成最小的.project文件。
Java	将 Java 配置添加到.project。生成.classpath和 JDT 设置文件。
Groovy	将 Groovy 配置添加到.project。
Scala	添加 Scala 支持到.project和.classpath文件。
War	将 web 应用程序支持添加到.project文件。仅当eclipse-wtp插件被应用时生成 WTP 设置文件。
ear	将 ear 应用程序支持添加到.project文件。仅当eclipse-wtp插件被应用时生成 WTP 设置文件。

Eclipse 插件是开放的，以定制和提供一套标准化的钩，用于添加和删除生成的文件的内容。

38.1.
用法

要使用 Eclipse 插件，请在构建脚本中包含以下语句：

示例 38.1. 使用 Eclipse 插件

build.gradle

apply plugin: 'eclipse'

Eclipse 插件向你的projects 添加了大量的任务。您将使用的主要任务是eclipse和cleanEclipse任务。

38.2.
任务

Eclipse 插件向一个 project 添加了如下所示的任务。

表 38.2. Eclipse 插件 - 任务

任务名称	依赖于	类型	描述
eclipse	eclipseProject, eclipseClasspath,eclipseJdt,  eclipseWtpComponent, cleanEclipseWtpFacet	Task	会生成所有的 Eclipse 配置文件
cleanEclipse	cleanEclipseProject, cleanEclipseClasspath,  cleanEclipseJdt, cleanEclipseWtpComponent, cleanEclipseWtpFacet	Delete	删除所有的 Eclipse 配置文件
cleanEclipseProject	-	Delete	删除.project文件。
cleanEclipseClasspath	-	Delete	删除.classpath文件。
cleanEclipseJdt	-	Delete	删除.settings/org.eclipse.jdt.core.prefs文件。
cleanEclipseWtpComponent	-	Delete	删除.settings/org.eclipse.wst.common.component文件。
cleanEclipseWtpFacet	-	Delete	删除.settings/org.eclipse.wst.common.component文件。
eclipseProject	-	GenerateEclipseProject	生成的.project文件。
eclipseClasspath	-	GenerateEclipseClasspath	生成.classpath文件。
eclipseJdt	-	GenerateEclipseJdt	生成.settings/org.eclipse.jdt.core.prefs文件。
eclipseWtpComponent	-	GenerateEclipseWtpComponent	只有当eclipse-wtp插件应用的时候，生成 .settings/org.eclipse.wst.common.component 文件。
eclipseWtpFacet	-	GenerateEclipseWtpFacet	只有当eclipse-wtp插件应用的时候，生成 .settings/org.eclipse.wst.common.project.facet.core.xml 文件。

38.3.
配置

表 38.3. Eclipse 插件的配置

模型	引用名称	描述
EclipseModel	eclipse	顶级元素，以DSL友好的方式启用 Eclipse 插件的配置
EclipseProject	eclipse.project	允许配置项目信息
EclipseClasspath	eclipse.classpath	允许配置类路径信息
EclipseJdt	eclipse.jdt	允许配置 jdt 信息 (source/target java 兼容性)
EclipseWtpComponent	eclipse.wtp.component	仅当eclipse-wtp插件被应用时，允许配置 wtp 组件信息。
EclipseWtpFacet	eclipse.wtp.facet	仅当eclipse-wtp插件被应用时，允许配置 wtp 方面信息。

38.4.
自定义生成的文件

Eclipse 插件允许您自定义生成的元数据文件。该插件提供一个 DSL，用于配置把该 project 的Eclipse 视图做成模型的模型对象。然后把这些模型对象与现有的 Eclipse XML 元数据进行合并，最终生成新的元数据。模型对象提供了低级别的hook，用于处理在合并模型配置前后表示文件内容的域对象。他们还提供了一个非常低级别的hook，用于直接处理原始 XML 持久化之前的调整，微调和配置使 Eclipse 插件不进行建模。

38.4.1.
合并

已存在的Eclipse 文件的部分，也是生成的目标内容，将会被修改或覆盖，具体取决于特定的部分。剩余的部分则不变。

38.4.1.1.
禁用完全覆盖的合并

若要完全覆盖现有 Eclipse 文件，请执行clean任务和其相应的生成任务，例如gradle
cleanEclipse eclipse (按此顺序)。如果你想要让它成为默认行为，请将tasks.eclipse.dependsOn(cleanEclipse)添加到构建脚本。这样一来，我们就没有必要显式执行
clean 任务。

完全覆盖同样可以用于个人文件，例如通过执行gradle
cleanEclipseClasspath eclipseClasspath。

38.4.2. Hooking到生成的生命周期中

Eclipse 插件提供了一些对象，对由 Gradle 生成的 Eclipse 文件的段落进行建模。生成的生命周期如下:

1. 读取文件;如果它不存在，则使用由 Gradle 提供的默认版本
2. beforeMerged的
   hook 会随着一个表示现有文件的域对象执行
3. 从 Gradle 构建推断出来或在 eclipse DSL 中显示定义的配置会与现有的内容合并在一起
4. whenMerged的
   hook 会随着一个表示持久化的域对象执行
5. withXml的 hook
   会随着一个表示将被持久化的XML的 raw 执行
6. 最终的 XML 被持久化

下表列出了用于每个 Eclipse 模型类型的域对象：

表 38.4. 高级的配置hook

模型	beforeMerged { arg -> } 参数类型	whenMerged { arg -> } 参数类型	withXml { arg -> } 参数类型
EclipseProject	Project	Project	XmlProvider
EclipseClasspath	Classpath	Classpath	XmlProvider
EclipseJdt	Jdt	Jdt
EclipseWtpComponent	WtpComponent	WtpComponent	XmlProvider
EclipseWtpFacet	WtpFacet	WtpFacet	XmlProvider

38.4.2.1.
部分重写现有内容

一个完全覆盖会导致现有的所有内容被丢弃，从而丢失在
IDE 中直接做的任何修改。另外， beforeMerged hook
可以实现只覆盖现有的某些部分的内容。下面的示例从Classpath域对象中删除现有的所有依赖关系:

示例 38.2. 部分覆盖 Classpath

build.gradle

eclipse.classpath.file {
    beforeMerged { classpath ->
        classpath.entries.removeAll { entry -> entry.kind == 'lib' || entry.kind == 'var' }
    }
}

生成的.classpath文件将只包含
Gradle 生成的依赖项，而没有其他可能存在于原始文件的依赖项。(对于依赖项，这也是默认行为。)其他部分的.classpath文件将会被合并或者保留。对.project文件中的natures的处理也是一样：

示例 38.3. 部分覆盖项目

build.gradle

eclipse.project.file.beforeMerged { project ->
    project.natures.clear()
}

38.4.2.2.
修改完全填充的域对象

WhenMerged hook
允许操作完全填充的域对象。通常，这是自定义 Eclipse 文件的首选的方法。下面的例子展示了如何导出一个 Eclipse 项目的所有依赖项：

示例 38.4. 导出依赖项

build.gradle

eclipse.classpath.file {
    whenMerged { classpath ->
        classpath.entries.findAll { entry -> entry.kind == 'lib' }*.exported = false
    }
}

38.4.2.3.
修改 XML 的表示形式

WithXml hook
允许在文件写入到磁盘之前，操纵内存中的 XML 的表示形式。尽管 Groovy 的 XML 支持对其有很大作用，但这种方法比起操纵域对象依然不大方便 。作为回报，你可以对生成的文件进行全面的控制，包括未由域对象建模的那些部分。

示例 38.5. 自定义 XML

build.gradle

apply plugin: 'eclipse-wtp'

eclipse.wtp.facet.file.withXml { provider ->
    provider.asNode().fixed.find { it.@facet == 'jst.java' }.@facet = 'jst2.java'
}