Chapter 15. The Build Environment

15.1. Configuring the build environment via 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):

from gradle.properties located in gradle user home.
from gradle.properties located in project build dir.
from system properties, e.g. when -Dsome.property is used in the command line.

The following properties can be used to configure the gradle build environment:

org.gradle.daemon

When set to true the gradle daemon is to run the build. This is our favorite property because we nearly always run gradle jobs with the daemon.

org.gradle.java.home

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

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.

15.1.1. Forked java processes

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.

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 13, The Gradle Daemon for more details.

15.2. Accessing the web via a proxy

Setting a proxy for web access (for example for downloading dependencies) is easy. Gradle does not need to provide special functionality for this. The JVM can be instructed to go via proxy by setting certain system properties. You could set these system properties directly in your build script with System.properties['proxy.proxyUser'] = 'userid'. Alternatively, you can specify these system properties in a gradle.properties file, either in the project build directory or in you gradle home directory.

You gradle.properties file could look something like:

Example 15.1. Accessing the web via a 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

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 svn 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.

15.2.1. NTLM Authentication

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:

Set the http.proxyUser system property to a value like domain/username.
Provide the authentication domain via the http.auth.ntlm.domain system property.