第二十章. 构建环境

Chapter 20. The Build Environment

20.1. 通过 gradle.properties 配置构建环境

20.1. Configuring the build environment via gradle.properties

Gradle提供了几个选项,可以很容易地配置用于执行构建的 Java 进程。尽管可以通过 GRADLE_OPTS 或 JAVA_OPTS 在本地环境中配置这些设置,但是如果某些设置,像 JVM 内存设置,Java home,守护进程开启/关闭等特定设置可以提交到 VCS 的话会更有用,这样整个团队就能使用一致的环境。为你的构建建立一个一致的环境就像将这些设置放入一个 gradle.properties 文件一样简单。这些配置将按以下顺序被应用(以防一个选项在多个位置都有配置时只有最后一个生效):
Gradle provides several options that make it easy to configure the Java process that will be used to execute your build. While it's possible to configure these in your local environment via GRADLE_OPTS or JAVA_OPTS, certain settings like JVM memory settings, Java home, daemon on/off can be more useful if they can versioned with the project in your VCS so that the entire team can work with consistent environment. Setting up a consistent environment for your build is as simple as placing those settings into a gradle.properties file. The configuration is applied in following order (in case an option is configured in multiple locations the last one wins):

  • 位于项目构建目录的 gradle.properties
    from gradle.properties located in project build dir.
  • 位于 gradle 用户主目录gradle.properties
    from gradle.properties located in gradle user home.
  • 系统属性,例如当在命令行中使用 -Dsome.property 时。
    from system properties, e.g. when -Dsome.property is used in the command line.

下面的属性可以用于配置 Gradle 构建环境:
The following properties can be used to configure the Gradle build environment:

org.gradle.daemon

当设置为 true 时,Gradle 守护进程会运行构建。对于本地开发者的构建而言,这是我们最喜欢的属性。开发人员的环境在速度和反馈上会优化,因此我们几乎总是使用守护进程运行 Gradle 作业。我们不会使用守护进程(即长时间运行的进程)运行 CI 构建,因为 CI 环境已经进行了优化以保持一致性和可靠性。
When set to true the Gradle daemon is to run the build. For local developer builds this is our favorite property. The developer environment is optimized for speed and feedback so we nearly always run Gradle jobs with the daemon. We don't run CI builds with the daemon (i.e. a long running process) as the CI environment is optimized for consistency and reliability.

org.gradle.java.home

指定 Gradle 构建进程的 java 主目录。该值可以设置为 JDKJRE 的位置,但是,根据你的构建所做的事情,JDK 会更安全。如果这一设置没有指定,则使用合理的默认值。
Specifies the java home for the Gradle build process. The value can be set to either jdk or jre location, however, depending on what does your build do, jdk is safer. Reasonable default is used if the setting is unspecified.

org.gradle.jvmargs

指定用于守护进程的 jvmargs。该设置对调整内存设置特别有用。目前的默认设置是在内存方面非常大方。
Specifies the jvmargs used for the daemon process. The setting is particularly useful for tweaking memory settings. At the moment the default settings are pretty generous with regards to memory.

org.gradle.configureondemand

启用新的试验性的模式,该模式可以在配置项目时使 Gradle 具有选择性。只适用于相关的项目被配置为在大型多项目中更快地构建。请参阅《第 56.1.1.1 节,“按需配置”》。
Enables new incubating mode that makes Gradle selective when configuring projects. Only relevant projects are configured which results in faster builds for large multi-projects. See Section 56.1.1.1, “Configuration on demand”.

org.gradle.parallel

配置之后,Gradle 将在试验性的并行模式下运行。
When configured, Gradle will run in incubating parallel mode.

20.1.1. Forked java 进程

20.1.1. Forked java processes

许多设置(如 java 版本和最大堆大小)只能在为构建进程启动新的 JVM 时指定。这意味着 Gradle 必须在解析各种 gradle.properties 文件后启动一个单独的 JVM 进程执行构建。当使用守护进程运行时,具有正确参数的JVM 将启动一次,并在每个守护进程的构建执行时重用。在没有守护进程的情况下执行 Gradle 时,除非由 Gradle 启动脚本启动的 JVM 恰好具有相同的参数,否则必须为每个构建的执行启动一个新的 JVM。
Many settings (like the java version and maximum heap size) can only be specified when launching a new JVM for the build process. This means that Gradle must launch a separate JVM process to execute the build after parsing the various gradle.properties files. When running with the daemon, a JVM with the correct parameters is started once and reused for each daemon build execution. When Gradle is executed without the daemon, then a new JVM must be launched for every build execution, unless the JVM launched by the Gradle start script happens to have the same parameters.

在每次构建执行中都启动一个额外的 JVM 的开销是非常大的,这就是为什么如果你指定了 org.gradle.java.homeorg.gradle.jvmargs,我们会强烈建议你使用 Gradle Daemon。更多细节请查阅《第十九章,Gradle 守护进程》。
This launching of an extra JVM on every build execution is quite expensive, which is why we highly recommend that you use the Gradle Daemon if you are specifying org.gradle.java.home or org.gradle.jvmargs. See Chapter 19, The Gradle Daemon for more details.

20.2. 通过代理访问网络

20.2. Accessing the web via a proxy

配置 HTTP 代理(例如用于下载依赖)是通过标准的 JVM 系统属性完成的。这些属性可以直接在构建脚本中设置;例如通过 System.setProperty('http.proxyHost', 'www.somehost.org') 来设置代理主机。或者,可以在构建的根目录或 Gradle 主目录中的 gradle.properties 文件中指定这些属性。
Configuring an HTTP proxy (for example for downloading dependencies) is done via standard JVM system properties. These properties can be set directly in the build script; for example System.setProperty('http.proxyHost', 'www.somehost.org') for the proxy host. Alternatively, the properties can be specified in a gradle.properties file, either in the build's root directory or in the Gradle home directory.

示例 20.1. 配置 HTTP 代理 - Example 20.1. Configuring an HTTP proxy

gradle.properties

systemProp.http.proxyHost=www.somehost.org
systemProp.http.proxyPort=8080
systemProp.http.proxyUser=userid
systemProp.http.proxyPassword=password
systemProp.http.nonProxyHosts=*.nonproxyrepos.com|localhost

HTTPS 有单独的设置。
There are separate settings for HTTPS.

示例 20.1. 配置 HTTPS 代理 - Example 20.2. Configuring an HTTPS proxy

gradle.properties

systemProp.https.proxyHost=www.somehost.org
systemProp.https.proxyPort=8080
systemProp.https.proxyUser=userid
systemProp.https.proxyPassword=password
systemProp.https.nonProxyHosts=*.nonproxyrepos.com|localhost

我们无法很好地概述所有可能的代理服务器设置。其中可以去查看的地方一个是 Ant 项目的一个文件中的常量,这里有一个到 Subversion 视图的链接;另一个是 JDK 文档里的网络属性页面。如果有人知道更好的概述,请通过邮件列表告诉我们。
We could not find a good overview for all possible proxy settings. One place to look are the constants in a file from the Ant project. Here a link to the Subversion view. The other is a Networking Properties page from the JDK docs. If anyone knows a better overview, please let us know via the mailing list.

20.2.1. NTLM 身份验证

20.2.1. NTLM Authentication

如果你的代理需要 NTLM 身份验证,则可能需要提供身份验证域以及用户名和密码。有两种方法可以向 NTLM 代理提供进行身份验证的域:
If your proxy requires NTLM authentication, you may need to provide the authentication domain as well as the username and password. There are 2 ways that you can provide the domain for authenticating to a NTLM proxy:

  • http.proxyUser 系统属性设置为一个这样的值:domain/username
    Set the http.proxyUser system property to a value like domain/username.
  • 通过 http.auth.ntlm.domain 系统属性提供验证域。
    Provide the authentication domain via the http.auth.ntlm.domain system property.