<!--
  ~ Copyright 2009 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.
  -->
<appendix id='gradle_command_line'>
    <title>Gradle Command Line</title>
    <para>The <command>gradle</command> command has the following usage:
        <cmdsynopsis>
            <command>gradle</command>
            <arg choice="opt" rep="repeat">option</arg>
            <arg choice="opt" rep="repeat">task</arg>
        </cmdsynopsis>
        The command-line options available for the <command>gradle</command> command are listed below:
    </para>
    <variablelist>
        <varlistentry>
            <term><option>-?</option>, <option>-h</option>, <option>--help</option></term>
            <listitem><para>Shows a help message.</para></listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-C</option>, <option>--cache</option></term>
            <listitem><para>Specifies how compiled build scripts should be cached. Possible values are:
                <literal>rebuild</literal> or <literal>on</literal>. Default value is
                <literal>on</literal>. See <xref linkend="sec:caching"/>.
            </para></listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-D</option>, <option>--system-prop</option></term>
            <listitem><para>Sets a system property of the JVM, for example <literal>-Dmyprop=myvalue</literal>.
            </para></listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-I</option>, <option>--init-script</option></term>
            <listitem><para>Specifies an initialization script. See <xref linkend="init_scripts"/>.</para></listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-P</option>, <option>--project-prop</option></term>
            <listitem><para>Sets a project property of the root project, for example
                <literal>-Pmyprop=myvalue</literal>.
            </para></listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-S</option>, <option>--full-stacktrace</option></term>
            <listitem><para>Print out the full (very verbose) stacktrace for any exceptions. See <xref linkend="logging"/>.
            </para></listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-a</option>, <option>--no-rebuild</option></term>
            <listitem><para>Do not rebuild project dependencies.
            </para></listitem>
        </varlistentry>
        <varlistentry>
            <term><option>--all</option></term>
            <listitem><para>Shows additional detail in the task listing. See <xref linkend="sec:listing_tasks"/>.
            </para></listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-b</option>, <option>--build-file</option></term>
            <listitem><para>Specifies the build file. See <xref linkend="sec:selecting_build"/>.
            </para></listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-c</option>, <option>--settings-file</option></term>
            <listitem><para>Specifies the settings file.</para></listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-d</option>, <option>--debug</option></term>
            <listitem><para>Log in debug mode (includes normal stacktrace). See <xref linkend="logging"/>.
            </para></listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-e</option>, <option>--embedded</option></term>
            <listitem><para>Specify an embedded build script.
            </para></listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-g</option>, <option>--gradle-user-home</option></term>
            <listitem><para>Specifies the Gradle user home directory.
            </para></listitem>
        </varlistentry>
        <varlistentry>
            <term><option>--gui</option></term>
            <listitem><para>Launches the Gradle GUI. See <xref linkend="tutorial_gradle_gui"/>.
            </para></listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-i</option>, <option>--info</option></term>
            <listitem><para>Set log level to info. See <xref linkend="logging"/>.
            </para></listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-m</option>, <option>--dry-run</option></term>
            <listitem><para>Runs the build with all task actions disabled.</para> </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>--no-color</option></term>
            <listitem><para>Do not use color in the console output.</para></listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-p</option>, <option>--project-dir</option></term>
            <listitem><para>Specifies the start directory for Gradle. Defaults to current directory.
                See <xref linkend="sec:selecting_build"/>.
            </para></listitem>
        </varlistentry>
        <varlistentry>
            <term><option>--profile</option></term>
            <listitem><para>Profiles build execution time and generates a report in the
                &lt;build_dir>/reports/profile directory.
            </para></listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-q</option>, <option>--quiet</option></term>
            <listitem><para>Log errors only. See <xref linkend="logging"/>.</para></listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-s</option>, <option>--stacktrace</option></term>
            <listitem><para>Print out the stacktrace also for user exceptions (e.g. compile error). See <xref linkend="logging"/>.
            </para></listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-u</option>, <option>--no-search-upwards</option></term>
            <listitem><para>Don't search in parent directories for a <filename>settings.gradle</filename> file.
            </para></listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-v</option>, <option>--version</option></term>
            <listitem><para>Prints version info.
            </para></listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-x</option>, <option>--exclude-task</option></term>
            <listitem><para>Specifies a task to be excluded from execution. See <xref linkend="sec:excluding_tasks_from_the_command_line"/>.
            </para></listitem>
        </varlistentry>
    </variablelist>
    <para>The above information is printed to the console when you execute <userinput>gradle -h</userinput>.</para>

    <section>
        <title>Deprecated command-line options</title>
        <para>The following options are deprecated and will be removed in a future version of Gradle:</para>
        <variablelist>
            <varlistentry>
                <term><option>-n</option>, <option>--dependencies</option></term>
                <listitem><para>(deprecated) Show list of all project dependencies. You should use <userinput>gradle dependencies</userinput>
                    instead. See <xref linkend="sec:listing_dependencies"/>.
                </para></listitem>
            </varlistentry>
            <varlistentry>
                <term><option>-r</option>, <option>--properties</option></term>
                <listitem><para>(deprecated) Show list of all available project properties. You should use <userinput>gradle properties</userinput>
                    instead. See <xref linkend="sec:listing_properties"/>.</para></listitem>
            </varlistentry>
            <varlistentry>
                <term><option>-t</option>, <option>--tasks</option></term>
                <listitem><para>(deprecated) Show list of available tasks. You should use <userinput>gradle tasks</userinput>
                    instead. See <xref linkend="sec:listing_tasks"/>.</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </section>

    <section>
        <title>Experimental command-line options</title>
        <para>The following options are experimental:</para>
        <variablelist>
            <varlistentry>
                <term><option>--daemon</option></term>
                <listitem><para>Uses the Gradle daemon to run the build. Starts the daemon if not running.</para></listitem>
            </varlistentry>
            <varlistentry>
                <term><option>--foreground</option></term>
                <listitem><para>Starts the Gradle daemon in the foreground.</para></listitem>
            </varlistentry>
            <varlistentry>
                <term><option>--no-daemon</option></term>
                <listitem><para>Do not use the Gradle daemon to run the build.</para></listitem>
            </varlistentry>
            <varlistentry>
                <term><option>--stop</option></term>
                <listitem><para>Stops the Gradle daemon if it is running.</para></listitem>
            </varlistentry>
        </variablelist>
    </section>

    <section>
        <title>System properties</title>
        <para>The following system properties are available for the <command>gradle</command> command. Note that
            command-line options take precedence over system properties.
        </para>
        <varlistentry>
            <term><literal>gradle.user.home</literal></term>
            <listitem><para>Specifies the Gradle user home directory.</para> </listitem>
        </varlistentry>
        <varlistentry>
            <term><literal>org.gradle.daemon</literal></term>
            <listitem><para>When set to <literal>true</literal>, use the Gradle daemon to run the build.</para>
            </listitem>
        </varlistentry>
    </section>

    <section>
        <title>Environment variables</title>
        <para>The following environment variables are available for the <command>gradle</command> command. Note that
            command-line options and system properties take precedence over environment variables.
        </para>
        <variablelist>
            <varlistentry>
                <term><literal>GRADLE_HOME</literal></term>
                <listitem><para>Specifies the root directory of the Gradle installation to use.</para></listitem>
            </varlistentry>
            <varlistentry>
                <term><literal>GRADLE_OPTS</literal></term>
                <listitem><para>Specifies command-line arguments to use to start the JVM. This can be useful for setting
                    the system properties to use for running Gradle. For example you could set <literal>GRADLE_OPTS="-Dorg.gradle.daemon=true"</literal>
                    to use the Gradle daemon without needing to use the <option>--daemon</option> option every time you
                    run Gradle.
                </para></listitem>
            </varlistentry>
            <varlistentry>
                <term><literal>GRADLE_USER_HOME</literal></term>
                <listitem><para>Specifies the Gradle user home directory.</para></listitem>
            </varlistentry>
        </variablelist>
    </section>
</appendix>
