Basic use of the Gradle command line

The basic use of the Gradle command line

This chapter describes the basic use of the command line. As you saw in the previous section, call the gradle command to accomplish some functionality.

Multitasth call

You can call multiple tasks at once on the command line as a list. F or example, the gradle compile test command is called in turn, and each task is called only once. C ompile and test tasks and their dependent tasks. W hether they are included in the script or not: tasks defined as command lines or dependent on other tasks are called to execute. Let's look at the following example.

Four tasks are defined below. Both dist and test rely on compile, and the gradle dist test task is called only when compile is called.

Task dependency

Multitasth call

build.gradle

task compile << {
    println 'compiling source'
}
task compileTest(dependsOn: compile) << {
    println 'compiling unit tests'
}
task test(dependsOn: [compile, compileTest]) << {
    println 'running unit tests'
}
task dist(dependsOn: [compile, test]) << {
    println 'building the distribution'
}

The output of the gradle dist test.

\> gradle dist test
:compile
compiling source
:compileTest
compiling unit tests
:test
running unit tests
:dist
building the distribution
BUILD SUCCESSFUL
Total time: 1 secs

Because each task is called only once, calling the gradle test is the same as calling the gradle test effect.

Exclude tasks

You can use the command line option -x to exclude certain tasks, let's demonstrate with the example above.

Exclude tasks

The output of the gradle dist -x test.

\> gradle dist -x test
:compile
compiling source
:dist
building the distribution
BUILD SUCCESSFUL
Total time: 1 secs

As you can see, the test task is not called, even if he is dependent on the dist task. At the same time, the test task-dependent task compileTest is not called, while tasks like compile, which are tested and dependent on other tasks at the same time, are still called.

Continues after failure

By default, Gradle interrupts execution whenever a task call fails. T his may make the call procedure faster, but those hidden errors will not be discovered. So you can use --continue to discover as many problems as possible in one call.

With the --continue option, Gradle calls each task and the tasks on which they depend. I nstead of interrupting execution in the event of an error. All error messages are listed at the end.

Once a task fails to execute, all subtastays that depend on the task are not called. For example, because the test task depends on the complie task, if the compile call goes wrong, the test is not called directly or indirectly.

Simplify the task name

When you try to call a task, you don't need to enter the full name of the task. J ust provide enough characters to uniquely distinguish the task. F or example, you can write the same in the example above. Use gradle di to call the dist task directly.

Simplify the task name

The output of the gradle di

\> gradle di
:compile
compiling source
:compileTest
compiling unit tests
:test
running unit tests
:dist
building the distribution
BUILD SUCCESSFUL
Total time: 1 secs

You can also call with the initials of each word in a hump-named task. For example, you can perform a gradle compTest or even gradle cT to call the compileTest task.

Simplify hump task names

The output of the gradle cT.

\> gradle cT
:compile
compiling source
:compileTest
compiling unit tests
BUILD SUCCESSFUL
Total time: 1 secs

You can still use the -x parameter after simplification.

Choose where to build

When you call gradle, the files in the current directory are always built by default, you can use the -b parameter to select the built files, and when you use this parameter, you always use them. Gradle will not take effect, look at the following example:

Select the file build

subdir/myproject.gradle

task hello << {
    println "using build file '$buildFile.name' in '$buildFile.parentFile.name'."
}

The output of the gradle -q -b subdir/myproject.gradle hello

Output of gradle -q -b subdir/myproject.gradle hello
\> gradle -q -b subdir/myproject.gradle hello
using build file 'myproject.gradle' in 'subdir'.

In addition, you can use the -p parameter to specify the directory you are building, for example, in a multi-project build you can replace the -b parameter with -p.

Choose to build the catalog

The output of the gradle -q -p subdir hello

\> gradle -q -p subdir hello
using build file 'build.gradle' in 'subdir'.

Get build information

Gradle provides many built-in tasks to gather build information. These built-in tasks are helpful in understanding the dependency structure and solving problems.

To learn more, you can refer to the Project Report plug-in to add build reports for your project.

The list of items

Executing gradle projects will give you a list of sub-project names. Here's an example.

Collect project information

The output of the gradle -q projects

\> gradle -q projects
\------------------------------------------------------------
Root project
\------------------------------------------------------------
Root project 'projectReports'
+--- Project ':api' - The shared API for the application
\--- Project ':webapp' - The Web application implementation
To see a list of the tasks of a project, run gradle <project-path>:tasks
For example, try running gradle :api:tasks

This report shows the description of each project. Of course, you can specify these descriptions in your project with the description property.

Add description information to the project.

build.gradle

description = 'The shared API for the application'

The task list

Executing the gradle tasks lists all the tasks in the project. T his displays all the default tasks in the project and a description of each task. Here's an example

Get task information

The output of the gradle -q tasks:

\> gradle -q tasks
\------------------------------------------------------------
All tasks runnable from root project
\------------------------------------------------------------
Default tasks: dists
Build tasks
\-----------
clean - Deletes the build directory (build)
dists - Builds the distribution
libs - Builds the JAR
Build Setup tasks
\-----------------
init - Initializes a new Gradle build. [incubating]
wrapper - Generates Gradle wrapper files. [incubating]
Help tasks
\----------
dependencies - Displays all dependencies declared in root project 'projectReports'.
dependencyInsight - Displays the insight into a specific dependency in root project 'projectReports'.
help - Displays a help message
projects - Displays the sub-projects of root project 'projectReports'.
properties - Displays the properties of root project 'projectReports'.
tasks - Displays the tasks runnable from root project 'projectReports' (some of the displayed tasks may belong to subprojects).
To see all tasks and more detail, run with --all.

By default, this only shows those tasks that are grouped. You can present this information to the results by setting group properties and descriptions for tasks.

Change the contents of the task report

build.gradle

dists {
    description = 'Builds the distribution'
    group = 'build'
}

Of course you can also use the --all parameter to gather more task information. This lists all tasks in the project and the dependencies between them.

Obtaining more information about tasks

The output of the gradle -q tasks --all:

\> gradle -q tasks --all
\------------------------------------------------------------
All tasks runnable from root project
\------------------------------------------------------------
Default tasks: dists
Build tasks
\-----------
clean - Deletes the build directory (build)
api:clean - Deletes the build directory (build)
webapp:clean - Deletes the build directory (build)
dists - Builds the distribution [api:libs, webapp:libs]
    docs - Builds the documentation
api:libs - Builds the JAR
    api:compile - Compiles the source files
webapp:libs - Builds the JAR [api:libs]
    webapp:compile - Compiles the source files
Build Setup tasks
\-----------------
init - Initializes a new Gradle build. [incubating]
wrapper - Generates Gradle wrapper files. [incubating]
Help tasks
\----------
dependencies - Displays all dependencies declared in root project 'projectReports'.
dependencyInsight - Displays the insight into a specific dependency in root project 'projectReports'.
help - Displays a help message
projects - Displays the sub-projects of root project 'projectReports'.
properties - Displays the properties of root project 'projectReports'.
tasks - Displays the tasks runnable from root project 'projectReports' (some of the displayed tasks may belong to subprojects).

Get task help information

Executing the gradle help --task someTask displays the details of the specified task. O r information about all tasks with the same task name in a multi-project build. Here's an example.

Get task help

The output of the gradle -q help --task libs

\> gradle -q help --task libs
Detailed task information for libs
Paths
     :api:libs
     :webapp:libs
Type
     Task (org.gradle.api.Task)
Description
     Builds the JAR

These results include the path, type, description information, and so on for the task.

Gets a list of dependencies

Executing a gradle dependencies lists the dependencies of the project, all of which are distinguished by tasks and presented as tree structures. Here's an example.

Get dependency information

gradle -q dependencies api:dependencies webapp: the output of the dependencies

\> gradle -q dependencies api:dependencies webapp:dependencies
\------------------------------------------------------------
Root project
\------------------------------------------------------------
No configurations
\------------------------------------------------------------
Project :api - The shared API for the application
\------------------------------------------------------------
compile
\--- org.codehaus.groovy:groovy-all:2.2.0
testCompile
\--- junit:junit:4.11
     \--- org.hamcrest:hamcrest-core:1.3
\------------------------------------------------------------
Project :webapp - The Web application implementation
\------------------------------------------------------------
compile
+--- project :api
|    \--- org.codehaus.groovy:groovy-all:2.2.0
\--- commons-io:commons-io:1.2
testCompile
No dependencies

Although the output is many, this is useful for understanding the build task, and of course you can use the --configuration parameter to see how dependent the specified build task is.

Filter dependent information

The output of the gradle -q api:dependencies --configuration testCompile

\> gradle -q api:dependencies --configuration testCompile
\------------------------------------------------------------
Project :api - The shared API for the application
\------------------------------------------------------------
testCompile
\--- junit:junit:4.11
     \--- org.hamcrest:hamcrest-core:1.3

View specific dependencies

Executing Running gradle dependencyInsight allows you to view the specified dependencies. Here's an example.

Get a specific dependency

gradle -q webapp: dependencyInsight --dependency groovy --configuration compile output

\> gradle -q webapp:dependencyInsight --dependency groovy --configuration compile
org.codehaus.groovy:groovy-all:2.2.0
\--- project :api
     \--- compile

This is useful for understanding dependencies and why this version was chosen as a dependency. For more information, see The Dependency Check Report.

The dependencyInsight task is one of the 'Help' task groups. T his task needs to be configured before it can be configured. I f a Java-related plug-in is used, the dependencyInsight task is pre-configured to 'Compile'. A ll you need to do is use the '-dependency' parameter to make the dependencies you want to see. I f you don't want to use the default configured parameter items, you can specify them by the '-configuration' parameter. For more information, see The Dependency Check Report.

Gets a list of project properties

Executing the gradle properties gives you a list of all the properties of the project. Here's an example.

Property information

The output of the gradle -q api:properties

\> gradle -q api:properties
\------------------------------------------------------------
Project :api - The shared API for the application
\------------------------------------------------------------
allprojects: [project ':api']
ant: org.gradle.api.internal.project.DefaultAntBuilder@12345
antBuilderFactory: org.gradle.api.internal.project.DefaultAntBuilderFactory@12345
artifacts: org.gradle.api.internal.artifacts.dsl.DefaultArtifactHandler@12345
asDynamicObject: org.gradle.api.internal.ExtensibleDynamicObject@12345
buildDir: /home/user/gradle/samples/userguide/tutorial/projectReports/api/build
buildFile: /home/user/gradle/samples/userguide/tutorial/projectReports/api/build.gradle

Build the log

The --profile parameter collects some information from the build period and saves it to the build/reports/profile directory and names these files after the build time.

The following log records the overall time spent and the time spent on each process, in reverse order of time size, and records the performance of the task.

If buildSrc is used, a log record is also generated under buildSrc/build.

Dry Run

Sometimes you may just want to know the results of a task executed sequentially in a task set, but you don't want to actually perform those tasks. T hen you can use the -m parameter. For example, gradle -m clean compile calls clean and compile, which complement tasks and lets you know which tasks can be used to execute.

This chapter summarizes

In this chapter you learned a lot about what you can do with the command line, and you can learn more by refering to the Gradle command in Appendix D, the Gradle command line.