Файл: Gradle.pdf

This report lists summary times and details for both the configuration phase and task execution. The times for configuration and task execution are sorted with the most expensive operations first. The task execution results also indicate if any tasks were skipped (and the reason) or if tasks that were not skipped did no work.

Builds which utilize a buildSrc directory will generate a second profile report for buildSrc in the buil directory.

11.6. Dry Run

Sometimes you are interested in which tasks are executed in which order for a given set of tasks specified on the command line, but you don't want the tasks to be executed. You can use the-m option for this. For example gradle -m clean compile shows you all tasks to be executed as part of the clean and compile tasks. This is complementary to the tasks task, which shows you the tasks which are available for execution.

11.7. Summary

In this chapter, you have seen some of the things you can do with Gradle from the command-line. You can find out more about the gradle command in Appendix C, Gradle Command Line.

Page 63 of 343

12

Using the Gradle Graphical User

Interface

In addition to supporting a traditional command line interface, Gradle offers a graphical user interface. This is a stand alone user interface that can be launched with the --gui option.

Example 12.1. Launching the GUI

gradle --gui

Note that this command blocks until the Gradle GUI is closed. Under *nix it is probably preferable to run this as a background task (gradle --gui&)

If you run this from your Gradle project working directory, you should see a tree of tasks.

Page 64 of 343

Figure 12.1. GUI Task Tree

It is preferable to run this command from your Gradle project directory so that the settings of the UI will be stored in your project directory. However, you can run it then change the working directory via the Setup tab in the UI.

The UI displays 4 tabs along the top and an output window along the bottom.

12.1. Task Tree

The Task Tree shows a hierarchical display of all projects and their tasks. Double clicking a task executes it.

There is also a filter so that uncommon tasks can be hidden. You can toggle the filter via the Filter button. Editing the filter allows you to configure which tasks and projects are shown. Hidden tasks show up in red. Note: newly created tasks will show up by default (versus being hidden by default).

The Task Tree context menu provides the following options:

Page 65 of 343

Execute ignoring dependencies. This does not require dependent projects to be rebuilt (same as the -a option).

Add tasks to the favorites (see Favorites tab)

Hide the selected tasks. This adds them to the filter.

Edit the build.gradle file. Note: this requires Java 1.6 or higher and requires that you have

.gradle files associated in your OS.

12.2. Favorites

The Favorites tab is place to store commonly-executed commands. These can be complex commands (anything that's legal to Gradle) and you can provide them with a display name. This i useful for creating, say, a custom build command that explicitly skips tests, documentation, and samples that you could call "fast build".

You can reorder favorites to your liking and even export them to disk so they can imported by others. If you edit them, you are given options to "Always Show Live Output." This only applies if you have 'Only Show Output When Errors Occur'. This override always forces the output to shown.

12.3. Command Line

The Command Line tab is place to execute a single Gradle command directly. Just enter whatever you would normally enter after 'gradle' on the command line. This also provides a place to try o commands before adding them to favorites.

12.4. Setup

The Setup tab allows configuration of some general settings.

Page 66 of 343

Figure 12.2. GUI Setup

Current Directory

Defines the root directory of your Gradle project (typically where build.gradle is located).

Stack Trace Output

This determines how much information to write out stack traces when errors occur. Note: if you specify a stack trace level on either the Command Line or Favorites tab, it will override this stack trace level.

Only Show Output When Errors Occur

Enabling this option hides any output when a task is executed unless the build fails.

Use Custom Gradle Executor - Advanced feature

This provides you with an alternate way to launch Gradle commands. This is useful if your

Page 67 of 343

project requires some extra setup that is done inside another batch file or shell script (such as specifying an init script).

Page 68 of 343

13

The Gradle Daemon

13.1. Enter the daemon

The Gradle daemon (sometimes referred as the build daemon) aims to improve the startup and execution time of Gradle.

We came up with several use cases where the daemon is very useful. For some workflows, the user invokes Gradle many times to execute a small number of relatively quick tasks. For example:

When using test driven development, where the unit tests are executed many times. When developing a web application, where the application is assembled many times. When discovering what a build can do, where gradle -t is executed a number of times.

For above sorts of workflows, it is important that the startup cost of invoking Gradle is as small as possible.

In addition, user interfaces can provide some interesting features if the Gradle model can be built relatively quickly. For example, the daemon might be useful for following scenarios:

Content assistance in the IDE

Live visualisation of the build in a GUI

Tab completion in a CLI

In general, snappy behavior of the build tool is always handy. If you try using the daemon for your local builds it's going to be hard for you to go back to regular use of Gradle.

The Tooling API (see Chapter 55, Embedding Gradle) uses the daemon all the time, e.g. you cannot officially use the Tooling API without the daemon. This means that if you use the STS Gradle plugin for Eclipse or new Intellij IDEA plugin (IDEA>10) the daemon acts behind the hood.

In future the daemon will offer more features:

Snappy up-to-date checks: use native file system change notifications (eg via jdk7 nio.2) to preemptively perform up-to-date analysis.

Even faster builds: preemptively evaluate projects, so that the model is ready when the user next invokes Gradle.

Did we mention faster builds? The daemon can potentially preemptively download

Page 69 of 343

dependencies or check for new versions of snapshot dependencies.

Utilize a pool of reusable processes available for compilation and testing. For example, both the Groovy and Scala compilers have a large startup cost. The build daemon could maintain a process with Groovy and/or Scala already loaded.

Preemptive execution of certain tasks, for example compilation. Quicker feedback. Fast and accurate bash tab completion.

Periodically garbage collect the Gradle caches.

13.2. Reusing and expiration of daemons

The basic idea is that the gradle command forks a daemon process, which performs the actual build. Subsequent invocations of the gradle command will reuse the daemon, avoiding the startup costs. Sometimes we cannot use an existing daemon because it is busy or its java version or jvm arguments are different. For exact details on when exactly new daemon process is forked read the dedicated section below. The daemon process automatically expire after 3 hours of idle time.

Here're all situations in which we fork a new daemon process:

If the daemon process is currently busy running some job, a brand new daemon process will be started.

We fork a separate daemon process per java home. So even if there is some idle daemon waiting for build requests but you happen to run build with a different java home then a brand new daemon will be forked.

We fork a separate daemon process if the jvm arguments for the build are sufficiently different. For example we will not fork a new daemon if a some system property has changed. However if -Xmx memory setting change or some fundamental immutable system property changes (e.g. file.encoding) then new daemon will be forked.

At the moment daemon is coupled with particular version of Gradle. This means that even if some daemon is idle but you are running the build with a different version of Gradle, a new daemon will be started. This also have a consequence for the --stop command line instruction: You can only stop daemons that were started with the Gradle version you use when running --stop.

We plan to improve the ways of managing / pooling the daemons in future.

13.3. Usage and troubleshooting

For command line usage take a look dedicated section in Appendix C, Gradle Command Line. If you are tired of using the same command line options again and again, take a look at Section 15.1, “Configuring the build environment via gradle.properties”.The section contains information on how to configure certain behavior of the daemon (including turning on the daemon by default) in a more 'persistent' way.

As mentioned earlier we are actively improving the daemon. At the moment the daemon is marked as 'experimental' in the user interface. We encourage everyone to try the daemon out and get ba to us with feedback (or even better: the pull requests). Some ways of troubleshooting the Gradle daemon:

Page 70 of 343

If you have a problem with your build, try temporarily disabling the daemon (you can pass the command line switch --no-daemon).

Occasionally, you may want to stop the daemons either via the --stop command line option or in a more forceful way.

There is a daemon log file, which by default is located in the Gradle user home directory. You may want to start the daemon in --foreground mode to observe how the build is executed.

13.4. Daemon properties

Some daemon settings can be configured in gradle.properties. For example, jvm args - memory settings or the java home. Please find more information in Section 14.2, “Gradl properties and system properties”

Page 71 of 343

14

Tutorial - 'This and Tha

14.1. Directory creation

There is a common situation, that multiple tasks depend on the existence of a directory. Of course you can deal with this by adding a mkdir to the beginning of those tasks. But this is kind of bloated. There is a better solution (works only if the tasks that need the directory have a dependsOn relationship):

Example 14.1. Directory creation with mkdir

build.gradle

classesDir = new File('build/classes') task resources << {

classesDir.mkdirs() // do something

}

task compile(dependsOn: 'resources') << { if (classesDir.isDirectory()) {

println 'The class directory exists. I can operate'

}

// do something

}

Output of gradle -q compile

> gradle -q compile

The class directory exists. I can operate

14.2. Gradle properties and system properties

Gradle offers a variety of ways to add properties to your build. With the -D command line option you can pass a system property to the JVM which runs Gradle. The -D option of the gradle command has the same effect as the -D option of the java command.

You can also directly add properties to your project objects using properties files. You can place a g file in the Gradle user home directory (defaults to USER_HOME/.gradle) or in your project directory. For multi-project builds you can place gradle.properties files in any subproject

Page 72 of 343

directory. The properties of the gradle.properties can be accessed via the project object. The properties file in the user's home directory has precedence over property files in the projec directories.

You can also add properties directly to your project object via the -P command line option. For more exotic use cases you can even pass properties directly to the project object via system and environment properties. For example if you run a build on a continuous integration server where you have no admin rights for the machine. Your build script needs properties which values should not be seen by others. Therefore you can't use the-P option. In this case you can add an environment property in the project administration section (invisible to normal users). [5] If the environment property follows the pattern ORG_GRADLE_PROJECT_propertyName=somevalue, p is added to your project object. If in the future CI servers support Gradle directly, they might start Gradle via its main method. Therefore we already support the same mechanism for system properties. The only difference is the pattern, which is org.gradle.project.propertyName.

With the gradle.properties files you can also set system properties. If a property in such a file has the prefix systemProp. the property and its value are added to the system properties, without the prefix.

Example 14.2. Setting properties with a gradle.properties file

gradle.properties

gradlePropertiesProp=gradlePropertiesValue

systemPropertiesProp=shouldBeOverWrittenBySystemProp

envPropertiesProp=shouldBeOverWrittenByEnvProp

systemProp.system=systemValue

build.gradle

task printProps << {

println commandLineProjectProp println gradlePropertiesProp println systemProjectProp println envProjectProp

println System.properties['system']

}

Output of gradle -q -PcommandLineProjectProp=commandLineProjectPropValue -Do

> gradle -q -PcommandLineProjectProp=commandLineProjectPropValue -Dorg.gradle. commandLineProjectPropValue

gradlePropertiesValue systemPropertyValue envPropertyValue systemValue

Page 73 of 343