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 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.
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 9.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 9.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 9.3. Abbreviated task name
Output of gradle d
> gradle d :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 9.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 9.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 9.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 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.
Running gradle --tasks
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:
Example 9.7. Obtaining information about tasks
Output of gradle -q --tasks
> gradle -q --tasks ------------------------------------------------------------ Root Project ------------------------------------------------------------ Default Tasks: dists :clean - Deletes the build directory (build) :dists -> :api:libs, :webapp:libs ------------------------------------------------------------ Project :api ------------------------------------------------------------ :api:libs rule - build<ConfigurationName>: builds the artifacts of the given configuration ------------------------------------------------------------ Project :webapp ------------------------------------------------------------ :webapp:libs rule - build<ConfigurationName>: builds the artifacts of the given configuration
Running gradle --dependencies
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:
Example 9.8. Obtaining information about dependencies
Output of gradle -q --dependencies
> gradle -q --dependencies ------------------------------------------------------------ Root Project ------------------------------------------------------------ No configurations ------------------------------------------------------------ Project :api ------------------------------------------------------------ compile |-----junit:junit:4.7:default ------------------------------------------------------------ Project :webapp ------------------------------------------------------------ compile |-----commons-io:commons-io:1.2:default
Running gradle --properties
gives you a list of the properties of each project in
the build.
You can also use the project report plugin to add a number of reporting tasks to your project.
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 -t
, which shows you all available tasks 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 B, Gradle Command Line.