<!--
  ~ 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.
  -->
<chapter id="tutorial_gradle_command_line">
    <title>Using the Gradle Command-Line</title>
    <para>This chapter introduces the basics of the Gradle command-line. You run a build using the
        <command>gradle</command> command, which you have already seen in action in previous chapters.</para>

    <section>
        <title>Executing multiple tasks</title>
        <para>You can execute multiple tasks in a single build by listing each of the tasks on the command-line. For example,
            the command <userinput>gradle compile test</userinput> will execute the <literal>compile</literal> and
            <literal>test</literal> tasks. Gradle will execute the tasks in the order that they are listed on the
            command-line, and will also execute the dependencies for each task. Each task is executed once only,
            regardless of why it is included in the build: whether it was specified on the command-line, or it a
            dependency of another task, or both. Let's look at an example.</para>
        <para>
            Below four tasks are defined. Both <literal>dist</literal> and <literal>test</literal> depend on the
            <literal>compile</literal> task. Running <userinput>gradle dist test</userinput> for this build script
            results in the <literal>compile</literal> task being executed only once.</para>
        <figure>
            <title>Task dependencies</title>
            <imageobject>
                <imagedata fileref="images/commandLineTutorialTasks.png"/>
            </imageobject>
        </figure>
        <sample id="multipleTasksFromCommandLine" dir="userguide/tutorial/excludeTasks" title="Executing multiple tasks">
            <sourcefile file="build.gradle"/>
            <output args="dist test"/>
        </sample>
        <para>
            Because each task is executed once only, executing <userinput>gradle test test</userinput> is exactly the same
            as executing <userinput>gradle test</userinput>.</para>
    </section>

    <section id="sec:excluding_tasks_from_the_command_line">
        <title>Excluding tasks</title>
        <para>You can exclude a task from being executed using the <option>-x</option> command-line option and providing
            the name of the task to exclude. Let's try this with the sample build file above.</para>
        <sample id="excludeTask" dir="userguide/tutorial/excludeTasks" title="Excluding tasks">
            <output args="dist -x test"/>
        </sample>
        <para>You can see from the output of this example, that the <literal>test</literal> task is not executed, even
            though it is a dependency of the <literal>dist</literal> task. You will also notice that the
            <literal>test</literal> task's dependencies, such as <literal>compileTest</literal>
            are not executed either. Those dependencies of <literal>test</literal> that are required by another task, such as
            <literal>compile</literal>, are still executed.</para>
    </section>

    <section>
        <title>Task name abbreviation</title>
        <para>When you specify tasks on the command-line, you don't have to provide the full name of the task. You only need to provide enough of the
            task name to uniquely identify the task. For example, in the sample build above, you can execute task
            <literal>dist</literal> by running <userinput>gradle d</userinput>:</para>
        <sample id="abbreviateTaskName" dir="userguide/tutorial/excludeTasks" title="Abbreviated task name">
            <output args="d"/>
        </sample>
        <para>You can also abbreviate each word in a camel case task name. For example, you can execute task <literal>compileTest</literal>
            by running <userinput>gradle compTest</userinput> or even <userinput>gradle cT</userinput></para>
        <sample id="abbreviateCamelCaseTaskName" dir="userguide/tutorial/excludeTasks" title="Abbreviated camel case task name">
            <output args="cT"/>
        </sample>
        <para>You can also use these abbreviations with the <option>-x</option> command-line option.</para>
    </section>

    <section>
        <title>Selecting which build to execute</title>
        <para>When you run the <command>gradle</command> command, it looks for a build file in the current directory.
            You can use the <option>-b</option> option to select another build file. For example:
        </para>
        <sample id="selectProjectUsingBuildFile" dir="userguide/tutorial/selectProject" title="Selecting the project using a build file">
            <sourcefile file="subdir/myproject.gradle"/>
            <output args="-q -b subdir/myproject.gradle hello"/>
        </sample>
        <para>Alternatively, you can use the <option>-p</option> option to specify the project directory to use:</para>
        <sample id="selectProjectUsingProjectDir" dir="userguide/tutorial/selectProject" title="Selecting the project using project directory">
            <output args="-q -p subdir hello"/>
        </sample>
    </section>

    <section>
        <title>Obtaining information about your build</title>
        <para>Gradle provides several command-line options which show particular details of your build. This can be
            useful for understanding the structure and dependencies of your build, and for debugging problems.
        </para>
        <para>Running <userinput>gradle --tasks</userinput>
            gives you a list of the tasks which make up the build, broken down by project. This report shows the default
            tasks, if any, of each project, and the description and dependencies of each task. Below is an example of
            this report:
        </para>
        <sample id="taskListReport" dir="userguide/tutorial/projectReports" title="Obtaining information about tasks">
            <output args="-q --tasks"/>
        </sample>
        <para id="para:commandline_dependency_report">Running <userinput>gradle --dependencies</userinput>
            gives you a list of the dependencies of the build, broken down by project. This report shows the
            configurations of each project. For each configuration, the direct and transitive dependencies of that
            configuration are shown. Below is an example of this report:
        </para>
        <sample id="dependencyListReport" dir="userguide/tutorial/projectReports" title="Obtaining information about dependencies">
            <output args="-q --dependencies"/>
        </sample>
        <para>Running <userinput>gradle --properties</userinput> gives you a list of the properties of each project in
            the build.
        </para>
        <!--<sample id="propertyListReport" dir="userguide/tutorial/projectReports" title="Information about properties">-->
            <!--<output args="-q - -properties"/>-->
        <!--</sample>-->
        <para>You can also use the <link linkend="project_reports_plugin">project report plugin</link> to add a
            number of reporting tasks to your project.
        </para>
    </section>

    <section>
        <title>Dry Run</title>
        <para>Sometimes you are interested in which tasks are executed in which order for a given set of tasks specified on the
            command line, but you don't want the tasks to be executed. You can use the <option>-m</option> option for this.
            For example <userinput>gradle -m clean compile</userinput> shows you all tasks to be executed as
            part of the <literal>clean</literal> and <literal>compile</literal> tasks.
            This is complementary to the <option>-t</option>, which shows you all available tasks for execution.
        </para>
    </section>

    <section>
        <title>Summary</title>
        <para>In this chapter, you have seen some of the things you can do with Gradle from the command-line. You can
            find out more about the <command>gradle</command> command in <xref linkend="gradle_command_line"/>.</para>
    </section>
</chapter>
