Файл: Gradle.pdf

Put a file that ends with .gradle in the USER_HOME/.gradle/init.d/ directory.

Put a file that ends with .gradle in the GRADLE_HOME/init.d/ directory, in the Gradle distribution. This allows you to package up a custom Gradle distribution containing some custom build logic and plugins. You can combine this with the Gradle wrapper as a way to make custom logic available to all builds in your enterprise.

If more than one init script is found they will all be executed, in the order specified above. Scripts in a given directory are executed in alphabetical order. This allows, for example, a tool to specify an init script on the command line and the user to put one in their home directory for defining the environment and both scripts will run when Gradle is executed.

53.3. Writing an init script

Similar to a Gradle build script, an init script is a groovy script. Each init script has a Gradle instance associated with it. Any property reference and method call in the init script will delegate to this Gradle instance.

Each init script also implements the Script interface.

53.3.1. Configuring projects from an init script

You can use an init script to configure the projects in the build. This works in a similar way to configuring projects in a multi-project build. The following sample shows how to perform extra configuration from an init script before the projects are evaluated. This sample uses this feature to configure an extra repository to be used only for certain environments.

Page 320 of 343

Example 53.1. Using init script to perform extra configuration before projects are evaluated

build.gradle

repositories { mavenCentral()

}

task showRepos << { println "All repos:"

println repositories.collect { it.name }

}

init.gradle

allprojects { repositories {

mavenLocal()

}

}

Output of gradle --init-script init.gradle -q showRepos

> gradle --init-script init.gradle -q showRepos All repos:

[MavenLocal, MavenRepo]

53.4. External dependencies for the init script

In Section 52.5, “External dependencies for the build script”is was explained how to add external dependencies to a build script. Init scripts can similarly have external dependencies defined. You do this using the initscript() method, passing in a closure which declares the init script classpath.

Example 53.2. Declaring external dependencies for an init script

init.gradle

initscript { repositories {

mavenCentral()

}

dependencies {

classpath group: 'org.apache.commons', name: 'commons-math', version:

}

}

The closure passed to the initscript() method configures a ScriptHandler instance. You declare the init script classpath by adding dependencies to the classpath configuration. This is the same way you declare, for example, the Java compilation classpath. You can use any of the dependency types described in Section 43.4, “How to declare your dependencies”,except project dependencies.

Page 321 of 343

Having declared the init script classpath, you can use the classes in your init script as you would any other classes on the classpath. The following example adds to the previous example, and uses classes from the init script classpath.

Example 53.3. An init script with external dependencies

init.gradle

import org.apache.commons.math.fraction.Fraction

initscript { repositories {

mavenCentral()

}

dependencies {

classpath group: 'org.apache.commons', name: 'commons-math', version:

}

}

println Fraction.ONE_FIFTH.multiply(2)

Output of gradle --init-script init.gradle -q doNothing

> gradle --init-script init.gradle -q doNothing 2 / 5

Page 322 of 343

54

The Gradle Wrapper

The Gradle Wrapper (henceforth referred to as the “wrapper) is the preferred way of starting Gradle build. The wrapper is a batch script on Windows, and a shell script for other operating systems. When you start a Gradle build via the wrapper, Gradle will be automatically downloaded and used to run the build.

The wrapper is something you should check into version control. By distributing the wrapper with your project, anyone can work with it without needing to install Gradle beforehand. Even better, users of the build are guaranteed to use the version of Gradle that the build was designed to work with. Of course, this is also great for continuous integration servers (i.e. servers that regularly build your project) as it requires no configuration on the server.

You install the wrapper into your project by adding and configuring a Wrapper task in your build script, and then executing it.

Example 54.1. Wrapper task

build.gradle

task wrapper(type: Wrapper) { gradleVersion = '0.9'

}

After such an execution you find the following new or updated files in your project directory (in case the default configuration of the wrapper task is used).

Example 54.2. Wrapper generated files

Build layout

simple/ gradlew gradlew.bat

gradle/wrapper/ gradle-wrapper.jar gradle-wrapper.properties

Page 323 of 343

All of these files should be submitted to your version control system. This only needs to be done once. After these files have been added to the project, the project should then be built with the added gradlew command. The gradlew command can be used exactly the same way as the gradle command.

If you want to switch to a new version of Gradle you don't need to rerun the wrapper task. It is goo enough to change the respective entry in the gradle-wrapper.properties file. But if there is for example an improvement in the gradle-wrapper functionality you need to regenerate the wrapper files.

54.1. Configuration

If you run Gradle with gradlew, Gradle checks if a Gradle distribution for the wrapper is available. If not it tries to download it, otherwise it delegates to the gradle command of this distribution with all the arguments passed originally to the gradlew command.

You can specify where the wrapper files should be stored (within your project directory):

Example 54.3. Configuration of wrapper task

build.gradle

task wrapper(type: Wrapper) { gradleVersion = '0.9'

jarFile = 'wrapper/wrapper.jar'

}

Build layout

customized/ gradlew gradlew.bat wrapper/

wrapper.jar

wrapper.properties

You can specify the download URL of the wrapper distribution. You can also specify where the wrapper distribution should be stored and unpacked (either within the project or within the Gradle user home dir). If the wrapper is run and there is local archive of the wrapper distribution Gradle tries to download it and stores it at the specified place. If there is no unpacked wrapper distribution Gradle unpacks the local archive of the wrapper distribution at the specified place. All the configuration options have defaults except the version of the wrapper distribution.

For the details on how to configure the wrapper, see Wrapper

If you don't want any download to happen when your project is build viagradlew, simply add the Gradle distribution zip to your version control at the location specified by your wrapper configuration. Relative url is supported - you can specify a distribution file relative to the location of file.

If you build via the wrapper, any existing Gradle distribution installed on the machine is ignored.

Page 324 of 343

54.2. Unix file permissions

The Wrapper task adds appropriate file permissions to allow the execution for the gradlew *NIX command. Subversion preserves this file permission. We are not sure how other version control systems deal with this. What should always work is to execute sh gradlew.

54.3. Environment variable

Some rather exotic use cases might occur when working with the Gradle Wrapper. For example the continuous integration server goes down during unzipping the Gradle distribution. As the distribution directory exists gradlew delegates to it but the distribution is corrupt. Or the zip-distribution was not properly downloaded. When you have no admin right on the continuous integration server to remove the corrupt files, Gradle offers a solution via environment variables.

Table 54.1. Gradle wrapper environment variables

Page 325 of 343

55

Embedding Gradle

55.1. Introduction to the Tooling API

The 1.0 milestone 3 release brought a new API called the tooling API, which you can use for embedding Gradle. This API allows you to execute and monitor builds, and to query Gradle about the details of a build. The main audience for this API is IDE, CI server, other UI authors, or integration testing of your Gradle plugins. However, it is open for anyone who needs to embed Gradle in their application.

A fundamental characteristic of the tooling API is that it operates in a version independent way. This means that you can use the same API to work with different target versions of Gradle. The tooling API is Gradle wrapper aware and, by default, uses the same target Gradle version as that used by the wrapper-powered project.

Some features that the tooling API provides today:

You can query Gradle for the details of a build, including the project hierarchy and the project dependencies, external dependencies (including source and javadoc jars), source directories and tasks of each project.

You can execute a build, and listen to stdout and stderr logging and progress (e.g. the stuff shown in the 'status bar' when you run on the command line).

Tooling API can download and install the appropriate Gradle version, similar to the wrapper. Bear in mind that the tooling API is wrapper aware so you should not need to configure a Gradle distribution directly.

The implementation is lightweight, with only a small number of dependencies. It is also a well-behaved library, and makes no assumptions about your class loader structure or logging configuration. This makes the API easy to bundle in your application.

In future we may support other interesting features:

Performance. The API gives us the opportunity to do lots of caching, static analysis and preemptive work, to make things faster for the user.

Better progress monitoring and build cancellation. For example, allowing test execution to be monitored.

Notifications when things in the build change, so that UIs and models can be updated. For example, your Eclipse or IDEA project will update immediately, in the background.

Page 326 of 343

Validating and prompting for user supplied configuration.

Prompting for and managing user credentials.

The Tooling API is the official and recommended way to embed Gradle. This means that the existing APIs, namely GradleLauncher and the open API (the UIFactory and friends), are mildly deprecated and will be removed in some future version of Gradle. If you happen to use one of the above APIs, please consider changing your application to use the tooling API instead.

55.2. Tooling API and the Gradle Build Daemon

Please take a look at Chapter 13, The Gradle Daemon. The Tooling API uses the daemon all the time, e.g. you cannot officially use the Tooling API without the daemon. This means that subsequent calls to the Tooling API, be it model building requests or task executing requests can be executed in the same long-living process. Chapter 13, The Gradle Daemon contains more details about the daemon, specifically information on situations when new daemons are forked.

55.3. Quickstart

Since the tooling API is an interface for a programmer most of the documentation lives in Javadoc/Groovydoc. This is exactly our intention - we don't expect this chapter to grow very much Instead we will add more code samples and improve the Javadoc documentation. The main entry point to the tooling API is the GradleConnector. You can navigate from there and find code samples and other instructions. Pretty effective way of learning how to use the tooling API is checking out and running the samples that live in $gradleHome/samples/toolingApi.

If you're embedding Gradle and you're looking for exact set of dependencies the tooling API J requires please look at one of the samples in $gradleHome/samples/toolingApi. The dependencies are declared in the Gradle build scripts. You can also find the repository declarations where the Jars are obtained from.

Page 327 of 343

A

Gradle Samples

Listed below are some of the stand-alone samples which are included in the Gradle distribution. You can find these samples in the GRADLE_HOME/samples directory of the distribution.

Table A.1. Samples included in the distribution

Page 328 of 343