This chapter introduces the basics of the Gradle command-line. You run a build using the gradle command, which you have already seen in action in previous chapters.
You can execute multiple tasks in a single build by listing each of the tasks on the command-line. For example,
the command gradle compile test will execute the compile and
test 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 it a
dependency of another task, or both. Let's look at an example.
Below four tasks are defined. Both dist and test depend on the
compile task. Running gradle dist test for this build script
results in the compile task being executed only once.
Example 10.1. Executing multiple tasks
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'
}Output of 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 executed once only, executing gradle test test is exactly the same
as executing gradle test.
You can exclude a task from being executed using the -x command-line option and providing
the name of the task to exclude. Let's try this with the sample build file above.
Example 10.2. Excluding tasks
Output of gradle dist -x test
> gradle dist -x test :compile compiling source :dist building the distribution BUILD SUCCESSFUL Total time: 1 secs
You can see from the output of this example, that the test task is not executed, even
though it is a dependency of the dist task. You will also notice that the
test task's dependencies, such as compileTest
are not executed either. Those dependencies of test that are required by another task, such as
compile, are still executed.
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
dist by running gradle d:
Example 10.3. Abbreviated task name
Output of 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 abbreviate each word in a camel case task name. For example, you can execute task compileTest
by running gradle compTest or even gradle cT
Example 10.4. Abbreviated camel case task name
Output of gradle cT
> gradle cT :compile compiling source :compileTest compiling unit tests BUILD SUCCESSFUL Total time: 1 secs
You can also use these abbreviations with the -x command-line option.
When you run the gradle command, it looks for a build file in the current directory.
You can use the -b option to select another build file. For example:
Example 10.5. Selecting the project using a build file
subdir/myproject.gradle
task hello << {
println "using build file '$buildFile.name' in '$buildFile.parentFile.name'."
}Output of gradle -q -b subdir/myproject.gradle hello
> gradle -q -b subdir/myproject.gradle hello using build file 'myproject.gradle' in 'subdir'.
Alternatively, you can use the -p option to specify the project directory to use:
Example 10.6. Selecting the project using project directory
Output of gradle -q -p subdir hello
> gradle -q -p subdir hello using build file 'build.gradle' in 'subdir'.
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.
In addition to the built-in tasks shown below, you can also use the project report plugin to add tasks to your project which will generate these reports.
Running gradle projects gives you a list of the sub-projects of the selected project,
displayed in a hierarchy. Here is an example:
Example 10.7. Obtaining information about projects
Output of 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
The report shows the description of each project, if specified. You can provide a description for a project
by setting the description property:
Example 10.8. Providing a description for a project
build.gradle
description = 'The shared API for the application'Running gradle tasks 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:
Example 10.9. Obtaining information about tasks
Output of gradle -q tasks
> gradle -q tasks ------------------------------------------------------------ Root Project ------------------------------------------------------------ Default tasks: dists Build tasks ----------- clean - Deletes the build directory (build) dists - Builds the distribution libs - Builds the JAR Help tasks ---------- dependencies - Displays the dependencies of 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 in root project 'projectReports'. To see all tasks and more detail, run with --all.
By default, this report shows only those tasks which have been assigned to a task group. You can do this
by setting the group property for the task. You can also set the description
property, to provide a description to be included in the report.
Example 10.10. Changing the content of the task report
build.gradle
dists {
description = 'Builds the distribution'
group = 'build'
}You can obtain more information in the task listing using the --all 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:
Example 10.11. Obtaining more information about tasks
Output of gradle -q tasks --all
> gradle -q tasks --all
------------------------------------------------------------
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
Help tasks
----------
dependencies - Displays the dependencies of 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 in root project 'projectReports'.Running gradle dependencies
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:
Example 10.12. Obtaining information about dependencies
Output of gradle -q dependencies api:dependencies webapp: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:1.7.6 [default] ------------------------------------------------------------ Project :webapp - The Web application implementation ------------------------------------------------------------ compile +--- projectReports:api:1.0-SNAPSHOT [compile] | \--- org.codehaus.groovy:groovy-all:1.7.6 [default] \--- commons-io:commons-io:1.2 [default]
Running gradle properties gives you a list of the properties of the selected
project. This is a snippet from the output:
Example 10.13. Information about properties
Output of gradle -q api:properties
> gradle -q api:properties
------------------------------------------------------------
Project :api - The shared API for the application
------------------------------------------------------------
additionalProperties: {}
all: [task ':api:clean', task ':api:compile', task ':api:libs']
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.DynamicObjectHelper@12345
asMap: {clean=task ':api:clean', compile=task ':api:compile', libs=task ':api:libs'}
buildDir: /home/user/gradle/samples/userguide/tutorial/projectReports/api/build
buildDirName: build
buildFile: /home/user/gradle/samples/userguide/tutorial/projectReports/api/build.gradleThe --profile command line option will record some useful timing information
while your build is running and write a report to the build/reports/profile directory.
The report will be named using the time when the build was run.
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.
Builds which utilize a buildSrc directory will generate a second profile report for buildSrc in the
buildSrc/build directory.
 |
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 -m option for this.
For example gradle -m clean compile shows you all tasks to be executed as
part of the clean and compile tasks.
This is complementary to the tasks task, which shows you the tasks which are available for
execution.
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 gradle command in Appendix C, Gradle Command Line.