<!--
  ~ 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 id="sec:executing_multiple_tasks">
        <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 how it came to be included in the build: whether it was specified on the command-line, or as 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="img/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>
            Each task is executed only once, so <userinput>gradle test test</userinput> is exactly the same
            as <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 id="sec:continue_build_on_failure">
        <title>Continuing the build when a failure occurs</title>
        <para>By default, Gradle will abort execution and fail the build as soon as any task fails. This allows the build to complete sooner, but hides other failures
            that would have occurred. In order to discover as many failures as possible in a single build execution, you can use the <literal>--continue</literal> option.
        </para>
        <para>When executed with <literal>--continue</literal>, Gradle will execute <emphasis>every</emphasis> task to be executed where all of the dependencies for that task completed without failure,
            instead of stopping as soon as the first failure is encountered. Each of the encountered failures will be reported at the end of the build.
        </para>
        <para>If a task fails, any subsequent tasks that were depending on it will not be executed, as it is not safe to do so. For example, tests will not
            run if there is a compilation failure in the code under test; because the test task will depend on the compilation task (either directly or indirectly).
        </para>
    </section>

    <section id="sec:task_name_abbreviation">
        <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="di"/>
        </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 id="sec:selecting_build">
        <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.
            If you use <option>-b</option> option then <filename>settings.gradle</filename> file is not used. 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.
        For multi-project builds you should use <option>-p</option> option instead of <option>-b</option> option.
        </para>
        <sample id="selectProjectUsingProjectDir" dir="userguide/tutorial/selectProject" title="Selecting the project using project directory">
            <output args="-q -p subdir hello"/>
        </sample>
    </section>

    <section id="sec:rerun_tasks">
        <title>Forcing tasks to execute</title>
        <para>
            Many tasks, particularly those provided by Gradle itself, support <link linkend="sec:up_to_date_checks">incremental builds</link>.
            Such tasks can determine whether they need to run or not based on whether their inputs or outputs have changed since the last
            time they ran. You can easily identify tasks that take part in incremental build when Gradle displays
            the text <literal>UP-TO-DATE</literal> next to their name during a build run.
        </para>
        <para>
            You may on occasion want to force Gradle to run all the tasks, ignoring any up-to-date checks. If that's the case, simply use
            the <literal>--rerun-tasks</literal> option. Here's the output when running a task both without and with <literal>--rerun-tasks</literal>:
        </para>
        <sample id="rerunTasks" dir="userguide/tutorial/rerun" title="Forcing tasks to run">
            <test args="doIt" />
            <output args="doIt" ignoreExtraLines="y" outputFile="noRerunTasks.out" />
            <output args="--rerun-tasks doIt" ignoreExtraLines="y" />
        </sample>
        <para>
            Note that this will force <emphasis>all</emphasis> required tasks to execute, not just the ones you specify on the command
            line. It's a little like running a <literal>clean</literal>, but without the build's generated output being deleted.
        </para>
    </section>

    <section id="sec:obtaining_information_about_your_build">
        <title>Obtaining information about your build</title>
        <para>Gradle provides several built-in tasks 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>In addition to the built-in tasks shown below, you can also use the
            <link linkend="project_reports_plugin">project report plugin</link> to add tasks to your project which will
            generate these reports.
        </para>
        <section id="sec:listing_projects">
            <title>Listing projects</title>
            <para>Running <userinput>gradle projects</userinput> gives you a list of the sub-projects of the selected project,
                displayed in a hierarchy. Here is an example:
            </para>
            <sample id="projectListReport" dir="userguide/tutorial/projectReports" title="Obtaining information about projects">
                <output args="-q projects"/>
            </sample>
            <para>The report shows the description of each project, if specified. You can provide a description for a project
                by setting the <literal>description</literal> property:
            </para>
            <sample id="projectListReport" dir="userguide/tutorial/projectReports" title="Providing a description for a project">
                <sourcefile file="build.gradle" snippet="project-description"/>
            </sample>
        </section>
        <section id="sec:listing_tasks">
            <title>Listing tasks</title>
            <para>Running <userinput>gradle tasks</userinput> gives you a list of the main tasks of the
                selected project. This report shows the default tasks for the project, if any, and a description for
                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>By default, this report shows only those tasks which have been assigned to a task group. You can do this
                by setting the <literal>group</literal> property for the task. You can also set the <literal>description</literal>
                property, to provide a description to be included in the report.
            </para>
            <sample id="taskListReport" dir="userguide/tutorial/projectReports" title="Changing the content of the task report">
                <sourcefile file="build.gradle" snippet="add-task-to-report"/>
            </sample>
            <para>You can obtain more information in the task listing using the <option>--all</option> option. With
                this option, the task report lists all tasks in the project, grouped by main task, and the dependencies
                for each task. Here is an example:
            </para>
            <sample id="taskListAllReport" dir="userguide/tutorial/projectReports" title="Obtaining more information about tasks">
                <output args="-q tasks --all"/>
            </sample>
        </section>
        <section id="sec:show_task_details">
            <title>Show task usage details</title>
            <para>Running <userinput>gradle help --task someTask</userinput> gives you detailed information about a specific task or multiple
                tasks matching the given task name in your multiproject build.
                Below is an example of this detailed information:
            </para>
            <sample id="taskHelp" dir="userguide/tutorial/projectReports" title="Obtaining detailed help for tasks">
                <output args="-q help --task libs"/>
            </sample>
            <para>This information includes the full task path, the task type, possible commandline options and the description of the given task.
            </para>
        </section>
        <section id="sec:listing_dependencies">
            <title>Listing project dependencies</title>
            <para id="para:commandline_dependency_report">Running <userinput>gradle dependencies</userinput>
                gives you a list of the dependencies of the selected project, broken down by configuration. For each
                configuration, the direct and transitive dependencies of that configuration are shown in a tree. Below
                is an example of this report:
            </para>
            <sample id="dependencyListReport" dir="userguide/tutorial/projectReports" title="Obtaining information about dependencies">
                <output args="-q dependencies api:dependencies webapp:dependencies"/>
            </sample>
            <para>
                Since a dependency report can get large, it can be useful to restrict the report to a particular configuration.
                This is achieved with the optional <userinput>--configuration</userinput> parameter:
            </para>
            <sample id="dependencyListReportFiltered" dir="userguide/tutorial/projectReports" title="Filtering dependency report by configuration">
                <output args="-q api:dependencies --configuration testCompile"/>
            </sample>
        </section>
        <section id="sec:listing_buildscript_dependencies">
            <title>Listing project buildscript dependencies</title>
            <para id="para:commandline_buildscript_dependency_report">
                Running <userinput>gradle buildEnvironment</userinput> visualises the buildscript dependencies of the selected project,
                similarly to how <userinput>gradle dependencies</userinput> visualises the dependencies of the software being built.
            </para>
        </section>
        <section id="sec:dependency_insight">
            <title>Getting the insight into a particular dependency</title>
            <para id="para:commandline_dependency_insight_report">Running <userinput>gradle dependencyInsight</userinput>
                gives you an insight into a particular dependency (or dependencies) that match specified input.
                Below is an example of this report:
            </para>
            <sample id="dependencyInsightReport" dir="userguide/tutorial/projectReports" title="Getting the insight into a particular dependency">
                <output args="-q webapp:dependencyInsight --dependency groovy --configuration compile"/>
            </sample>
            <para>
                This task is extremely useful for investigating the dependency resolution,
                finding out where certain dependencies are coming from and why certain versions are selected.
                For more information please see the <apilink class="org.gradle.api.tasks.diagnostics.DependencyInsightReportTask"/> class in the API documentation.
            </para>
            <para>
                The built-in dependencyInsight task is a part of the 'Help' tasks group.
                The task needs to configured with the dependency and the configuration.
                The report looks for the dependencies that match the specified dependency spec in the specified configuration.
                If Java related plugin is applied, the dependencyInsight task is pre-configured with 'compile' configuration because typically it's the compile dependencies we are interested in.
                You should specify the dependency you are interested in via the command line '--dependency' option.
                If you don't like the defaults you may select the configuration via '--configuration' option.
                For more information see the <apilink class="org.gradle.api.tasks.diagnostics.DependencyInsightReportTask"/> class in the API documentation.
            </para>
        </section>
        <section id="sec:listing_properties">
            <title>Listing project properties</title>
            <para>Running <userinput>gradle properties</userinput> gives you a list of the properties of the selected
                project. This is a snippet from the output:
            </para>
            <sample id="propertyListReport" dir="userguide/tutorial/projectReports" title="Information about properties">
                <output args="-q api:properties" ignoreExtraLines="true"/>
            </sample>
        </section>
        <section id="sec:profiling_build">
            <title>Profiling a build</title>
            <para>The <userinput>--profile</userinput> command line option will record some useful timing information
            while your build is running and write a report to the <filename>build/reports/profile</filename> directory.
            The report will be named using the time when the build was run.
            </para>
            <para>This report lists summary times and details for both the configuration phase and task execution.  The
                times for configuration and task execution are sorted with the most expensive operations first.  The task
                execution results also indicate if any tasks were skipped (and the reason) or if tasks that were not skipped
                did no work.
            </para>
            <para>Builds which utilize a buildSrc directory will generate a second profile report for buildSrc in the
                <filename>buildSrc/build</filename> directory.
            </para>
            <imageobject>
                <imagedata fileref="img/profile.png" width="903px" depth="477px"/>
            </imageobject>

        </section>
    </section>

    <section id="sec:dry_run">
        <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, if you run “<userinput>gradle -m clean compile</userinput>”, you'll see all the tasks that would be
            executed as part of the <literal>clean</literal> and <literal>compile</literal> tasks.
            This is complementary to the <option>tasks</option> task, which shows you the tasks which are available for
            execution.
        </para>
    </section>
    <section id="sec:cli_tutorial_summary">
        <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>
