// Copyright 2017 the original author or authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[gradle_daemon]]
= The Gradle Daemon

[quote, Wikipedia]
A daemon is a computer program that runs as a background process, rather than being under the direct control of an interactive user.

Gradle runs on the Java Virtual Machine (JVM) and uses several supporting libraries with non-trivial initialization time.
Startup can be slow. The **Gradle Daemon** solves this problem.

The Daemon is a long-lived background process that reduces the time it takes to run a build.
The Daemon reduces build times by:

* caching project information across builds
* running in the background so every Gradle build doesn't have to wait for JVM startup
* benefiting from continuous runtime optimization in the JVM
* <<file_system_watching.adoc#sec:daemon_watch_fs,watching the file system>> to calculate exactly what needs to be rebuilt before you run a build

[[sec:status]]
== Check Status

To get a list of running Daemons and their statuses, use the `--status` command:

====
[listing.terminal]
----
$ gradle --status
----
====

Sample output:
[source]
----
   PID STATUS   INFO
 28486 IDLE     7.5
 34247 BUSY     7.5
----

Currently, a given Gradle version can only connect to Daemons of the same version.
This means the status output only shows Daemons spawned running the same version of Gradle as the current project.

[[find_all_daemons]]
=== Find all Daemons

If you have the Java Development Kit (JDK) installed, you can view live Daemons with the `jps` command.
Live Daemons appear under the name `GradleDaemon`. Because this command uses the JDK, you can view Daemons
running any version of Gradle.

== Enable

Gradle enables the Daemon by default since Gradle 3.0. If your project doesn't use the
Daemon, you can enable it for a single build with the `--daemon` flag when you run a build:

====
[listing.terminal]
----
$ gradle <task> --daemon
----
====

This flag overrides any settings that disable the Daemon in your project or user `gradle.properties` files.

To enable the Daemon by default in older Gradle versions, add the following setting to the
`gradle.properties` file in the project root or your Gradle user home:

====
.gradle.properties
[source,properties]
----
org.gradle.daemon=true
----
====

[[sec:disabling_the_daemon]]
== Disable

You can disable the Daemon in multiple ways.

=== Disable for a Build

To disable the Daemon for a single build, pass the `--no-daemon` flag when you run a build:

====
[listing.terminal]
----
$ gradle <task> --no-daemon
----
====

This flag overrides any settings that enable the Daemon in your project or user `gradle.properties` files.

=== Disable for a Project

To disable the Daemon for all builds of a project, add `org.gradle.daemon=false` to
the `gradle.properties` file in the project root.

=== Disable for a User

On Windows, this command disables the Daemon for the current user:

[source]
----
(if not exist "%USERPROFILE%/.gradle" mkdir "%USERPROFILE%/.gradle") && (echo. >> "%USERPROFILE%/.gradle/gradle.properties" && echo org.gradle.daemon=false >> "%USERPROFILE%/.gradle/gradle.properties")
----

On UNIX-like operating systems, the following Bash shell command disables the Daemon for the current user:

[source,bash]
----
mkdir -p ~/.gradle && echo "org.gradle.daemon=false" >> ~/.gradle/gradle.properties
----

=== Disable Globally

There are two recommended ways to disable the Daemon globally across an environment:

* add `org.gradle.daemon=false` to the `<GRADLE_USER_HOME>/gradle.properties` file
* add the flag `-Dorg.gradle.daemon=false` to the `GRADLE_OPTS` environment variable

[[sec:stopping_an_existing_daemon]]
== Stop

It can be helpful to stop the Daemon when troubleshooting or debugging a failure.
Daemons automatically stop given any of the following conditions:

* available system memory is low
* the Daemon has been idle for 3 hours

To stop running Daemon processes, use the following command:

====
[listing.terminal]
----
$ gradle --stop
----
====

This terminates all Daemon processes started with the same version of Gradle used to execute the command.

You can also kill Daemons manually with your operating system. To find the PIDs for all Daemons regardless of Gradle version,
see <<gradle_daemon.adoc#find_all_daemons,Find all Daemons>>.

[[sec:tools_and_ides]]
== Tools & IDEs

The <<third_party_integration.adoc#embedding,Gradle Tooling API>> used by IDEs and other tools
to integrate with Gradle _always_ uses the Gradle Daemon to execute builds.
If you execute Gradle builds from within your IDE, you already use the Gradle Daemon.
There's no need to enable it for your environment.

== Continuous Integration

We recommend using the Daemon for both developer machines and Continuous Integration servers.

[[compatibility]]
== Compatibility

Gradle starts a new Daemon if no idle or compatible Daemons exist.
The following values determine compatibility:

* *Requested build environment*, including the following:
** Java version
** JVM attributes
** JVM properties
* Gradle version

Compatibility is based on exact matches of these values. For example:

* If a Daemon is available with a Java 8 runtime, but the requested build environment calls for Java 10,
  then the Daemon is not compatible.

* If a Daemon is available running Gradle 7.0, but the current build uses Gradle 7.4, then the
  Daemon is not compatible.

Certain properties of a Java runtime are _immutable_: they cannot be changed once the JVM has started.
The following JVM system properties are immutable:

* `file.encoding`
* `user.language`
* `user.country`
* `user.variant`
* `java.io.tmpdir`
* `javax.net.ssl.keyStore`
* `javax.net.ssl.keyStorePassword`
* `javax.net.ssl.keyStoreType`
* `javax.net.ssl.trustStore`
* `javax.net.ssl.trustStorePassword`
* `javax.net.ssl.trustStoreType`
* `com.sun.management.jmxremote`

The following JVM attributes controlled by startup arguments are also immutable:

* The maximum heap size (the `-Xmx` JVM argument)
* The minimum heap size (the `-Xms` JVM argument)
* The boot classpath (the `-Xbootclasspath` argument)
* The “assertion” status (the `-ea` argument)

If the requested build environment requirements for any of these properties and attributes
differ from the Daemon’s JVM requirements, the Daemon is not compatible.

[NOTE]
====

For more information about build environments, see <<build_environment.adoc#build_environment,the build environment documentation>>.

====

[[sec:why_the_daemon]]
== Performance Impact

The Daemon can reduce build times by 15-75% when you build the same project repeatedly.

TIP: To get a sense of the Daemon's impact on your builds, you can profile your build with `--profile`.

In between builds, the Daemon waits idly for the next build.
As a result, your machine only loads Gradle into memory once for multiple builds, instead of once per build.
This is a significant performance optimization. But that's not where it stops.

=== Runtime Code Optimizations

The JVM gains significant performance from **runtime code optimization**: optimizations applied to code while it runs.
JVM implementations like OpenJDK's Hotspot progressively optimize code during execution.
Subsequent builds can be faster purely due to this optimization process.
Experiments with HotSpot show that it takes somewhere between 5 and 10 builds for optimization to stabilize.
Thanks to the Daemon, perceived build times can drop dramatically between the first build and tenth builds of a project.

=== Memory Caching

The Daemon enables in-memory caching across builds. This includes classes for plugins and build scripts.
Similarly, the Daemon maintains in-memory caches of build data such as the hashes of task inputs and outputs for incremental builds.

== Performance Monitoring

Gradle actively monitors heap usage to detect memory leaks in the Daemon.
When a memory leak exhausts available heap space, the Daemon:

. Finishes the currently running build.
. Restarts before running the next build.

Gradle enables this monitoring by default.
To disable this monitoring, set the `org.gradle.daemon.performance.enable-monitoring` Daemon option to
`false`. You can do this on the command line with the following command:

====
[listing.terminal]
----
$ gradle <task> -Dorg.gradle.daemon.performance.enable-monitoring=false
----
====

Or configure the property in the `gradle.properties` file in the project root or your Gradle project home:

====
.gradle.properties
[source,properties]
----
org.gradle.daemon.performance.enable-monitoring=false
----
====

[[daemon_faq]]
== FAQ

[[sec:why_is_there_more_than_one_daemon_process_on_my_machine]]
=== Why is there more than one Daemon process on my machine?

Gradle starts a new Daemon process for your build if no idle Daemon exists with a compatible configuration.
For more information about compability, see <<gradle_daemon.adoc#compatibility,Compatibility>>.

[[sec:how_much_memory_does_the_daemon_use_and_can_i_give_it_more]]
=== How much memory does the Daemon use and can I give it more?

If the requested build environment does not specify a maximum heap size, the Daemon uses up to 512MB of heap.
Daemons use the JVM's default minimum heap size. 512MB is more than enough for most builds.
Larger builds with hundreds of subprojects, lots of configuration, and source code may benefit from a larger heap size.

To increase the amount of memory the Daemon can use, specify the appropriate flags as part of the requested build environment.
Please see <<build_environment.adoc#build_environment,the build environment documentation>> for details.

[[sec:what_can_go_wrong_with_daemon]]
=== What can go wrong with the Daemon?

User build scripts and third party plugins can destabilize the Daemon through memory leaks, poor resource management,
and global state corruption. Failing to close files after reading and writing is a common cause.
The Microsoft Windows operating system frequently stops Daemon processes destabilized in this way.

Specify the `--no-daemon` switch for a build to prevent use of the Daemon.
This can help determine if the Daemon is causing a problem with your build.
