<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

[.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, 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 applied in following order (if an option is configured in multiple locations the _last one wins_):

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

For multi-project builds you can place `gradle.properties` files in any subproject directory; however, it is recommended to place one `gradle.properties` file in the project root.

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, using the build cache>>.
`org.gradle.configureondemand=(true,false)`::
Enables incubating <<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 <<sec:command_line_logging, command-line logging>> for additional details.
`org.gradle.daemon=(true,false)`::
When set to `true` the <<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 used if the setting is unspecified.
`org.gradle.jvmargs=(JVM arguments)`::
Specifies the JVM arguments used for the forked processes like the Gradle Daemon and workers. The setting is particularly useful for <<sec:configuring_jvm_memory,configuring JVM memory settings>> for build performance.
`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 <<sec: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. For limitations of this option please see <<sec:parallel_execution>>.
`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 <<sec:command_line_performance, performance command-line options>>.

The following example demonstrates usage of various properties.

++++
<sample id="properties" dir="userguide/tutorial/properties" title="Setting properties with a gradle.properties file">
    <sourcefile file="gradle.properties"/>
    <sourcefile file="build.gradle"/>
    <output args="-q -PcommandLineProjectProp=commandLineProjectPropValue -Dorg.gradle.project.systemProjectProp=systemPropertyValue printProps"/>
</sample>
++++

You can use link:https://scans.gradle.com[build scans] to see what the build environment was for a given build using `--scan`.

image:img/build-scan-infrastructure.png[Build Environment in build scan]

[[sec:configuring_jvm_memory]]
=== Configuring JVM memory

Gradle defaults to 1024 megabytes maximum heap per JVM process (`-Xmx1024m`), however, that may be too much or too little depending on the size of your project. There are many JVM options (this link:https://dzone.com/articles/java-performance-tuning[blog post on Java performance tuning] and link:http://www.oracle.com/technetwork/java/javase/tech/vmoptions-jsp-140102.html[this reference] may be helpful).

You can adjust JVM options for Gradle in the following ways:

The `JAVA_OPTS` environment variable is used for the Gradle client, but not forked JVMs.

.Changing JVM settings for Gradle client JVM
====
[source,properties]
----
JAVA_OPTS="-Xmx2g -XX:MaxPermSize=256m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8"
----
====

You need to use the `org.gradle.jvmargs` Gradle property to configure JVM settings for forked JVM processes, including the Gradle Daemon and worker processes executed through api:org.gradle.workers.WorkerExecutor[]

.Changing JVM settings for forked Gradle JVMs
====
[source,properties]
----
org.gradle.jvmargs=-Xmx2g -XX:MaxPermSize=256m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8
----
====

[NOTE]
====
Many settings (like the Java version and maximum heap size) can only be specified when launching a new JVM for the build process. This means that Gradle must launch a separate JVM process to execute the build after parsing the various `gradle.properties` files.

When running with the daemon, a JVM with the correct parameters is started once and reused for each daemon build execution. When Gradle is executed without the daemon, then a new JVM must be launched for every build execution, unless the JVM launched by the Gradle start script happens to have the same parameters.
====

When using api:org.gradle.api.tasks.testing.Test#setMaxParallelForks[] for JUnit or TestNG tests, Gradle will fork test worker JVMs that you can configure through the `test` task. See examples in the api:org.gradle.api.tasks.testing.Test[] API documentation and <<sec:test_execution>>.

[[sec:gradle_system_properties]]
=== System properties
<commit_msg>Okay a little more polish for build env chapter<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

[.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, 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 applied in following order (if an option is configured in multiple locations the _last one wins_):

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

For multi-project builds you can place `gradle.properties` files in any subproject directory; however, it is recommended to place one `gradle.properties` file in the project root.

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, using the build cache>>.
`org.gradle.configureondemand=(true,false)`::
Enables incubating <<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 <<sec:command_line_logging, command-line logging>> for additional details.
`org.gradle.daemon=(true,false)`::
When set to `true` the <<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 used if the setting is unspecified.
`org.gradle.jvmargs=(JVM arguments)`::
Specifies the JVM arguments used for the forked processes like the Gradle Daemon and workers. The setting is particularly useful for <<sec:configuring_jvm_memory,configuring JVM memory settings>> for build performance.
`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 <<sec: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. For limitations of this option please see <<sec:parallel_execution>>.
`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 <<sec:command_line_performance, performance command-line options>>.

The following example demonstrates usage of various properties.

++++
<sample id="properties" dir="userguide/tutorial/properties" title="Setting properties with a gradle.properties file">
    <sourcefile file="gradle.properties"/>
    <sourcefile file="build.gradle"/>
    <output args="-q -PcommandLineProjectProp=commandLineProjectPropValue -Dorg.gradle.project.systemProjectProp=systemPropertyValue printProps"/>
</sample>
++++

You can use link:https://scans.gradle.com[build scans] to see what the build environment was for a given build using `--scan`.

image:img/build-scan-infrastructure.png[Build Environment in build scan]

[[sec:configuring_jvm_memory]]
=== Configuring JVM memory

Gradle defaults to 1024 megabytes maximum heap per JVM process (`-Xmx1024m`), however, that may be too much or too little depending on the size of your project. There are many JVM options (this link:https://dzone.com/articles/java-performance-tuning[blog post on Java performance tuning] and link:http://www.oracle.com/technetwork/java/javase/tech/vmoptions-jsp-140102.html[this reference] may be helpful).

You can adjust JVM options for Gradle in the following ways:

The `JAVA_OPTS` environment variable is used for the Gradle client, but not forked JVMs.

.Changing JVM settings for Gradle client JVM
====
[source,properties]
----
JAVA_OPTS="-Xmx2g -XX:MaxPermSize=256m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8"
----
====

You need to use the `org.gradle.jvmargs` Gradle property to configure JVM settings for forked JVM processes, including the Gradle Daemon and worker processes executed through api:org.gradle.workers.WorkerExecutor[].

.Changing JVM settings for forked Gradle JVMs
====
[source,properties]
----
org.gradle.jvmargs=-Xmx2g -XX:MaxPermSize=256m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8
----
====

[NOTE]
====
Many settings (like the Java version and maximum heap size) can only be specified when launching a new JVM for the build process. This means that Gradle must launch a separate JVM process to execute the build after parsing the various `gradle.properties` files.

When running with the daemon, a JVM with the correct parameters is started once and reused for each daemon build execution. When Gradle is executed without the daemon, then a new JVM must be launched for every build execution, unless the JVM launched by the Gradle start script happens to have the same parameters.
====

When using api:org.gradle.api.tasks.testing.Test#setMaxParallelForks[] for JUnit or TestNG tests, Gradle will fork test worker JVMs that you can configure through the `test` task. See examples in the api:org.gradle.api.tasks.testing.Test[] API documentation and <<sec:test_execution, test execution in the Java plugin reference>>.

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

{'fraction_non_alphanumeric': 0.0844508880028996, 'fraction_numerical': 0.005920019330675366, 'mean_word_length': 5.273209549071618, 'pattern_counts': {'":': 0, '<': 69, '<?xml version=': 0, '>': 69, 'https://': 4, 'lorem ipsum': 0, 'www.': 4, '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': '6958013', 'n_tokens_mistral': 4511, 'n_tokens_neox': 4311, 'n_words': 1995}