Chapter 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. At the moment, we marked the Gradle build daemon as experimental because there are still many aspects of the daemon we'd like to improve.

The Tooling API (see Chapter 54, 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 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.
Preemtive execution of certain tasks, for example compilation. Quicker feedback.
Fast and accurate bash tab completion.
Periodically garbage collect the Gradle caches.

13.2. Implementation notes

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.

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 deamon 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 deamon 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 14.3, “Configuring gradle 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 back to us with feedback (or even better: the pull requests). Some ways of troubleshooting the gradle daemon:

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 is located by default in the gradle user home.
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, “Gradle properties and system properties”