本章介紹了命令行的基本使用.正如在前面的章節裏你所見到的調用 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任務以及它們的依賴任務.
無論它們是否被包含在腳本中:即無論是以命令行的形式定義的任務還是依賴於其它任務都會被調用執行.來看下面的例子.
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,只用當 compile被調用之後纔會調用gradle
dist test任務
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也沒有被調用,而像 compile被test和其它任務同時依賴的任務仍然會被調用.
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選項,Gralde會調用每一個任務以及它們依賴的任務.
而不是一旦出現錯誤就會中斷執行.所有錯誤信息都會在最後被列出來.
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.
一旦某個任務執行失敗,那麼所有依賴於該任務的子任務都不會被調用.例如由於test任務依賴於complie任務,所以如果compile調用出錯,test便不會被直接或間接調用.
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
di來直接調用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
di:
例 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 or even 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參數選擇構建的文件,並且當你使用此參數時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.
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:
執行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
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:
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
----------
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).
執行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.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
雖然輸出結果很多,但這對於瞭解構建任務十分有用,當然你可以通過 --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
執行Running 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.2.0
\--- 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 seeDependencyInsightReportTask.
dependencyInsight任務是'Help'任務組中的一個.這項任務需要進行配置纔可以. 如果用了Java相關的插件,那麼dependencyInsight任務已經預先被配置到'Compile'下了. 你只需要通過'--dependency'參數來制定所需查看的依賴即可.如果你不想用默認配置的參數項你可以通過 '--configuration' 參數來進行指定.瞭解更多請參閱 依賴檢查報告.
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 seeDependencyInsightReportTask.
執行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 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/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 examplegradle
-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 command
in 附錄 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.