Gradle 1.12用户指南翻译——第六十二章. 嵌入 Gradle

其他章节的翻译请参见：
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.6开发中版本兼容 Android 2.3以上系统，项目地址如下：
https://github.com/msdx/gradle-doc-apk
翻译不易，转载请注明本文在CSDN博客上的出处：

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

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

另外，目前Gradle1.12版本的文档已经翻译完并进入校稿阶段，校稿的方式为到该项目https://github.com/msdx/gradledoc 提交issue或是pull request。校稿的结果不只是在此版本更新，也会用于改善Gradle下一版本（2.0）文档的翻译。

第六十二章. 嵌入 Gradle

62.1.Tooling API 简介

1.0 里程碑 3 的发布带来了新的 API 叫tooling API，可以用于嵌入 Gradle。这个API可以让你执行和监视构建，并向Gradle 查询有关构建的细节。它的主要受众是IDE，CI服务器，其他的UI作者，或者你的Gradle插件的集成测试。不过，它是向所有需要把Gradle嵌入到他们的应用的人开放的。

这个tooling API 的一个基本特征是它以一个版本独立的方式管理。这意味着，你可以让同样的API与不同的Gradle版本一起使用。Tooling API 是有Gradle包装器感知的，并且默认情况下使用与wrapper-powered 项目相同的目标Gradle版本。

目前这个tooling API提供了以下这些功能：

• 你可以查询Gradle 关于构建的详细信息，包括项目层次结构和项目依赖，外部依赖（包括源代码及javadoc jars），源代码目录以及每一个项目的任务。
• 你可以执行构建，并且监听标准输出和错误输出的日志和进度（例如当你在命令上运行时显示在“状态栏”上的东西）。
• Tooling API 可以下载和安装适当的Gradle版本，类似于包装器。记住，tooling API 是有包装器感知的，因此你不需要直接 配置Gradle分发包。
• 它的实现很轻量，只有很少的依赖。它也是一个很优秀的库，并且不会有魅力从你的类加载器结构或者日志的配置。这便于把API捆绑到你的应用程序中。

将来我们可能会支持一些其他有趣的功能：

• 性能。这个API 让我们有机会去做大量的缓存，静态分析以及抢占式的工作，为用户提供更快的速度。
• 更好的进度监控及可取消构建。例如，允许对测试的执行进行监控。
• 当构建中的内容有变化时进行通知，以便可以更新UI和模型。例如，你的 Eclipse 或IDEA 项目将在后台中马上更新。
• 对用户提供的配置进行验证和输入提示。
• 提示输入和管理用户凭据

Tooling API 是官方及推荐的嵌入Gradle 的方法。这意味着，现有的 API，即GradleLauncher和开放的 API（UIFactory 及同类）已经被弃用，且会在以后的 Gradle 版本中移除。如果你碰巧使用一种上面的API，请考虑一下更改你的应用程序，改为使用tooling API。

62.2. Tooling API 及 Gradle 构建守护进程

请查看 第十九章，Gradle守护进程。Tooling API 在整个过程中都会使用守护进程，举例来说，没有守护进程，你不能正式地使用Tooling API。这意味着对Tooling API的后续调用，无论是模型构建请求还是任务执行请求，都可以在同一个长期存活的进程中执行。第十九章，Gradle守护进程包含了关于守护进程的更多细节内容，特别是当新进行被fork时的信息。

62.3. 快速入门

由于tooling API 是一个针对程序员的接口，因此大部分的文档都在Javadoc中。这正是我们的意图——我们并不想这章内容变得很长。相反的，我们将添加更多的代码示例来完善Javadoc 文档. Tooling API 的主要入口点是GradleConnector。你可以从那里导航和查找代码示例以及其他说明。关于学习如何使用 API 的非常有效的方法是，检出及运行在$gradleHome/samples/toolingApi上的示例。

如果你正在嵌入 Gradle，并且你正在寻找tooling API Jar所需要的确切的依赖，，请参考在$gradleHome/samples/toolingApi上的一些示例。依赖是在 Gradle 构建脚本中声明的。你也可以找到获取Jar 的仓库声明。