<commit_before>// 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.

[[build_environment]]
= Build Environment

TIP: Interested in configuring your Build Cache to speed up builds? https://gradle.com/training/build-cache-deep-dive/?bid=docs-build-environment[Register here] for our Build Cache training session to learn some of the tips and tricks top engineering teams are using to increase build speed.

[.lead]
Gradle provides multiple mechanisms for configuring 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 (first one wins):

* <<command_line_interface.adoc#command_line_interface, Command-line flags>> such as `--build-cache`. These have precedence over properties and environment variables.
* <<#sec:gradle_system_properties, System properties>> such as `systemProp.http.proxyHost=somehost.org` stored in a `gradle.properties` file.
* <<#sec:gradle_configuration_properties, Gradle properties>> such as `org.gradle.caching=true` that are typically stored in a `gradle.properties` file in a project root directory or `GRADLE_USER_HOME` environment variable.
* <<#sec:gradle_environment_variables, Environment variables>> such as `GRADLE_OPTS` sourced by the environment that executes Gradle.

Aside from configuring the build environment, you can configure a given project build using <<#sec:project_properties, Project properties>> such as `-PreleaseType=final`.

[[sec:gradle_configuration_properties]]
== 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 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.

Setting up a consistent environment for your build is as simple as placing these settings into a `gradle.properties` file. The configuration is a combination of all your `gradle.properties` files, but if an option is configured in multiple locations, the _first one wins_:

* system properties, e.g. when `-Dgradle.user.home` is set on the command line.
* `gradle.properties` in `GRADLE_USER_HOME` directory.
* `gradle.properties` in project root directory.
* `gradle.properties` in Gradle installation directory.

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, resulting is much faster builds. Learn more about <<build_cache.adoc#build_cache, using the build cache>>.

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

`org.gradle.configureondemand=(true,false)`::
Enables incubating <<multi_project_builds.adoc#sec:configuration_on_demand, configuration on demand>>, where Gradle will attempt to configure only necessary projects.

`org.gradle.console=(auto,plain,rich,verbose)`::
Customize console output coloring or verbosity. Default depends on how Gradle is invoked. See <<command_line_interface.adoc#sec:command_line_logging, command-line logging>> for additional details.

`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.idletimeout=(# of idle millis)`::
Gradle Daemon will terminate itself after specified number of idle milliseconds. Default is `10800000` (3 hours).

`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 the equivalent of 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.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. A reasonable default is derived from your environment (`JAVA_HOME` or the path to `java`) if the setting is unspecified. This does not affect the version of Java used to launch the Gradle client VM (<<#sec:gradle_environment_variables, see Environment variables>>).

`org.gradle.jvmargs=(JVM arguments)`::
Specifies the JVM arguments used for the Gradle Daemon. The setting is particularly useful for <<#sec:configuring_jvm_memory,configuring JVM memory settings>> for build performance. This does not affect the JVM settings for the Gradle client VM.

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

`org.gradle.parallel=(true,false)`::
When configured, Gradle will fork up to `org.gradle.workers.max` JVMs to execute projects in parallel. To learn more about parallel task execution, see link:https://guides.gradle.org/performance/#parallel_execution[the Gradle performance guide].

`org.gradle.priority=(low,normal)`::
Specifies the scheduling priority for the Gradle daemon and all processes launched by it. Default is `normal`. See also <<command_line_interface.adoc#sec:command_line_performance, performance command-line options>>.

`org.gradle.vfs.watch=(true,false)`::
Toggles <<gradle_daemon.adoc#sec:daemon_watch_fs,watching the file system>>.
Allows Gradle to re-use information about the file system in the next build.
_Default is off_.

`org.gradle.warning.mode=(all,fail,summary,none)`::
When set to `all`, `summary` or `none`, Gradle will use different warning type display. See <<command_line_interface.adoc#sec:command_line_logging,Command-line logging options>> for details.

`org.gradle.workers.max=(max # of worker processes)`::
When configured, Gradle will use a maximum of the given number of workers. Default is number of CPU processors. See also <<command_line_interface.adoc#sec:command_line_performance, performance command-line options>>.

The following example demonstrates usage of various properties.

.Setting properties with a gradle.properties file
====
include::sample[dir="snippets/tutorial/properties/groovy",files="gradle.properties[]"]
====

====
include::sample[dir="snippets/tutorial/properties/groovy",files="build.gradle[]"]
include::sample[dir="snippets/tutorial/properties/kotlin",files="build.gradle.kts[]"]
====

----
$ gradle -q -PcommandLineProjectProp=commandLineProjectPropValue -Dorg.gradle.project.systemProjectProp=systemPropertyValue printProps
include::{snippetsPath}/tutorial/properties/tests/properties.out[]
----
<commit_msg>Mention verbose VFS logging in build environment<commit_after>// 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.

[[build_environment]]
= Build Environment

TIP: Interested in configuring your Build Cache to speed up builds? https://gradle.com/training/build-cache-deep-dive/?bid=docs-build-environment[Register here] for our Build Cache training session to learn some of the tips and tricks top engineering teams are using to increase build speed.

[.lead]
Gradle provides multiple mechanisms for configuring 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 (first one wins):

* <<command_line_interface.adoc#command_line_interface, Command-line flags>> such as `--build-cache`. These have precedence over properties and environment variables.
* <<#sec:gradle_system_properties, System properties>> such as `systemProp.http.proxyHost=somehost.org` stored in a `gradle.properties` file.
* <<#sec:gradle_configuration_properties, Gradle properties>> such as `org.gradle.caching=true` that are typically stored in a `gradle.properties` file in a project root directory or `GRADLE_USER_HOME` environment variable.
* <<#sec:gradle_environment_variables, Environment variables>> such as `GRADLE_OPTS` sourced by the environment that executes Gradle.

Aside from configuring the build environment, you can configure a given project build using <<#sec:project_properties, Project properties>> such as `-PreleaseType=final`.

[[sec:gradle_configuration_properties]]
== 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 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.

Setting up a consistent environment for your build is as simple as placing these settings into a `gradle.properties` file. The configuration is a combination of all your `gradle.properties` files, but if an option is configured in multiple locations, the _first one wins_:

* system properties, e.g. when `-Dgradle.user.home` is set on the command line.
* `gradle.properties` in `GRADLE_USER_HOME` directory.
* `gradle.properties` in project root directory.
* `gradle.properties` in Gradle installation directory.

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, resulting is much faster builds. Learn more about <<build_cache.adoc#build_cache, using the build cache>>.

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

`org.gradle.configureondemand=(true,false)`::
Enables incubating <<multi_project_builds.adoc#sec:configuration_on_demand, configuration on demand>>, where Gradle will attempt to configure only necessary projects.

`org.gradle.console=(auto,plain,rich,verbose)`::
Customize console output coloring or verbosity. Default depends on how Gradle is invoked. See <<command_line_interface.adoc#sec:command_line_logging, command-line logging>> for additional details.

`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.idletimeout=(# of idle millis)`::
Gradle Daemon will terminate itself after specified number of idle milliseconds. Default is `10800000` (3 hours).

`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 the equivalent of 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.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. A reasonable default is derived from your environment (`JAVA_HOME` or the path to `java`) if the setting is unspecified. This does not affect the version of Java used to launch the Gradle client VM (<<#sec:gradle_environment_variables, see Environment variables>>).

`org.gradle.jvmargs=(JVM arguments)`::
Specifies the JVM arguments used for the Gradle Daemon. The setting is particularly useful for <<#sec:configuring_jvm_memory,configuring JVM memory settings>> for build performance. This does not affect the JVM settings for the Gradle client VM.

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

`org.gradle.parallel=(true,false)`::
When configured, Gradle will fork up to `org.gradle.workers.max` JVMs to execute projects in parallel. To learn more about parallel task execution, see link:https://guides.gradle.org/performance/#parallel_execution[the Gradle performance guide].

`org.gradle.priority=(low,normal)`::
Specifies the scheduling priority for the Gradle daemon and all processes launched by it. Default is `normal`. See also <<command_line_interface.adoc#sec:command_line_performance, performance command-line options>>.

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

`org.gradle.vfs.watch=(true,false)`::
Toggles <<gradle_daemon.adoc#sec:daemon_watch_fs,watching the file system>>.
Allows Gradle to re-use information about the file system in the next build.
_Default is off_.

`org.gradle.warning.mode=(all,fail,summary,none)`::
When set to `all`, `summary` or `none`, Gradle will use different warning type display. See <<command_line_interface.adoc#sec:command_line_logging,Command-line logging options>> for details.

`org.gradle.workers.max=(max # of worker processes)`::
When configured, Gradle will use a maximum of the given number of workers. Default is number of CPU processors. See also <<command_line_interface.adoc#sec:command_line_performance, performance command-line options>>.

The following example demonstrates usage of various properties.

.Setting properties with a gradle.properties file
====
include::sample[dir="snippets/tutorial/properties/groovy",files="gradle.properties[]"]
====

====
include::sample[dir="snippets/tutorial/properties/groovy",files="build.gradle[]"]
include::sample[dir="snippets/tutorial/properties/kotlin",files="build.gradle.kts[]"]
====

----
$ gradle -q -PcommandLineProjectProp=commandLineProjectPropValue -Dorg.gradle.project.systemProjectProp=systemPropertyValue printProps
include::{snippetsPath}/tutorial/properties/tests/properties.out[]
----

{'fraction_non_alphanumeric': 0.09044357677782756, 'fraction_numerical': 0.003200409652435512, 'mean_word_length': 5.688356164383562, 'pattern_counts': {'":': 0, '<': 73, '<?xml version=': 0, '>': 73, 'https://': 4, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7662216', 'n_tokens_mistral': 4304, 'n_tokens_neox': 4084, 'n_words': 1746}