<!--
  ~ Copyright 2012 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.
  -->
<chapter id='build_environment'>
    <title>The Build Environment</title>

    <section id="sec:gradle_configuration_properties">
        <title>Configuring the build environment via gradle.properties</title>
        <para>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,
            certain settings like JVM memory settings, Java home, daemon on/off
            can be more useful if they can be versioned with the project in your VCS so that
            the 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 <filename>gradle.properties</filename> file.
            The configuration is applied in following order
            (if an option is configured in multiple locations the last one wins):
            <itemizedlist>
                <listitem>from <filename>gradle.properties</filename> in project build dir.</listitem>
                <listitem>from <filename>gradle.properties</filename> in <literal>gradle user home</literal>.</listitem>
                <listitem>from system properties, e.g. when <literal>-Dsome.property</literal> is set on the command line.</listitem>
            </itemizedlist>
        </para>
        <para>When setting these properties you should keep in mind that Gradle requires a Java JDK or JRE of version 7 or higher to run.
        </para>
        <para>
            The following properties can be used to configure the Gradle build environment:
            <varlistentry>
                <term><literal>org.gradle.daemon</literal></term>
                <listitem><para>When set to <literal>true</literal> the Gradle daemon is used to run the build.
                    For local developer builds this is our favorite property. The developer environment is optimized for speed and feedback
                    so we nearly always run Gradle jobs with the daemon.
                    We don't run CI builds with the daemon (i.e. a long running process)
                    as the CI environment is optimized for consistency and reliability.
                </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><literal>org.gradle.java.home</literal></term>
                <listitem><para>Specifies the Java home for the Gradle build process.
                    The value can be set to either a <literal>jdk</literal> or <literal>jre</literal> location,
                    however, depending on what your build does, <literal>jdk</literal> is safer.
                    A reasonable default is used if the setting is unspecified.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><literal>org.gradle.jvmargs</literal></term>
                <listitem><para>Specifies the jvmargs used for the daemon process.
                    The setting is particularly useful for tweaking memory settings.
                    At the moment the default settings are pretty generous with regards to memory.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><literal>org.gradle.configureondemand</literal></term>
                <listitem><para>Enables new incubating mode that makes Gradle selective when configuring projects.
                    Only relevant projects are configured which results in faster builds for large multi-projects.
                    See <xref linkend="sec:configuration_on_demand"/>.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><literal>org.gradle.parallel</literal></term>
                <listitem><para>When configured, Gradle will run in incubating parallel mode.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><literal>org.gradle.workers.max</literal></term>
                <listitem><para>When configured, Gradle will use a maximum of the given number of workers.  See <literal>--max-workers</literal> for details.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><literal>org.gradle.debug</literal></term>
                <listitem><para>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 <literal>-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005</literal> to
                    the JVM command line and will suspend the virtual machine until a debugger is attached.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><literal>org.gradle.daemon.performance.enable-monitoring</literal></term>
                <listitem><para>When set to false, Gradle will not monitor the memory usage of running daemons. See <xref linkend="sec:what_can_go_wrong_with_daemon"/>.</para>
                </listitem>
            </varlistentry>
        </para>
        <section id="sec:forked_java_processes">
            <title>Forked Java processes</title>
            <para>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 <filename>gradle.properties</filename> 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.
            </para>
            <para>
            This launching of an extra JVM on every build execution is quite expensive, which is why if you are
            setting either <literal>org.gradle.java.home</literal> or <literal>org.gradle.jvmargs</literal>
            we highly recommend that you use the Gradle Daemon. See <xref linkend="gradle_daemon"/> for more details.</para>
        </section>
    </section>
    <section id="sec:gradle_properties_and_system_properties">
        <title>Gradle properties and system properties</title>
        <para>Gradle offers a variety of ways to add properties to your build. With the <option>-D</option> command line
            option you can pass a system property to the JVM which runs Gradle. The <option>-D</option> option of the
            <command>gradle</command> command has the same effect as the <option>-D</option> option of the
            <command>java</command> command.
        </para>
        <para>You can also add properties to your project objects using properties files. You can place a
            <filename>gradle.properties</filename> file in the Gradle user home directory (defined by the
            “<literal>GRADLE_USER_HOME</literal>” environment variable, which if not set defaults to
            <filename><replaceable>USER_HOME</replaceable>/.gradle</filename>) or in your project directory. For
            multi-project builds you can place <filename>gradle.properties</filename> files in any subproject directory.
            The properties set in a <filename>gradle.properties</filename> file can be accessed via the project object. The
            properties file in the user's home directory has precedence over property files in the project directories.
        </para>
        <para>You can also add properties directly to your project object via the <option>-P</option> command line option.
        </para>
        <para>Gradle can also set project properties when it sees specially-named system properties or
            environment variables. This feature is very useful when you don't have admin rights to a continuous integration
            server and you need to set property values that should not be easily visible, typically for security reasons.
            In that situation, you can't use the <option>-P</option> option, and you can't change the system-level
            configuration files.  The correct strategy is to change the configuration of your continuous integration
            build job, adding an environment variable setting that matches an expected pattern.  This won't be visible
            to normal users on the system.
            <footnote>
                <para>
                    <emphasis>Jenkins</emphasis>, <emphasis>Teamcity</emphasis>, or <emphasis>Bamboo</emphasis> are some CI servers which offer this functionality.
                </para>
            </footnote>
        </para>
        <para>
            If the environment variable name looks like
            <literal>ORG_GRADLE_PROJECT_<replaceable>prop</replaceable>=somevalue</literal>,
            then Gradle will set a <literal>prop</literal> property on your project object, with the value
            of <literal>somevalue</literal>. Gradle also supports this for
            system properties, but with a different naming pattern, which looks like
            <literal>org.gradle.project.<replaceable>prop</replaceable></literal>.
        </para>
        <para>You can also set system properties in the <filename>gradle.properties</filename> file. If a property
            name in such a file has the prefix “<literal>systemProp.</literal>”, like “<literal>systemProp.propName</literal>”,
            then the property and its value will be set as a system property, without the prefix. In a multi project
            build, “<literal>systemProp.</literal>” properties set in any project except the root will be ignored.
            That is, only the root project's <filename>gradle.properties</filename> file will be checked for
            properties that begin with the “<literal>systemProp.</literal>” prefix.
        </para>
        <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>
        <section id="sub:checking_for_project_properties">
            <title>Checking for project properties</title>
            <para>You can access a project property in your build script simply by using its name as you would use a
                variable. If this property does not exist, an exception will be thrown and the build will fail. If your
                build script relies on optional properties the user might set, perhaps in a <literal>gradle.properties</literal> file,
                you need to check for existence before you access them. You can do this by using the method
                <literal>hasProperty('propertyName')</literal>
                which returns
                <literal>true</literal>
                or <literal>false</literal>.
            </para>
        </section>
    </section>

    <section id="sec:accessing_the_web_via_a_proxy">
        <title>Accessing the web via a proxy</title>
        <para>Configuring an HTTP or HTTPS proxy (for downloading dependencies, for example) is done via standard JVM system
        properties. These properties can be set directly in the build script; for example, setting the HTTP proxy host
        would be done with <literal>System.setProperty('http.proxyHost', 'www.somehost.org')</literal>.
        Alternatively, the properties can be specified in a gradle.properties file, either in the build's root
        directory or in the Gradle home directory.
        </para>
        <example>
            <title>Configuring an HTTP proxy</title>
            <para><filename>gradle.properties</filename></para>
            <programlisting><![CDATA[
systemProp.http.proxyHost=www.somehost.org
systemProp.http.proxyPort=8080
systemProp.http.proxyUser=userid
systemProp.http.proxyPassword=password
systemProp.http.nonProxyHosts=*.nonproxyrepos.com|localhost
]]></programlisting>
        </example>
        <para>There are separate settings for HTTPS.</para>
        <example>
            <title>Configuring an HTTPS proxy</title>
            <para><filename>gradle.properties</filename></para>
            <programlisting><![CDATA[
systemProp.https.proxyHost=www.somehost.org
systemProp.https.proxyPort=8080
systemProp.https.proxyUser=userid
systemProp.https.proxyPassword=password
systemProp.http.nonProxyHosts=*.nonproxyrepos.com|localhost
]]></programlisting>
        </example>
        <para>We could not find a good overview for all possible proxy settings. One place to look are the constants
            in a file from the Ant project. Here's a
            <ulink url='http://svn.apache.org/viewvc/ant/core/trunk/src/main/org/apache/tools/ant/util/ProxySetup.java?view=markup&amp;pathrev=556977'>
                link
            </ulink> to the Subversion view. The other is a
            <ulink url='http://download.oracle.com/javase/6/docs/technotes/guides/net/properties.html'>
                Networking Properties page
            </ulink> from the JDK docs. If anyone knows of a better overview, please let us know via the mailing list.
        </para>
        <section id="sub:ntlm_authentication">
            <title>NTLM Authentication</title>
            <para>If your proxy requires NTLM authentication, you may need to provide the authentication domain as well as the username and password.
                There are 2 ways that you can provide the domain for authenticating to a NTLM proxy:
                <itemizedlist>
                    <listitem>Set the <literal>http.proxyUser</literal> system property to a value like <literal><replaceable>domain</replaceable>/<replaceable>username</replaceable></literal>.
                    </listitem>
                    <listitem>Provide the authentication domain via the <literal>http.auth.ntlm.domain</literal> system property.
                    </listitem>
                </itemizedlist>
            </para>
        </section>
    </section>
</chapter>
