Gradle Gradle 命令行的基本使用

本章介紹了命令行的基本使用。正如在前面的章節(jié)里你所見到的調(diào)用 gradle 命令來完成一些功能。

多任務調(diào)用

你可以以列表的形式在命令行中一次調(diào)用多個任務。例如 gradle compile test 命令會依次調(diào)用，并且每個任務僅會被調(diào)用一次。compile 和 test 任務以及它們的依賴任務。無論它們是否被包含在腳本中：即無論是以命令行的形式定義的任務還是依賴于其它任務都會被調(diào)用執(zhí)行。來看下面的例子。

下面定義了四個任務。dist 和 test 都依賴于 compile，只用當 compile 被調(diào)用之后才會調(diào)用 gradle dist test 任務。

任務依賴

多任務調(diào)用

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 的輸出結(jié)果。

\> gradle dist test
:compile
compiling source
:compileTest
compiling unit tests
:test
running unit tests
:dist
building the distribution
BUILD SUCCESSFUL
Total time: 1 secs

由于每個任務僅會被調(diào)用一次，所以調(diào)用 gradle dist test 與調(diào)用 gradle test 效果是相同的。

排除任務

你可以用命令行選項 -x 來排除某些任務，讓我們用上面的例子來示范一下。

排除任務

gradle dist -x test 的輸出結(jié)果。

\> gradle dist -x test
:compile
compiling source
:dist
building the distribution
BUILD SUCCESSFUL
Total time: 1 secs

可以看到，test 任務并沒有被調(diào)用，即使他是 dist 任務的依賴。同時 test 任務的依賴任務 compileTest 也沒有被調(diào)用，而像 compile 被 test 和其它任務同時依賴的任務仍然會被調(diào)用。

失敗后繼續(xù)執(zhí)行

默認情況下只要有任務調(diào)用失敗 Gradle 就是中斷執(zhí)行。這可能會使調(diào)用過程更快，但那些后面隱藏的錯誤不會被發(fā)現(xiàn)。所以你可以使用--continue 在一次調(diào)用中盡可能多的發(fā)現(xiàn)所有問題。

采用了--continue 選項，Gradle會調(diào)用每一個任務以及它們依賴的任務。而不是一旦出現(xiàn)錯誤就會中斷執(zhí)行。所有錯誤信息都會在最后被列出來。

一旦某個任務執(zhí)行失敗,那么所有依賴于該任務的子任務都不會被調(diào)用。例如由于 test 任務依賴于 complie 任務，所以如果 compile 調(diào)用出錯，test 便不會被直接或間接調(diào)用。

簡化任務名

當你試圖調(diào)用某個任務的時候，無需輸入任務的全名。只需提供足夠的可以唯一區(qū)分出該任務的字符即可。例如，上面的例子你也可以這么寫。用 gradle di 來直接調(diào)用 dist 任務。

簡化任務名

gradle di 的輸出結(jié)果

\> gradle di
:compile
compiling source
:compileTest
compiling unit tests
:test
running unit tests
:dist
building the distribution
BUILD SUCCESSFUL
Total time: 1 secs

你也可以用駝峰命名的任務中每個單詞的首字母進行調(diào)用。例如，可以執(zhí)行 gradle compTest or even gradle cT 來調(diào)用 compileTest 任務。

簡化駝峰任務名

gradle cT 的輸出結(jié)果。

\> gradle cT
:compile
compiling source
:compileTest
compiling unit tests
BUILD SUCCESSFUL
Total time: 1 secs

簡化后你仍然可以使用 -x 參數(shù)。

選擇構(gòu)建位置

調(diào)用 gradle 時，默認情況下總是會構(gòu)建當前目錄下的文件，可以使用-b 參數(shù)選擇構(gòu)建的文件，并且當你使用此參數(shù)時settings.gradle 將不會生效,看下面的例子:

選擇文件構(gòu)建

subdir/myproject.gradle

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

gradle -q -b subdir/myproject.gradle hello 的輸出結(jié)果

Output of gradle -q -b subdir/myproject.gradle hello
\> gradle -q -b subdir/myproject.gradle hello
using build file 'myproject.gradle' in 'subdir'.

另外，你可以使用 -p 參數(shù)來指定構(gòu)建的目錄，例如在多項目構(gòu)建中你可以用 -p 來替代 -b 參數(shù)。

選擇構(gòu)建目錄

gradle -q -p subdir hello 的輸出結(jié)果

\> gradle -q -p subdir hello
using build file 'build.gradle' in 'subdir'.

獲取構(gòu)建信息

Gradle 提供了許多內(nèi)置任務來收集構(gòu)建信息。這些內(nèi)置任務對于了解依賴結(jié)構(gòu)以及解決問題都是很有幫助的。

了解更多，可以參閱項目報告插件以為你的項目添加構(gòu)建報告。

項目列表

執(zhí)行 gradle projects 會為你列出子項目名稱列表。如下例。

收集項目信息

gradle -q projects 的輸出結(jié)果

\> 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 屬性來指定這些描述信息。

為項目添加描述信息.

build.gradle

description = 'The shared API for the application'

任務列表

執(zhí)行 gradle tasks 會列出項目中所有任務。這會顯示項目中所有的默認任務以及每個任務的描述。如下例

獲取任務信息

gradle -q tasks的輸出結(jié)果：

\> 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 來把 這些信息展示到結(jié)果中。

更改任務報告內(nèi)容

build.gradle

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

當然你也可以用--all 參數(shù)來收集更多任務信息。這會列出項目中所有任務以及任務之間的依賴關系。

Obtaining more information about tasks

gradle -q tasks --all的輸出結(jié)果：

\> 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'.
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).

獲取任務幫助信息

執(zhí)行 gradle help --task someTask 可以顯示指定任務的詳細信息。或者多項目構(gòu)建中相同任務名稱的所有任務的信息。如下例。

獲取任務幫助

gradle -q help --task libs 的輸出結(jié)果

\> 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

這些結(jié)果包含了任務的路徑、類型以及描述信息等。

獲取依賴列表

執(zhí)行 gradle dependencies 會列出項目的依賴列表，所有依賴會根據(jù)任務區(qū)分，以樹型結(jié)構(gòu)展示出來。如下例。

獲取依賴信息

gradle -q dependencies api:dependencies webapp:dependencies 的輸出結(jié)果

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

雖然輸出結(jié)果很多，但這對于了解構(gòu)建任務十分有用，當然你可以通過--configuration 參數(shù)來查看 指定構(gòu)建任務的依賴情況。

過濾依賴信息

gradle -q api:dependencies --configuration testCompile 的輸出結(jié)果

\> 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

查看特定依賴

執(zhí)行 Running gradle dependencyInsight 可以查看指定的依賴情況。如下例。

獲取特定依賴

gradle -q webapp:dependencyInsight --dependency groovy --configuration compile 的輸出結(jié)果

\> gradle -q webapp:dependencyInsight --dependency groovy --configuration compile
org.codehaus.groovy:groovy-all:2.2.0
\--- project :api
     \--- compile

這對于了解依賴關系、了解為何選擇此版本作為依賴十分有用。了解更多請參閱依賴檢查報告。

dependencyInsight 任務是'Help'任務組中的一個。這項任務需要進行配置才可以。如果用了 Java 相關的插件，那么 dependencyInsight 任務已經(jīng)預先被配置到'Compile'下了。你只需要通過'--dependency'參數(shù)來制定所需查看的依賴即可。如果你不想用默認配置的參數(shù)項你可以通過 '--configuration' 參數(shù)來進行指定。了解更多請參閱依賴檢查報告。

獲取項目屬性列表

執(zhí)行 gradle properties 可以獲取項目所有屬性列表。如下例。

屬性信息

gradle -q api:properties 的輸出結(jié)果

\> 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
buildDir: /home/user/gradle/samples/userguide/tutorial/projectReports/api/build
buildFile: /home/user/gradle/samples/userguide/tutorial/projectReports/api/build.gradle

構(gòu)建日志

--profile 參數(shù)可以收集一些構(gòu)建期間的信息并保存到 build/reports/profile 目錄下并且以構(gòu)建時間命名這些文件。

下面這份日志記錄了總體花費時間以及各過程花費的時間，并以時間大小倒序排列，并且記錄了任務的執(zhí)行情況。

如果采用了 buildSrc，那么在 buildSrc/build 下同時也會生成一份日志記錄記錄。

Dry Run

有時可能你只想知道某個任務在一個任務集中按順序執(zhí)行的結(jié)果，但并不想實際執(zhí)行這些任務。那么你可以用-m 參數(shù)。例如 gradle -m clean compile 會調(diào)用 clean 和 compile，這與 tasks 可以形成互補，讓你知道哪些任務可以用于執(zhí)行。

本章小結(jié)

在本章中你學到很多用命令行可以做的事情，了解更多你可以參閱 gradle command in 附錄 D， Gradle 命令行。