// 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.

[[console]]
== The Gradle Console

[[sec:console_overview]]
=== Overview

Nearly every Gradle user will experience the command-line interface at some point. Gradle's console output is optimized for rendering performance and usability, showing only relevant information and providing visually appealing feedback.

+++++
<figure xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>The Gradle command-line in action</title>
    <imageobject>
        <imagedata fileref="img/console-animation.gif"/>
    </imageobject>
</figure>
+++++

=== Command-line feedback

Gradle displays information while the build is running so you can concentrate on the most important items of interest. Each of the sections of Gradle's console output help answer specific questions.

- <<sec:console_build_output,Is there anything I should know about my build right now e.g. tests have failed and emitted warnings?>>
- <<sec:console_build_progress_bar,When will my build finish?>>
- <<sec:console_work_in_progress_display,What is Gradle doing right now?>>
- <<sec:console_build_result,Are there other interesting outcomes e.g. tasks that have been skipped or were up-to-date?>>

[[sec:console_build_output]]
==== Build output

Output from build script log messages, tasks, forked processes, test output and compile warnings is displayed above the build progress bar.

+++++
<figure xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>Build output portion of the Gradle command-line</title>
    <imageobject>
        <imagedata fileref="img/console-build-output.jpg"/>
    </imageobject>
</figure>
+++++

Starting with Gradle 4.0, the volume of command-line console output has been reduced. The start and end of each task is not displayed anymore or the outcome of the task (e.g. `UP-TO-DATE`). The task's name is only displayed if some output is emitted during task execution. Gradle also groups output originating from a specific context together, e.g. all warnings from a compilation task, test execution or forked processes. Grouped output is especially useful for parallel task execution, as it prevents interleaved messages that do not clearly indicate their origin (see <<sec:parallel_execution>>).

NOTE: Grouped console output and reduced console output only occurs with interactive and _rich console_ command-lines. Continuous integration servers and builds using `--console=plain` will see console output similar to pre-Gradle 4.0. You can also set this option via `org.gradle.console` property, see <<sec:gradle_configuration_properties>>.

The following console output shows grouped output for the configuration phase and the task `:compileJava`:

----
> Configure project ':library'
Configuring project version for project ':library'

> Configure project ':consumer'
Configuring project version for project ':consumer'

> Task :compileJava
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.
----

Gradle does not wait until a unit of work is fully completed before displaying its output. Gradle flushes output to the console after a short amount of time to ensure that relevant information is made available as soon as possible. When building in parallel, the output of long running tasks can be broken up by other tasks. Each block of console output will clearly indicate which task it belongs to.

----
> Task :compileJava
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :generateCode
Generating JAXB classed from XSD files.

> Task :compileJava
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
----

[[sec:console_build_progress_bar]]
==== Build progress bar

The build progress bar gives you a very fast way of knowing if the build will be finished soon. As the build performs work, the progress bar will fill from left to right. At any given time, the build progress bar also renders the current phase of the build lifecycle (see <<sec:build_phases>>) and the overall time spent during the build.

+++++
<figure xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>Build progress bar portion of the Gradle command-line</title>
    <imageobject>
        <imagedata fileref="img/console-build-progress-bar.jpg"/>
    </imageobject>
</figure>
+++++

The following examples shows the progress bar during the initialization, configuration and execution phase of the build lifecycle:

----
<-------------> 0% INITIALIZING [2s]
<==-----------> 25% CONFIGURING [4s]
<=========----> 64% EXECUTING [17s]
----

[[sec:console_work_in_progress_display]]
==== Work in-progress display

Gradle provides a fined-grained view of the actual work being performed directly underneath the <<sec:console_build_progress_bar,The build progress bar>>. Each line represents a thread or process that can perform work in parallel--resolving dependencies, executing a task and running tests. If an available worker is not being used then it is marked with `IDLE`. The number of available workers defaults to the number of processors on the machine executing the build.

+++++
<figure xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>Work in-progress portion of the Gradle command-line</title>
    <imageobject>
        <imagedata fileref="img/console-work-in-progress.jpg"/>
    </imageobject>
</figure>
+++++

NOTE: Parallel test execution is only displayed for JVM-based tests supported by Gradle core e.g. JUnit and TestNG. Future versions of Gradle might support other testing tools and frameworks.

The following portion of the console output shows the work in-progress display with 8 concurrent workers:

----
<==========---> 77% EXECUTING [10s]
> :codeQuality:classpathManifest > Resolve dependencies :codeQuality:runtimeClasspath
> :ivy:classpathManifest > Resolve dependencies :ivy:runtimeClasspath
> IDLE
> :antlr:classpathManifest > Resolve dependencies :antlr:runtimeClasspath
> :scala:compileJava > Resolve dependencies :scala:compileClasspath
> :buildInit:classpathManifest > Resolve dependencies :buildInit:runtimeClasspath
> :jacoco:classpathManifest > Resolve dependencies :jacoco:runtimeClasspath
> IDLE
----

[[sec:console_build_result]]
==== Build result

At the end of the build, Gradle will display the result of the build (successful or failed) and the number of tasks that performed work and avoided work. The build result also displays the overall elapsed time it took to execute the build. The number of tasks that performed work provides an indication of how out-of-date or busy the build was.

+++++
<figure xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>Build progress bar portion of the Gradle command-line</title>
    <imageobject>
        <imagedata fileref="img/console-build-result.jpg"/>
    </imageobject>
</figure>
+++++

The following build result represents a successful build and the amount of tasks including their statuses:

----
BUILD SUCCESSFUL in 2m 10s
411 actionable tasks: 381 executed, 30 up-to-date
----

"Actionable" tasks are tasks with at least one action. Lifecycle tasks like `build` (also called aggregation tasks) do not declare any actions and are therefore _not_ actionable.

[[sec:console_non_interactive_environments]]
=== Look & feel in non-interactive environments

By default, Gradle tries to enable rich console output by detecting the type of console the build is running from. This enables color and additional console output formatting. Non-interactive environments fall back to using plain console output. The plain output format _does not_ support grouping of output. Tasks and outcomes are always printed to be consistent with Gradle 3.x versions.

NOTE: Gradle builds executed from an IDE (e.g. Buildship and IntelliJ) or Continuous Integration products (e.g. Jenkins and TeamCity) use plain console output by default.

The following output demonstrates the use of a plain console:

----
:compileJava
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.
:processResources
:classes
:jar
:assemble
:compileTestJava NO-SOURCE
:processTestResources NO-SOURCE
:testClasses UP-TO-DATE
:test NO-SOURCE
:check UP-TO-DATE
:build

BUILD SUCCESSFUL in 6s
11 actionable tasks: 6 executed, 5 up-to-date
----
