Chapter 11. Using the Gradle Command-Line 使用 Gradle 命令行

    同个构建可以执行多个 task ,通过再命令行 列出每个 task。举例，命令
    将会执行 compile 和 test 两个 task。
    Gradle 将会按顺序执行 命令行每个列出的 task，并且执行每个 task 的依赖。每个任务仅执行一次，不管它是如何被包含在构建中：无论是在命令行中指定，或作为另一个 task 的依赖，或两者都是。让我们看一个例子。

    下面定义了4个 task。 dist 和 test 都依赖于 compile 。执行 gradle dist test ，compile 将会仅仅被执行一次。

    Figure 11.1. Task dependencies

    Example 11.1. Executing multiple tasks

    build.gradle

    执行 gradle dist test 输出 

    1. > gradle dist test
    2. :compile
    3. compiling source
    4. :compileTest
    5. compiling unit tests
    6. :test
    7. running unit tests
    8. :dist
    9. building the distribution
    11. BUILD SUCCESSFUL
    13. Total time: 1 secs

    每个 task 只执行一次，所以 gradle test test 跟 gradle test 执行结果一样。

    11.2. Excluding tasks 排除 task

    可以通过 -x 命令行来排除 task 被执行。如下：

    Example 11.2. Excluding tasks

    执行 gradle dist -x test 输出

    1. > gradle dist -x test
    2. :compile
    3. compiling source
    4. :dist
    5. building the distribution
    7. BUILD SUCCESSFUL

    Total time: 1 secs

    可以看到 ，test 并未执行，即使它是 dist 的依赖。同时注意到， test 的依赖，如 compileTest 也未执行。这些 test 的依赖如果是被其他 task 所需要的话，如 compile 仍会执行。

    默认情况下，只要任何 task 失败，Gradle 将中止执行。这使得构建更快地完成，但隐藏了其他可能发生的故障。为了发现在一个单一的构建中多个可能发生故障的地方，你可以使用 —continue 选项。

    通过执行 —continue ，Gralde 会执行每一个 task ，当那个 task 所有的依赖都无故障的执行完成, 而不是一旦出现错误就会中断执行。所有故障信息都会在最后报告出来。

    一旦某个 task 执行失败,那么所有依赖于该 task 的后面的 task 都不会被执行，因为这样做不安全。例如，在测试时，当编译代码失败则测试不会执行。因为 测试 task 将取决于 编译 task（不管是直接或间接）。

    11.4. Task name abbreviation 任务名称缩写

    当你试图执行某个 task 的时候,无需输入 task 的全名.只需提供足够的可以唯一区分出该 task 的字符即可。例如,上面的例子你也可以这么写, 用 gradle di 来直接调用 dist 。

    Example 11.3. Abbreviated task name

    执行 gradle di

    1. > gradle di
    2. :compile
    3. compiling source
    4. :compileTest
    5. compiling unit tests
    6. :test
    7. running unit tests
    8. :dist
    9. building the distribution
    11. BUILD SUCCESSFUL
    13. Total time: 1 secs

    同时也可以应用在驼峰的 task 名称。如，执行 compileTest 时，运行
    gradle compTest 或者 gradle cT 都可以。

    Example 11.4. Abbreviated camel case task name

    执行 gradle cT

    1. > gradle cT
    2. :compile
    3. compiling source
    4. :compileTest
    5. compiling unit tests
    7. BUILD SUCCESSFUL
    9. Total time: 1 secs

    同时，也可以应用在 -x 命令选项。

    Example 11.5. Selecting the project using a build file

    subdir/myproject.gradle

    1.     println "using build file '$buildFile.name' in '$buildFile.parentFile.name'."
    2. }

    执行 gradle -q -b subdir/myproject.gradle hello 输出

    或者，您可以使用 -p 选项来指定要使用的项目目录。多 project 的构建时应使用 -p 选项来代替 -b 选项。

    Example 11.6. Selecting the project using project directory

    执行 gradle -q -p subdir hello 输出

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

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

    Gradle 提供了许多内置 task 来收集构建信息。这些内置 task 对于了解依赖结构以及解决问题都是很有帮助的.

    了解更多,可以参阅,可以为你的项目添加构建报告

    执行 gradle projects 会为你列出选中项目的子项目列表.如下例.

    Example 11.7. Obtaining information about projects

    执行 gradle -q projects 输出

    1. > gradle -q projects
    2. ------------------------------------------------------------
    4. ------------------------------------------------------------
    6. Root project 'projectReports'
    7. +--- Project ':api' - The shared API for the application
    8. \--- Project ':webapp' - The Web application implementation
    10. To see a list of the tasks of a project, run gradle <project-path>:tasks
    11. For example, try running gradle :api:tasks

    这份报告展示了每个项目的描述信息。当然你可以在项目中用 description属性来指定这些描述信息。

    Example 11.8. Providing a description for a project

    build.gradle

    1. description = 'The shared API for the application'

    11.6.2. Listing tasks 任务列表

    执行 gradle tasks 会列出项目中所有 task。这份报告显示项目中所有的默认 task 以及每个 task 的描述。如下

    Example 11.9. Obtaining information about tasks

    执行 gradle -q tasks 输出

    1. > gradle -q tasks
    2. ------------------------------------------------------------
    3. All tasks runnable from root project
    4. ------------------------------------------------------------
    6. Default tasks: dists
    8. Build tasks
    9. -----------
    10. clean - Deletes the build directory (build)
    11. dists - Builds the distribution
    12. libs - Builds the JAR
    14. Build Setup tasks
    15. -----------------
    16. init - Initializes a new Gradle build. [incubating]
    17. wrapper - Generates Gradle wrapper files. [incubating]
    19. Help tasks
    20. ----------
    21. components - Displays the components produced by root project 'projectReports'. [incubating]
    22. dependencies - Displays all dependencies declared in root project 'projectReports'.
    23. dependencyInsight - Displays the insight into a specific dependency in root project 'projectReports'.
    24. help - Displays a help message.
    25. projects - Displays the sub-projects of root project 'projectReports'.
    26. properties - Displays the properties of root project 'projectReports'.
    27. tasks - Displays the tasks runnable from root project 'projectReports' (some of the displayed tasks may belong to subprojects).
    29. To see all tasks and more detail, run with --all.

    默认情况下,这只会显示那些被分组的 task.你可以通过为 task 设置group 属性和 description 来把这些信息展示到报告中

    Example 11.10. Changing the content of the task report

    build.gradle

    1. dists {
    2.     description = 'Builds the distribution'
    3.     group = 'build'
    4. }

    当然你也可以用 —all 参数来收集更多 task 信息。这报告列出项目中所有被主 task 的分组的 task 以及 task 之间的依赖关系。下面是示例

    Example 11.11. Obtaining more information about tasks

    执行 gradle -q tasks —all 输出

    Example 11.12. Obtaining detailed help for tasks

    执行 gradle -q help —task libs 输出

    1. > gradle -q help --task libs
    2. Detailed task information for libs
    4. Paths
    5.      :api:libs
    6.      :webapp:libs
    8. Type
    10. Description

    这些结果包含了完整的 task 的路径、类型、可能的命令行选项以及描述信息等.

    11.6.4. Listing project dependencies 依赖列表

    执行 gradle dependencies 会列出项目的依赖列表,所有依赖会根据任务区分,以树型结构展示出来。如下

    Example 11.13. Obtaining information about dependencies

    执行 gradle -q dependencies api:dependencies webapp:dependencies 输出

    1. > gradle -q dependencies api:dependencies webapp:dependencies
    2. ------------------------------------------------------------
    3. Root project
    4. ------------------------------------------------------------
    6. No configurations
    8. ------------------------------------------------------------
    9. Project :api - The shared API for the application
    10. ------------------------------------------------------------
    12. compile
    13. \--- org.codehaus.groovy:groovy-all:2.3.6
    15. testCompile
    16. \--- junit:junit:4.11
    17.      \--- org.hamcrest:hamcrest-core:1.3
    19. ------------------------------------------------------------
    20. Project :webapp - The Web application implementation
    21. ------------------------------------------------------------
    23. compile
    24. +--- project :api
    25. |    \--- org.codehaus.groovy:groovy-all:2.3.6
    26. \--- commons-io:commons-io:1.2
    28. testCompile
    29. No dependencies

    由于依赖的报告可以变得较大，可以使用特定的配置来限制到一个有用的报告。可以通过 —configuration 可选参数来实现。

    Example 11.14. Filtering dependency report by configuration

    执行 gradle -q api:dependencies —configuration testCompile 输出为

    1. > gradle -q api:dependencies --configuration testCompile
    2. ------------------------------------------------------------
    3. Project :api - The shared API for the application
    4. ------------------------------------------------------------
    6. testCompile
    7. \--- junit:junit:4.11
    8.      \--- org.hamcrest:hamcrest-core:1.3

    执行 gradle dependencyInsight 可以查看指定的依赖情况，如下

    Example 11.15. Getting the insight into a particular dependency

    执行 gradle -q webapp:dependencyInsight —dependency groovy —configuration compile 输出

    1. > gradle -q webapp:dependencyInsight --dependency groovy --configuration compile
    2. org.codehaus.groovy:groovy-all:2.3.6
    3. \--- project :api
    4.      \--- compile

    这对于分辨依赖、了解依赖关系、了解为何选择此版本作为依赖十分有用。了解更多请参阅 DependencyInsightReportTask 类的 API

    内建的 dependencyInsight 是’Help’ task 分组中的一个。这项 task 需要进行依赖和配置文件的配置才可以。该报告寻找那些与定依赖规范指定的配置匹配的的依赖。如果应用了 Java 相关的插件，该dependencyinsight task 是预先经过 ‘compile’ 配置，因为它通常依赖我们感兴趣的编译。你应该指定您感兴趣的依赖,通过命令行 ‘—dependency’选项。如果你不喜欢默认的，你可以选择通过 ‘—configuration’ 选项来配置。更多信息见 类的API文档。

    11.6.6. Listing project properties 项目属性列表

    执行 gradle properties 可以获取项目所有属性列表，如下

    Example 11.16. Information about properties

    执行 gradle -q api:properties 输出

    1. > gradle -q api:properties
    2. ------------------------------------------------------------
    3. Project :api - The shared API for the application
    4. ------------------------------------------------------------
    6. allprojects: [project ':api']
    7. ant: org.gradle.api.internal.project.DefaultAntBuilder@12345
    8. antBuilderFactory: org.gradle.api.internal.project.DefaultAntBuilderFactory@12345
    9. artifacts: org.gradle.api.internal.artifacts.dsl.DefaultArtifactHandler_Decorated@12345
    10. asDynamicObject: org.gradle.api.internal.ExtensibleDynamicObject@12345
    11. baseClassLoaderScope: org.gradle.api.internal.initialization.DefaultClassLoaderScope@12345
    12. buildDir: /home/user/gradle/samples/userguide/tutorial/projectReports/api/build
    13. buildFile: /home/user/gradle/samples/userguide/tutorial/projectReports/api/build.gradle

    —profile 命令选项可以记录一些构建期间的信息并保存到 build/reports/profile 目录下并且以构建时间命名这些文件

    该报告列出总时间和在配置和 task 的执行 阶段的细节。并以时间大小倒序排列，并且记录了任务的执行情况

    如果采用了 buildSrc 构建,那么在 buildSrc/build 下同时也会给 buildSrc 生成一份日志记录

    Chapter 11. Using the Gradle Command-Line 使用 Gradle 命令行 - 图1

    有时可能你只想知道某个 task 在一个 task 集中按顺序执行的结果,但并不想实际执行这些 task 。那么你可以用 -m 选项。例如 执行 将会看到所有的作为 clean 和 compile 一部分的 task 会被执行。这与 task 可以形成互补,让你知道哪些 task 可以用于执行。

    11.8. Summary 总结

    本章看到了命令行的一部分。更多详见 Appendix D. Gradle Command Line 命令行