本章介绍了Gradle命令行的基础知识，正如你在前面章节所看到的使用gradle命令来运行构建。
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.
你可以通过在命令行中列出每个任务来在单个构建中执行多个任务。例如，gradle compile test命令将执行compile和test任务。 Gradle将按照命令行中的顺序依次执行这些任务以及每一个任务所依赖的其他任务。每个任务只会被执行一次，无论它们是如何被包含在构建中的：即无论是在命令行中指定的，还是另一个任务的依赖，抑或两者都有。来看下面的例子。
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.
下面定义了四个任务，其中dist和test都依赖于compile任务。对于这个构建脚本，运行gradle dist test只会使compile任务被执行一次。
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.
示例 11.1. 执行多个任务 - Example 11.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'
}
gradle dist test的输出结果
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
由于每个任务只执行一次，执行gradle test test与执行gradle test的结果是完全相同的。
Because each task is executed once only, executing gradle test test is exactly the same as executing gradle test.
你可以使用-x命令行选项加上任务名称来排除某些会被执行的任务。让我们用上面的例子来演示一下。
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.
示例 11.2. 排除任务 - Example 11.2. Excluding tasks
gradle dist -x test的输出结果
Output of gradle dist -x test
> gradle dist -x test :compile compiling source :dist building the distribution BUILD SUCCESSFUL Total time: 1 secs
你可以本例的输出中看出test任务并不执行，即使它被dist任务所依赖。你也可能同时注意到test任务所依赖的任务，如compileTest也一样没有执行。而test所依赖的同时也是另一个任务所需要的任务，如compile，则仍然执行。
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.
默认情况下，只要有任务失败，Gradle就将中断执行让构建失败。这样做会使构建更快地结束，但也会让其他可能发生的失败不被发现。因此你可以使用--continue选项来在单个构建执行中发现尽可能多的失败。
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 --continue option.
当带上--continue参数执行时，Gradle将执行所有要执行的任务，即该任务的所有依赖任务都会完成执行，而不是一出现错误就停止。所有失败的信息将在构建结束时报告出来。
When executed with --continue, Gradle will execute every 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.
如果任务失败了，则依赖于它的所有后续任务将不会被执行，因为那样做是不安全的。例如，如果在测试代码中存在编译失败，测试将不会运行;因为测试任务会（直接或间接地）依赖于编译任务。
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).
在命令行中指定任务时，可以不输入任务的全名，只需要提供可以足够唯一标识任务的任务名。例如，在上面的示例构建中，你可以通过运行gradle d来执行dist任务：
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:
示例11.3. 缩写任务名称 - Example 11.3. Abbreviated task name
gradle di的输出结果
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
你也可以对驼峰命名的任务名称的每一个单词进行缩写。例如，你可以通过运行gradle compTest或gradle cT执行compileTest任务
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
示例11.4. 缩写驼峰任务名称 - Example 11.4. Abbreviated camel case task name
gradle cT的输出结果
Output of gradle cT
> gradle cT :compile compiling source :compileTest compiling unit tests BUILD SUCCESSFUL Total time: 1 secs
在使用-x命令行选项时，依然可以使用这些缩写。
You can also use these abbreviations with the -x command-line option.
当你运行gradle这个命令时，它会在当前目录中查找一个构建文件。你也可以使用-b选项来选择另一个构建文件。如果你使用-b选项，那么Gradle就不会去用到settings.gradle文件。例：
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. If you use -b option then settings.gradle file is not used. Example:
示例11.5. 使用构建文件选择项目 - Example 11.5. Selecting the project using a build file
subdir/myproject.gradle
task hello << {
println "using build file '$buildFile.name' in '$buildFile.parentFile.name'."
}
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'.
或者，你也可以使用-p选项来指定使用哪一个项目目录。对于多项目构建，你应该使用-p而不是-b选项。
Alternatively, you can use the -p option to specify the project directory to use. For multi-project builds you should use -p option instead of -b option.
示例11.6. 使用项目目录选择项目 - Example 11.6. Selecting the project using project directory
gradle -q -p subdir hello的输出结果
Output of gradle -q -p subdir hello
> gradle -q -p subdir hello using build file 'build.gradle' in 'subdir'.
Gradle提供了一些内置任务能展示构建的相关特定信息。这对于了解构建的结构和依赖以及调试问题可能很有用。
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.
运行gradle projects会为你按子项目的层次结构显示出项目列表，如下所示：
Running gradle projects gives you a list of the sub-projects of the selected project, displayed in a hierarchy. Here is an example:
示例11.7. 获取项目的相关信息 - Example 11.7. Obtaining information about projects
gradle -q 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
这个报告显示了每一个项目的描述信息（如果你有配置这个项目的描述信息的话）。你可以通过设置description属性来提供项目的描述信息：
The report shows the description of each project, if specified. You can provide a description for a project by setting the description property:
示例11.8. 提供项目描述信息 - Example 11.8. Providing a description for a project
build.gradle
description = 'The shared API for the application'
运行gradle tasks会为你列出所选项目的主要任务。报告会显示项目的默认任务（如果有配置默认任务的话），以及每个任务的说明。以下是关于该报告的示例：
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:
示例11.9. 获取任务的相关信息 - Example 11.9. Obtaining information about tasks
gradle -q tasks的输出结果
Output of 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.
默认情况下，此报告仅显示已分配给任务组的任务。你可以通过为任务设置group属性来实现它。你也可以通过设置description属性，来提供包含在报告中的描述。
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.
示例11.10. 更改任务报告的内容 - Example 11.10. Changing the content of the task report
build.gradle
dists {
description = 'Builds the distribution'
group = 'build'
}
当然你也可以使用--all选项，来获取更多的任务信息。使用此选项时，任务报告将按主要任务以及每一个任务的依赖进行分组，来列出项目中的所有任务。例子如下：
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:
示例11.11. 获取任务的更多相关信息 - Example 11.11. Obtaining more information about tasks
gradle -q tasks --all的输出结果
Output of 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'.
api:dependencies - Displays all dependencies declared in project ':api'.
webapp:dependencies - Displays all dependencies declared in project ':webapp'.
dependencyInsight - Displays the insight into a specific dependency in root project 'projectReports'.
api:dependencyInsight - Displays the insight into a specific dependency in project ':api'.
webapp:dependencyInsight - Displays the insight into a specific dependency in project ':webapp'.
help - Displays a help message
api:help - Displays a help message
webapp:help - Displays a help message
projects - Displays the sub-projects of root project 'projectReports'.
api:projects - Displays the sub-projects of project ':api'.
webapp:projects - Displays the sub-projects of project ':webapp'.
properties - Displays the properties of root project 'projectReports'.
api:properties - Displays the properties of project ':api'.
webapp:properties - Displays the properties of project ':webapp'.
tasks - Displays the tasks runnable from root project 'projectReports' (some of the displayed tasks may belong to subprojects).
api:tasks - Displays the tasks runnable from project ':api'.
webapp:tasks - Displays the tasks runnable from project ':webapp'.
运行gradle help --task someTask可以向你提供有关指定任务或是在多项目构建中与所指定的任务名称相匹配的所有任务的详细信息。如下所示：
Running gradle help --task someTask 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:
示例11.12. 获取任务的帮助信息 - Example 11.12. Obtaining detailed help for tasks
gradle -q help --task libs的输出结果
Output of 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
该信息包括完整的任务路径，任务类型，可用的命令行选项以及任务的描述信息。
This information includes the full task path, the task type, possible commandline options and the description of the given task.
运行gradle dependencies会为你列出所选项目的依赖关系，这些依赖会根据配置的任务细分。对于每个配置，它的直接和传递依赖会按树型结构展示出来。如下例：
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:
示例11.13. 获取依赖的相关信息 - Example 11.13. Obtaining information about dependencies
gradle -q dependencies api:dependencies webapp: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:2.3.3
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.3.3
\--- commons-io:commons-io:1.2
testCompile
No dependencies
由于一份依赖报告可能会很长，因此只显示指定配置的报告会很有用，它通过可选的--configuration参数来实现：
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 --configuration parameter:
示例11.14. 按配置过滤依赖报告 - Example 11.14. Filtering dependency report by configuration
gradle -q api:dependencies --configuration testCompile的输出结果
Output of 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
运行gradle dependencyInsight会让你深入了解与指定的输入内容相匹配的特定依赖（或多个依赖）。示例如下：
Running gradle dependencyInsight gives you an insight into a particular dependency (or dependencies) that match specified input. Below is an example of this report:
示例11.15. 查看特定的依赖 - Example 11.15. Getting the insight into a particular dependency
gradle -q webapp:dependencyInsight --dependency groovy --configuration compile的输出结果
Output of gradle -q webapp:dependencyInsight --dependency groovy --configuration compile
> gradle -q webapp:dependencyInsight --dependency groovy --configuration compile
org.codehaus.groovy:groovy-all:2.3.3
\--- project :api
\--- compile
这一任务对于调查依赖解析非常有用，它可以找出某些依赖关系来自于哪，以及为什么选择这些版本。有关更多信息，请参阅DependencyInsightReportTask。
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 DependencyInsightReportTask.
内置的dependencyInsight任务是“Help”任务组的一部分。该任务需要使用依赖和配置信息来配置。报告将在指定的配置中查找与指定依赖说明相匹配的依赖项。例如，如果应用了java相关的插件，那么dependencyInsight任务是通过“compile”配置进行预配置的，因为通常来说，我们感兴趣的是编译的依赖。如果你想要指定所感兴趣的依赖，可以使用命令行“--configurastion”选项。如果您不想要默认的配置，也可以通过“--configuration”选项来选择配置。更多信息请参阅DependencyInsightReportTask。
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 DependencyInsightReportTask.
运行gradle properties会向你列出所选项目的属性。如下例：
Running gradle properties gives you a list of the properties of the selected project. This is a snippet from the output:
示例11.16. 获取属性的相关信息 - Example 11.16. Information about properties
gradle -q api:properties的输出结果
Output of 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 baseClassLoaderScope: org.gradle.api.internal.initialization.DefaultClassLoaderScope@12345 buildDir: /home/user/gradle/samples/userguide/tutorial/projectReports/api/build buildFile: /home/user/gradle/samples/userguide/tutorial/projectReports/api/build.gradle
使用--profile命令行选项会在运行构建时记录一些有用的计时信息，并以运行构建时的时间命名，把报告保存到build/reports/profile目录。
The --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.
使用buildSrc目录的构建为buildSrc在buildSrc/build目录里生成第二个分析报告。
Builds which utilize a buildSrc directory will generate a second profile report for buildSrc in the buildSrc/build directory.
 |
有时候你可能想知道，以命令行指定的给定一组任务会以怎样的顺序去执行，但你不希望任务被真的执行，就可以使用-m这个选项。例如gradle -m clean compile会显示所有要执行的任务，如clean和compile任务。这是对tasks任务的补充，用于显示可以执行的任务。
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.
在本章中，你已经学到了许多可以从命令行做的事情。关于gradle这命令的更多信息，可以参考《附录D，Gradle命令行》。
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 D, Gradle Command Line.