第1章 使用gradle命令行

内容列表

• 1.1. 执行多命令
• 1.2. 剔除任务
• 1.3. 发生错误继续执行
• 1.4. 任务名称缩写
• 1.5. 选择构建文件
• 1.6. 强制执行任务
• 1.7. 获取构建信息
• 1.8. Dry Run
• 1.9. Summary

1.1.执行多命令

你如果在一个build文件中定义了多个任务，可以在command-line中指定任务集合来执行多个任务。例如命令：gradle compile test会按照顺序执行compile和test任务，并且执行任务的依赖任务。不管任务是否在命令行中指定或其他任务引用，每个任务只会执行一次。

下面例子中定义了4个任务，dist和test任务都依赖compile任务。如果执行gradle dist test命令，compile命令只会执行一次。

图1.1 任务依赖

示例 1.1 执行多任务

build.gradle

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

gradle dist test的运行结果：

> Task :compilecompiling source> Task :compileTestcompiling unit tests> Task :testrunning unit tests> Task :distbuilding the distributionBUILD SUCCESSFUL in 2s4 actionable tasks: 4 executed

结果显示只运行了一次test任务，因此执行命名写成gradle test test和写成gradle test效果一样。

1.2. 剔除任务

你可以使用在命令行中使用-x参数剔除某任务。

示例 1.2 剔除任务
执行gradle dist -x test的输出：

> Task :compilecompiling source> Task :distbuilding the distributionBUILD SUCCESSFUL in 1s2 actionable tasks: 2 executed

从输出中可以看出，test任务被dist任务依赖但并未执行。

1.3.发生错误后继续执行

默认情况下，gradle执行过程中一旦出现错误就会停止运行。可以使用--continue参数隐藏错误，继续执行，以尽早发现整个执行过程中的所有错误。

使用了--continue参数后，gradle会执行所有的任务，并在最后显示所有的错误信息。但是如果一个任务执行失败，那么依赖它的任务不会被执行，因为其执行是不安全的。例如示例中，如果compile任务执行失败，那么test任务不会被执行。因为test任务直接或间接引用了compile任务。

1.4.任务名称缩写

在命令行识别某任务时，不需要使用任务全称，只需要键入足以识别任务的关键字。例如示例中的dist任务，可以使用gradle di执行。

示例 1.3 缩略任务名

gradle id的输出：

> Task :compilecompiling source> Task :compileTestcompiling unit tests> Task :testrunning unit tests> Task :distbuilding the distributionBUILD SUCCESSFUL in 2s4 actionable tasks: 4 executed

你还可以缩写驼峰命名任务的每个单词。例如任务compileTest可以通过gradle compTest或gradle cT来执行。

示例 1.4 驼峰任务名缩写

gradle cT的输出：

> Task :compilecompiling source> Task :compileTestcompiling unit testsBUILD SUCCESSFUL in 1s2 actionable tasks: 2 executed

当然在-x参数后的任务名也可以使用这种缩写形式。

1.5.选择构建文件

当运行gradle命令时，会在当前文件夹下查找build文件。你可以使用-b参数指定其他构建文件。

示例 1.5 选择构建文件

subdir/myproject.gradle

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

gradle -q -b subdir/myproject.gradle hello的输出：

using build file 'myproject.gradle' in 'subdir'.

你可以使用-p代替-b，但是在多工程构建中，必须使用-p。

示例 1.6 通过工程路径选择工程

gradle -q -p subdir hello的输出：

using build file 'build.gradle' in 'subdir'.

1.6. 强制执行任务

一些任务，特别是gradle自带的任务支持增量构建。这些任务通过上次执行后的输入（inputs）和输出（outputs）有没有变化而决定是否需要执行。你可以很容易识别哪些增量任务没被执行，因为在执行输出结果中，这些任务后变会标记上UP-TO-DATE。

有些情况下那你可能需要忽略up-to-date而强制执行这些增量构建任务，你可以使用--rerun-tasks参数。下面示例中演示了不使用和使用这种参数的运行结果。

示例 1.7 强制执行

gradle doIt的输出：

：doIt UP-TO-DATE

gradle --rerun-tasks doIt的输出：

：doIt

这种方式可以强制所有任务都被执行，有点像是clean任务，但是这种方式不会删除已经生成的输出结果。

1.7. 获取构建信息

gradle提供了多个内嵌的任务可以显示构建过程中的细节信息。这些信息对理解构建结构、各种依赖关系、跟踪问题等非常有用。

除了下面演示的内嵌任务，你还可使用project report plugin插件生成这些信息报告。

1.7.1. 工程列表

运行gradle projects命令，会显示当前工程的子工程结构树。

示例 1.8 获取工程信息

gradle -q projects的输出：

Root project 'projectReports'+--- Project ':api' - The shared API for the application\--- Project ':webapp' - The Web application implementationTo see a list of the tasks of a project, run gradle <project-path>:tasks

打印内容中显示了每个工程的描述信息，你可以通过工程的description属性设置这些信息。

示例 1.9 提供工程的description属性

build.gradle

description = 'The shared API for the application'

1.7.2. 任务列表

运行gradle tasks命令会显示选中工程的主要任务列表，以及任务的描述信息。

示例 1.10 获取任务列表

gradle -q tasks的输出：

------------------------------------------------------------All tasks runnable from root project------------------------------------------------------------Build Setup tasks-----------------init - Initializes a new Gradle build.wrapper - Generates Gradle wrapper files.Help tasks----------buildEnvironment - Displays all buildscript dependencies declared in root project 'Chapter4'.components - Displays the components produced by root project 'Chapter4'. [incubating]dependencies - Displays all dependencies declared in root project 'Chapter4'.dependencyInsight - Displays the insight into a specific dependency in root project 'Chapter4'.dependentComponents - Displays the dependent components of components in root project 'Chapter4'.help - Displays a help message.model - Displays the configuration model of root project 'Chapter4'. [incubating]projects - Displays the sub-projects of root project 'Chapter4'.properties - Displays the properties of root project 'Chapter4'.tasks - Displays the tasks runnable from root project 'Chapter4'.

默认情况下，打印内容只包括指定了group的任务，也成为”可见任务”。你可以通过任务的group属性设置任务的分组，通过description属性配置任务的描述信息。

示例 1.11 修改任务报告内容

build.gradle

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

你可以通过--all属性获取更多的任务信息。通过该参数可以显示出所有任务列表，包括为指定分组的任务，也成为”隐藏任务”。

示例 1.12 获取更多的任务信息

gradle -q tasks -all的输出：

------------------------------------------------------------All tasks runnable from root project------------------------------------------------------------Default tasks: distsBuild tasks-----------clean - Deletes the build directory (build)api:clean - Deletes the build directory (build)webapp:clean - Deletes the build directory (build)dists - Builds the distributionapi:libs - Builds the JARwebapp:libs - Builds the JARBuild Setup tasks-----------------init - Initializes a new Gradle build.wrapper - Generates Gradle wrapper files.Help tasks----------buildEnvironment - Displays all buildscript dependencies declared in root project 'projectReports'.api:buildEnvironment - Displays all buildscript dependencies declared in project ':api'.webapp:buildEnvironment - Displays all buildscript dependencies declared in project ':webapp'.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'.dependentComponents - Displays the dependent components of components in root project 'projectReports'. [incubating]api:dependentComponents - Displays the dependent components of components in project ':api'. [incubating]webapp:dependentComponents - Displays the dependent components of components in project ':webapp'. [incubating]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'.Other tasks-----------api:compile - Compiles the source fileswebapp:compile - Compiles the source filesdocs - Builds the documentation

1.7.3. 显示任务细节

运行gradle help --task someTask命令，可以打印出指定任务或者多工程定义重复任务的详细信息。

示例 1.13 获取任务细节

gradle -q help --task libs的输出：

Detailed task information for libsPaths     :api:libs     :webapp:libsType     Task (org.gradle.api.Task)Description     Builds the JARGroup     build

打印内容包括任务的全路径、任务类型、可用的名称参数和描述信息。

1.7.4. 工程引用列表

运行gradle dependencies会打印出工程的引用列表，可以通过配置分离，对每个配置会显示直接引用和间接引用的树形结构。

示例 1.14 获取引用信息

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.4.10testCompile\--- 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.4.10\--- commons-io:commons-io:1.2testCompileNo dependencies

因为引用结构树会变得非常庞大，显示特定配置的引用结构树是有必要的，可以通过指定--configuration参数实现该目标。

示例 1.15 通过configuration过滤引用结构树

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

1.7.5. buildscript引用列表

运行gradle buildEnvironment命令，可以显示工程的buildscript引用列表，类似于gradle dependencies命令显示工程引用。

1.7.6. 特定引用详情

运行gradle dependencyInsight命令，可以打印出指定命令详细信息。

示例 1.16 获取引用详情

gradle -q webapp:dependencyInsight --dependency groovy --configuration compile的输出：

org.codehaus.groovy:groovy-all:2.4.10\--- project :api     \--- compile

这个任务对解决引用问题非常有用，可以查询出引用的来源及为何选择某版本。

1.7.7. 显示工程属性

运行gradle properties命令，会打印出工程的相关属性。

示例 1.17 工程属性

gradle -q api:properties的输出：

allprojects: [project ':api']ant: org.gradle.api.internal.project.DefaultAntBuilder@12345antBuilderFactory: org.gradle.api.internal.project.DefaultAntBuilderFactory@12345artifacts: org.gradle.api.internal.artifacts.dsl.DefaultArtifactHandler_Decorated@12345asDynamicObject: DynamicObject for project ':api'baseClassLoaderScope: org.gradle.api.internal.initialization.DefaultClassLoaderScope@12345buildDir: /home/user/gradle/samples/userguide/tutorial/projectReports/api/buildbuildFile: /home/user/gradle/samples/userguide/tutorial/projectReports/api/build.gradle

1.7.8. build过程描述

在将构建过程报告保存至build/reports/profile中时，使用--profile参数可以记录一些有用的时间信息。

1.8. 运行预演

有些时候你可能希望知道命令行中指定的多个命令的执行任务和任务执行顺序，但不想真正执行这些任务，可以使用-m参数。

gradle -m test的输出：

:compile SKIPPED:compileTest SKIPPED:test SKIPPED

1.9. 小结

本章讲解了命令行中执行任务的内容，如果想了解更多命令行相关的内容，可以参考Appendix D, Gradle Command Line