【转载】Gradle学习 第十一章：使用Gradle命令行

转载地址：http://ask.android-studio.org/?/article/94

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基础命令行。你可以使用gradle进行构建，就像上一章节中你看到的那样。

11.1. Executing multiple tasks 多任务执行

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 as a dependency of another task, or both. Let's look at an example.
<翻译> 你可以通过在命令行中列出每个任务来执行多任务。例如，‘gradle compile test’ 将执行compile和test两个任务。Gradle将执行在命令行中列出的任务，以及每个任务所依赖的任务。每个任务仅执行一次，不论它是在命令行中被指定的或者另一个任务的依赖。请看一个例子。

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.
<翻译> 下面定义了得个任务。都依赖compile任务。

Figure 11.1. Task dependencies 任务依赖

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'
}
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


Each task is executed only once, so gradle test test is exactly the same as gradle test.
<翻译> 每个任务仅执行一次，所以'gradle test test'相当于'gradle test'。

11.2. Excluding tasks 排队任务

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.
<翻译> 你可以使用'-x 任务名'选项来排除一个任务。看看下面。

Example 11.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.
<翻译> 你可以看到输出内容，test任务没有执行，尽管它是dist任务的依赖。你同样也注意到了，test的依赖compileTest也没有执行。但是另一个依赖compile却执行了。

11.3. Continuing the build when a failure occurs 发生错误时继续构建

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.
<翻译> 默认情况下，只要有一个任务失败Gradle将停止执行。这样的结果就是我们无法发现其它的的错误。这个时候，我们就可以使用'--continue'选项来帮助我们发现更多的错误。

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.
<翻译> 当我们执行的时候带上‘--continue’选项，Gradle将执行每一个要执行的任务，所有的依赖，无故障的完成任务。在构建完成后会显示每一个错误。

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).
<翻译> 如果一个任务失败了，接下来任何一个依赖它的任务都不会执行，因为这样是不安全的。

11.4. Task name abbreviation 任务名缩写

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:
<翻译> 在你指定任务的时候，不用提供任务全名。你只需要提供足够的任务唯一标识。例如，下面的例子中，‘gradle d’就可以执行dist任务：

Example 11.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
<翻译> 你还可以使用驼峰任务名。例如，你可以使用‘gradle compTest’或‘gradle cT’来执行compileTest任务

Example 11.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.
<翻译> 你也可以带上‘-x’选项来使用这些缩写。

11.5. Selecting which build to execute 选择执行

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:
<翻译> 当你执行一个gradle命令，它看上去会是当前目录的build文件。你可以使用‘-b’选项来选择另一个文件，这样settings.gralde文件不会被使用。例如：

Example 11.5. Selecting the project using a build file 选择项目使用build文件

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. For multi-project builds you should use -p option instead of -b option.
<翻译> 另外，你可以使用‘-p’选项来替代‘-b’指定多个项目目录。

Example 11.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'.


11.6. Obtaining information about your build 获取构建信息

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.
<翻译> Gradle提供了几个显示构建详情的内置任务。这个可以用来理解构建的结构，依赖，以及调试问题。

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.
<翻译> 除了下面显示的内置任务，你还可以使用项目报告插件来添加任务到你的项目。

11.6.1. Listing projects 列出项目

Running gradle projects gives you a list of the sub-projects of the selected project, displayed in a hierarchy. Here is an example:
<翻译> 运行'gradle projects'可以列出所选项目的子模块，看下面：

Example 11.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
**<翻译>** 运行'gradle 项目路径:tasks'可以查看该项目的任务列表
For example, try running gradle :api:tasks 比如运行'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 11.8. Providing a description for a project 提供一个项目的描述

build.gradle
description = 'The shared API for the application'


11.6.2. Listing 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:
<翻译> 运行'gralde tasks'能够列出所选项目的主任务。一般会显示项目的默认任务及描述。看下面这个例子：

Example 11.9. Obtaining information about 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)
**<翻译>** 删除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

components - Displays the components produced by root project 'projectReports'. [incubating]
**<翻译>** 
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.
**<翻译>** 
model - Displays the configuration model of root project 'projectReports'. [incubating]
**<翻译>** 
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 gradle tasks --all
**<翻译>** 

To see more detail about a task, run gradle help --task <task>
**<翻译>** 


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 11.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 11.11. Obtaining more information about tasks

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

components - Displays the components produced by root project 'projectReports'. [incubating]
**<翻译>** 
api:components - Displays the components produced by project ':api'. [incubating]
**<翻译>** 
webapp:components - Displays the components produced by project ':webapp'. [incubating]
**<翻译>** 
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.
**<翻译>** 
model - Displays the configuration model of root project 'projectReports'. [incubating]
**<翻译>** 
api:model - Displays the configuration model of project ':api'. [incubating]
**<翻译>** 
webapp:model - Displays the configuration model of project ':webapp'. [incubating]
**<翻译>** 
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'.
**<翻译>** 


11.6.3. Show task usage details

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:
<翻译> 

Example 11.12. Obtaining detailed help for tasks

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

Group
 build


This information includes the full task path, the task type, possible commandline options and the description of the given task.
<翻译> 

11.6.4. Listing project 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:
<翻译> 

Example 11.13. 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:2.3.10

testCompile
--- junit:junit:4.12
 --- org.hamcrest:hamcrest-core:1.3

------------------------------------------------------------
Project :webapp - The Web application implementation


<翻译>

compile
+--- project :api
|    --- org.codehaus.groovy:groovy-all:2.3.10
--- commons-io:commons-io:1.2

testCompile
No dependencies


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:
<翻译> 

Example 11.14. Filtering dependency report by configuration

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.12
 --- org.hamcrest:hamcrest-core:1.3


11.6.5. Getting the insight into a particular dependency

Running gradle dependencyInsight gives you an insight into a particular dependency (or dependencies) that match specified input. Below is an example of this report:
<翻译> 

Example 11.15. Getting the insight into a particular dependency

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.10
--- project :api
 --- compile


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 the DependencyInsightReportTask class in the API documentation.
<翻译> 

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 the DependencyInsightReportTask class in the API documentation.
<翻译> 

11.6.6. Listing project properties

Running gradle properties gives you a list of the properties of the selected project. This is a snippet from the output:
<翻译> 

Example 11.16. Information about 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_Decorated@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


11.6.7. Profiling a build

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.
<翻译> 

Builds which utilize a buildSrc directory will generate a second profile report for buildSrc in the buildSrc/build directory.
<翻译> 

11.7. Dry Run

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, if you run “gradle -m clean compile”, you'll see all the tasks that would 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.
<翻译> 

11.8. Summary

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.
<翻译>