// Copyright (C) 2023 Gradle, Inc.
//
// Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.;
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      https://creativecommons.org/licenses/by-nc-sa/4.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.

[[build_environment]]
= Configuring the Build Environment

Gradle provides multiple mechanisms for configuring the behavior of Gradle itself and specific projects.
The following is a reference for using these mechanisms.

When configuring Gradle behavior, you can use these methods, listed in order of highest to lowest precedence (the first one wins):

[cols="1,1,1,2"]
|===
|Order |Method |Example |Notes

|1
|<<command_line_interface#command_line_interface, Command-line flags>>
|`--build-cache`
|These have precedence over properties and environment variables.

|2
|<<#sec:gradle_system_properties, System properties>>
|`systemProp.http.proxyHost=somehost.org`
|Stored in a `gradle.properties` file in a root project directory.

|3
|<<#sec:gradle_configuration_properties, Gradle properties>>
|`org.gradle.caching=true`
|Stored in a `gradle.properties` file in the `<<directory_layout.adoc#dir:gradle_user_home,GRADLE_USER_HOME>>`.

|3.1
|<<#sec:gradle_configuration_properties, Gradle properties>>
|`org.gradle.caching=true`
|Stored in a `gradle.properties` file in a project directory, then its parent project’s directory up to the project’s root directory.

|3.2
|<<#sec:gradle_configuration_properties, Gradle properties>>
|`org.gradle.caching=true`
|Stored in a `gradle.properties` file in the `<<sec:gradle_environment_variables,GRADLE_HOME>>`.

|4
|<<#sec:gradle_environment_variables, Environment variables>>
|`GRADLE_OPTS`
|Sourced by the environment that executes Gradle.
|===

== Configuring your build environment
You can configure the build using the same mechanisms.

You can also read information about the environment in the build logic.

[[sec:gradle_command_line_flags]]
== 1. Command-line flags

The command line interface, along with the available flags, is described in <<command_line_interface#command_line_interface,its own section>>.

[[sec:gradle_system_properties]]
== 2. System properties

Using 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 set system properties in `gradle.properties` files with the prefix `systemProp`:

----
systemProp.gradle.wrapperUser=myuser
systemProp.gradle.wrapperPassword=mypassword
----

The following are _common_ system properties:

*Gradle Properties*

`gradle.wrapperUser=(myuser)`:: Specify username to download Gradle distributions <<gradle_wrapper.adoc#sec:authenticated_download,from servers using HTTP Basic Authentication>>.
`gradle.wrapperPassword=(mypassword)`:: Specify password for downloading a Gradle distribution using the Gradle wrapper.
`gradle.user.home=(path to directory)`:: Specify the `GRADLE_USER_HOME` directory.

The Gradle Properties listed the <<#sec:gradle_configuration_properties,section below>> can also be set as system properties.

*Networking Properties*

`https.protocols`:: Specify the supported TLS versions in a comma-separated format. e.g., `TLSv1.2,TLSv1.3`.
`http.proxyHost`:: The hostname, or address, of the proxy server. Default: `none`.
`http.proxyPort`:: The port number of the proxy server. Default: `80`.
`http.nonProxyHosts`:: Indicates the hosts that should be accessed without going through the proxy. Default: `localhost|127.*|[::1]`.
`https.proxyHost`:: The hostname, or address, of the proxy server. Default: `none`.
`https.proxyPort`:: The port number of the proxy server. Default: `443`.
`socksProxyHost`:: The hostname, or address, of the proxy server. Default: `none`.
`socksProxyPort`:: The port number of the proxy server. Default: `1080`.
`socksProxyVersion`:: The version of the SOCKS protocol supported by the server. Default: `5` for SOCKS V5.
`java.net.socks.username`:: Username to use if the SOCKSv5 server asks for authentication. Default: `none`.
`java.net.socks.password`:: Password to use if the SOCKSv5 server asks for authentication. Default: `none`.

*Runtime Environment Properties*

`java.runtime.version=(string)`:: JRE version, e.g. `1.7.0_09-b05`.
`java.version=(string)`:: JDK version, e.g., `1.7.0_09`.
`java.home=(string)`:: JRE home directory, e.g., `C:\Program Files\Java\jdk1.7.0_09\jre`.
`java.class.path=(string)`:: JRE classpath e.g., `.` (dot – used for current working directory).
`java.library.path=(string)`:: JRE library search path for search native libraries. Typically taken from the environment variable PATH.
`java.ext.dirs=(string)`:: JRE extension library path(s), e.g, `C:\Program Files\Java\jdk1.7.0_09\jre\lib\ext;C:\Windows\Sun\Java\lib\ext`.

*Operating System Properties*

`os.name=(string)`:: The OS’s name, e.g., `Windows 7`.
`os.arch=(string)`:: The OS’s architecture, e.g., `x86`.
`os.version=(string)`:: The OS’s version, e.g., `6.1`.

*File System Properties*

`file.separator=(string)`:: Symbol for file directory separator such as `d:\test\test.java`. Default is '\' for windows or '/' for Unix/Mac.
`path.separator=(string)`:: Symbol for separating path entries, e.g., in PATH or CLASSPATH. Default is ';' for windows or ':' for Unix/Mac.
`line.separator=(string)`:: Symbol for end-of-line (or new line). Default is "\r\n" for windows or "\n" for Unix/Mac OS X.

*User Properties*

`user.name=(string)`:: The user’s name.
`user.home=(string)`:: The user’s home directory.
`user.dir=(string)`:: The user’s current working directory.

In a multi-project build, `systemProp` properties set in any project except the root will be *ignored*.
Only the root project's `gradle.properties` file will be checked for properties that begin with `systemProp`.

The following examples demonstrate how to use System properties.

*Example 1:* Setting system properties with a `gradle.properties` file:
====
include::sample[dir="snippets/tutorial/systemProperties/groovy",files="gradle.properties[]"]
====

*Example 2:* Reading system properties at configuration time:
====
include::sample[dir="snippets/tutorial/systemProperties/kotlin",files="init.gradle.kts[];settings.gradle.kts[];build.gradle.kts[tags=system-properties]"]
include::sample[dir="snippets/tutorial/systemProperties/groovy",files="init.gradle[];settings.gradle[];build.gradle[tags=system-properties]"]
====

*Example 3:* Reading system properties for consumption at execution time:
====
include::sample[dir="snippets/tutorial/systemProperties/kotlin",files="build.gradle.kts[tags=system-properties-task-inputs]"]
include::sample[dir="snippets/tutorial/systemProperties/groovy",files="build.gradle[tags=system-properties-task-inputs]"]
====

*Example 4:* Setting system properties from the command line `-D gradle.wrapperUser=username`:
====
----
$ gradle -Dsystem=commandLineValue
----
====

[[sec:gradle_configuration_properties]]
== 3. 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`, it is useful to be able to store certain settings like JVM memory configuration and `JAVA_HOME` location in version control so that an entire team can work with a consistent environment.

To do so, place these settings into a `gradle.properties` file and commit it to your version control system.

The final configuration taken into account by Gradle is a combination of all Gradle properties set on the command line and your `gradle.properties` files.

If an option is configured in multiple locations, the _first one_ found in any of these locations wins:

. command line, set using `-D`.
. `gradle.properties` in <<directory_layout.adoc#dir:gradle_user_home,`GRADLE_USER_HOME`>> directory.
. `gradle.properties` in the project's directory, then its parent project's directory up to the build's root directory.
. `gradle.properties` in the Gradle installation directory.

NOTE: The location of the `GRADLE_USER_HOME` may have been changed beforehand via the `-Dgradle.user.home` system property passed on the command line.

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

`org.gradle.caching=(true,false)`::
When set to `true`, Gradle will reuse task outputs from any previous build when possible, <<build_cache.adoc#build_cache,resulting in much faster builds>>.
+
_Default is `false`; the build cache is *not* enabled._

`org.gradle.caching.debug=(true,false)`::
When set to `true`, individual input property hashes and the build cache key for each task are <<build_cache.adoc#sec:task_output_caching,logged on the console>>.
+
_Default is `false`._

`org.gradle.configuration-cache=(true,false)`::
Enables <<configuration_cache.adoc#config_cache:usage:enable, configuration caching>>. Gradle will try to reuse the build configuration from previous builds.
+
_Default is `false`._

`org.gradle.configuration-cache.inputs.unsafe.ignore.file-system-checks=(file path)`::
Used to exclude file system checks on the specified path from configuration cache inputs fingerprinting.
+
_Default is `null`._

`org.gradle.configuration-cache.inputs.unsafe.ignore.in-serialization=(true,false)`::
Used to ignore inputs in task graph serialization.
+
_Default is `false`._

`org.gradle.configuration-cache.problems=(fail,warn)`::
Configures how the configuration cache <<configuration_cache.adoc#config_cache:usage:ignore_problems, handles problems>>.
+
Set to `warn` to report problems without failing the build.
+
Set to `fail` to report problems and fail the build if there are any problems.
+
_Default is `fail`._

`org.gradle.configuration-cache.max-problems=(# of problems)`::
Configures the <<configuration_cache.adoc#config_cache:usage:max_problems, maximum number of configuration cache problems>> allowed as warnings until Gradle fails the build.
+
_Default is `512`._

`org.gradle.configureondemand=(true,false)`::
Enables incubating configuration-on-demand, where Gradle will attempt to configure only necessary projects.
+
_Default is `false`._

`org.gradle.console=(auto,plain,rich,verbose)`::
Customize <<command_line_interface.adoc#sec:command_line_logging,console output>> coloring or verbosity.
+
_Default depends on how Gradle is invoked._

`org.gradle.continue=(true,false)`::
If enabled, continue task execution after a task failure, else stop task execution after a task failure.
+
_Default is `false`._

`org.gradle.continuous.quietperiod=(# of quiet period millis)`::
When using <<command_line_interface.adoc#sec:continuous_build,continuous build>>, Gradle will wait for the quiet period to pass before triggering another build.
Any additional changes within this quiet period restart the quiet period countdown.
+
_Default is `250` milliseconds._

`org.gradle.daemon=(true,false)`::
When set to `true` the <<gradle_daemon.adoc#gradle_daemon, Gradle Daemon>> is used to run the build.
+
_Default is `true`._

`org.gradle.daemon.healthcheckinterval=(# of millis)`::
Gradle Daemon health will be checked after a specified number of milliseconds.
+
_Default is `10000;` (10 secs)._

`org.gradle.daemon.idletimeout=(# of idle millis)`::
Gradle Daemon will terminate itself after a specified number of idle milliseconds.
+
_Default is `10800000` (3 hours)._

`org.gradle.daemon.registry.base=(directory)`::
Specify a Daemon registry path where the daemon registry file (addresses of active daemons) and daemon log files reside.
+
_Default is `.` (local directory)._

`org.gradle.debug=(true,false)`::
When set to `true`, Gradle will run the build with remote debugging enabled, listening on port 5005.
Note that this is equivalent to adding `-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005` to the JVM command line and will suspend the virtual machine until a debugger is attached.
+
_Default is `false`._

`org.gradle.debug.host=(host address)`::
Specifies the host address to listen on or connect to when debug is enabled.
In the server mode on Java 9 and above, passing `*` for the host will make the server listen on all network interfaces.
+
_Default is `null`; no host address is passed to JDWP (on Java 9 and above, the loopback address is used, while earlier versions listen on all interfaces)._

`org.gradle.debug.port=(port number)`::
Specifies the port number to listen on when debug is enabled.
+
_Default is `5005`._

`org.gradle.debug.server=(true,false)`::
If set to `true` and debugging is enabled, Gradle will run the build with the socket-attach mode of the debugger.
Otherwise, the socket-listen mode is used.
+
_Default is `true`._

`org.gradle.debug.suspend=(true,false)`::
When set to `true` and debugging is enabled, the JVM running Gradle will suspend until a debugger is attached.
+
_Default is `true`._

`org.gradle.dependency.verification=(strict,lenient,off)`::
Configures the dependency verification mode where in `strict` mode verification fails as early as possible, in order to avoid the use of compromised dependencies during the build.
+
_Default is `strict`._

`org.gradle.internal.instrumentation.agent=(true,false)`::
Enables the instrumentation Java agent for the daemon.
+
_Default is `true`._

`org.gradle.java.home=(path to JDK home)`::
Specifies the Java home for the Gradle build process.
The value can be set to either a `jdk` or `jre` location; however, depending on what your build does, using a JDK is safer.
This does not affect the version of Java used to launch the <<#sec:gradle_environment_variables,Gradle client VM>>.
+
_Default is derived from your environment (`JAVA_HOME` or the path to `java`) if the setting is unspecified._

`org.gradle.jvmargs=(JVM arguments)`::
Specifies the JVM arguments used for the Gradle Daemon.
The setting is particularly useful for <<config_gradle.adoc#sec:configuring_jvm_memory,configuring JVM memory settings>> for build performance.
This does not affect the JVM settings for the Gradle client VM.
+
_Default is `-Xmx512m "-XX:MaxMetaspaceSize=384m"`._

`org.gradle.logging.level=(quiet,warn,info,debug)`::
When set to quiet, warn, info, or debug, Gradle will use this <<logging.adoc#sec:choosing_a_log_level,log level>>.
The values are not case-sensitive.
+
_Default is `lifecycle` level._

`org.gradle.logging.stacktrace=(internal,all,full)`::
Specifies whether stacktraces should be displayed as part of the build result upon an exception. See the <<command_line_interface.adoc#sec:command_line_debugging, `--stacktrace command-line option` for additional information>>.
+
When set to `internal`, a stacktrace is present in the output only in case of internal exceptions.
+
When set to `all` or `full`, a stacktrace is present in the output for all exceptions and build failures.
+
Using `full` doesn't truncate the stacktrace, which leads to a much more verbose output.
+
_Default is `internal`._

`org.gradle.parallel=(true,false)`::
When configured, Gradle will fork up to `org.gradle.workers.max` JVMs to execute <<performance.adoc#parallel_execution,projects in parallel>>.
+
_Default is `false`._

`org.gradle.priority=(low,normal)`::
Specifies the <<command_line_interface.adoc#sec:command_line_performance,scheduling priority>> for the Gradle daemon and all processes launched by it.
+
_Default is `normal`._

`org.gradle.projectcachedir=(directory)`::
Specify the project-specific cache directory. Defaults to `.gradle` in the root project directory."
+
_Default is `.gradle`._

`org.gradle.unsafe.isolated-projects=(true,false)`::
Enables project isolation which enables configuration caching.
+
_Default is `false`._

`org.gradle.vfs.verbose=(true,false)`::
Configures verbose logging when <<file_system_watching.adoc#sec:daemon_watch_fs,watching the file system>>.
+
_Default is `false`._

`org.gradle.vfs.watch=(true,false)`::
Toggles <<file_system_watching.adoc#sec:daemon_watch_fs,watching the file system>>.
When enabled, Gradle reuses information it collects about the file system between builds.
+
_Default is `true` on operating systems where Gradle supports this feature._

`org.gradle.vfs.watch.debug=(true,false)`::
Enables debug events emitted in `native-platform` to be shown. Events are only shown when `--debug` is enabled or when the daemon is between builds.
+
_Default is `false`._

`org.gradle.warning.mode=(all,fail,summary,none)`::
When set to `all`, `summary` or `none`, Gradle will use <<command_line_interface.adoc#sec:command_line_logging,different warning type display>>.
+
_Default is `summary`._

`org.gradle.welcome=(never,once)`::
Controls whether Gradle should print a welcome message.
+
If set to `never`, then the welcome message will be suppressed.
+
If set to `once`, then the message is printed once for each new version of Gradle.
+
_Default is `once`._

`org.gradle.workers.max=(max # of worker processes)`::
When configured, Gradle will use a maximum of the <<command_line_interface.adoc#sec:command_line_performance,given number of workers>>.
+
_Default is the number of CPU processors._

The following examples demonstrate how to use Gradle properties.

*Example 1:* Setting Gradle properties with a `gradle.properties` file:
====
include::sample[dir="snippets/tutorial/gradleProperties/groovy",files="gradle.properties[tags=gradle-properties]"]
====

*Example 2:* Reading Gradle properties at configuration time:
====
include::sample[dir="snippets/tutorial/gradleProperties/kotlin",files="settings.gradle.kts[tags=gradle-properties];build.gradle.kts[tags=gradle-properties]"]
include::sample[dir="snippets/tutorial/gradleProperties/groovy",files="settings.gradle[tags=gradle-properties];build.gradle[tags=gradle-properties]"]
====

[.multi-language-text.lang-kotlin]
The link:https://kotlinlang.org/docs/delegated-properties.html[Kotlin delegated properties] are part of the Gradle Kotlin DSL.
You need to explicitly specify the type as `String`.
If you need to branch depending on the presence of the property, you can also use `String?` and check for `null`.

[.multi-language-text.lang-groovy]
Note that if a Gradle property has a dot in its name, using the dynamic Groovy names is not possible.
You have to use the API or the dynamic array notation instead.

*Example 3:* Reading Gradle properties for consumption at execution time:
====
include::sample[dir="snippets/tutorial/gradleProperties/kotlin",files="build.gradle.kts[tags=gradle-properties-task-inputs]"]
include::sample[dir="snippets/tutorial/gradleProperties/groovy",files="build.gradle[tags=gradle-properties-task-inputs]"]
====

*Example 4:* Setting Gradle properties from the command line:
====
----
$ gradle -DgradlePropertiesProp=commandLineValue
----
====

Note that <<init_scripts.adoc#init_scripts, initialization scripts>> can't read Gradle properties directly.
The earliest Gradle properties can be read in initialization scripts is on `settingsEvaluated {}`:

*Example 5:* Reading Gradle properties from initialization scripts:
====
include::sample[dir="snippets/tutorial/gradleProperties/kotlin",files="init.gradle.kts[tags=gradle-properties]"]
include::sample[dir="snippets/tutorial/gradleProperties/groovy",files="init.gradle[tags=gradle-properties]"]
====

Properties declared in a `gradle.properties` file present in a subproject directory are only available to that project and its children.

[[sec:gradle_environment_variables]]
== 4. Environment variables

The following environment variables are available for the `gradle` command.

`GRADLE_HOME`::
Installation directory for Gradle.
+
Can be used to specify a local Gradle version instead of using the wrapper.
+
You can add `GRADLE_HOME/bin` to your `PATH` for specific applications and use-cases (such as testing an early release for Gradle).

`JAVA_OPTS`::
Used to pass JVM options and custom settings to the JVM.

`GRADLE_OPTS`::
Specifies JVM arguments to use when starting the Gradle client VM.
+
The client VM only handles command line input/output, so it is rare that one would need to change its VM options.
+
The actual build is run by the Gradle daemon, which is not affected by this environment variable.

`<<directory_layout.adoc#dir:gradle_user_home,GRADLE_USER_HOME>>`::
Specifies the `GRADLE_USER_HOME` directory for Gradle to store its global configuration properties, initialization scripts, caches, log files and more.
+
Defaults to `USER_HOME/.gradle` if not set.

`JAVA_HOME`::
Specifies the JDK installation directory to use for the client VM.
+
This VM is also used for the daemon unless a different one is specified in a Gradle properties file with `org.gradle.java.home`.

`GRADLE_LIBS_REPO_OVERRIDE`::
Overrides for the default Gradle library repository.
+
Can be used to specify a default Gradle repository URL in `org.gradle.plugins.ide.internal.resolver`.
+
Useful override to specify an internally hosted repository in case your company uses a firewall/proxy.


The following examples demonstrate how to use environment variables.

*Example 1:* Reading environment variables at configuration time:
====
include::sample[dir="snippets/tutorial/environmentVariables/kotlin",files="init.gradle.kts[];settings.gradle.kts[];build.gradle.kts[tags=configuration]"]
include::sample[dir="snippets/tutorial/environmentVariables/groovy",files="init.gradle[];settings.gradle[];build.gradle[tags=configuration]"]
====

*Example 2:* Reading environment variables for consumption at execution time:
====
include::sample[dir="snippets/tutorial/environmentVariables/kotlin",files="build.gradle.kts[tags=execution]"]
include::sample[dir="snippets/tutorial/environmentVariables/groovy",files="build.gradle[tags=execution]"]
====
