GradleUserGuide中文版 10)网页应用 11)Gradle命令行

10 网页应用快速入门

Gradle 提供了两个插件用来支持网页应用: War 插件和 Jetty 插件.
War 插件是在 Java 插件的基础上扩充的用来构建 WAR 文件.
Jetty 插件是在 War 插件的基础上扩充的, 允许用户将网页应用发布到一个介入的 Jetty 容器里.

10.1 构建一个 WAR 文件

为了构建一个 WAR 文件, 需要在项目中加入 War 插件:

9-1 War 插件
build.gradle

apply plugin: 'war'

samples/webApplication/quickstart

这个插件也会在你的项目里加入 Java 插件. 运行 gradle build 将会编译, 测试和创建项目的 WAR 文件. Gradle 将会把源文件包含在 WAR 文件的 src/main/webapp 目录里. 编译后的 classe , 和它们运行所需要的依赖也会被包含在 WAR 文件里.

10.2 Running your web application

要启动Web工程,在项目中加入Jetty plugin即可:

9-2 采用Jetty plugin启动web工程
build.gradle

apply plugin: 'jetty'

由于Jetty plugin继承自War plugin.使用 gradle jettyRun 命令将会把你的工程启动部署到jetty容器中. 调用 gradle jettyRunWar 命令会打包并启动部署到jetty容器中.

Groovy web applications 可以结合多个插件在一个项目中, 所以可以一起使用War 和 Groovy插件构建一个 Groovy 基础 web 应用.合适的 Groovy 类库会添加到你的 WAR 文件中.

TODO: which url, configure port, uses source files in place and can edit your files and reload.

10.3 总结

Chapter 26,The War Plugin
Chapter 28,The Jetty Plugin
samples/webApplication

11 使用 Gradle命令行

11.1 多任务调用

可以以列表的形式在命令行中一次调用多个任务.
e.g. gradle compile test 命令会依次调用 compile 和 test 任务, 它们所依赖的任务也会被调用. 这些任务只会被调用一次, 无论它们是否被包含在脚本中: 即无论是以命令行的形式定义的任务还是依赖于其它任务都会被调用执行.

下面定义了四个任务 dist和test 都 依赖于 compile ,只用当 compile 被调用之后才会调用 gradle dist test 任务
p11-1 任务依赖

11-1 多任务调用
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 命令的输出

> 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效果是相同的.

11.2 排除任务

可以用命令行选项 -x来排除某些任务
11-2 排除任务
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 和其它任务同时依赖的任务仍然会被调用.

11.3 失败后继续执行构建

默认情况下, 只要有任务调用失败, Gradle就会中断执行. 这可能会使调用过程更快, 但那些后面隐藏的错误就没有办法发现了. 所以可以使用 --continue 选项在一次调用中尽可能多的发现所有问题.

采用 --continue 选项, Gralde 会调用每一个任务以及它们依赖的任务. 而不是一旦出现错误就会中断执行. 所有错误信息都会在最后被列出来.

一旦某个任务执行失败,那么所有依赖于该任务的子任务都不会被调用.
e.g. 由于 test 任务依赖于 complie 任务,所以如果 compile 调用出错, test 便不会被直接或间接调用.

11.4 简化任务名

当试图调用某个任务的时候, 你并不需要输入任务的全名. 只需提供足够的可以唯一区分出该任务的字符即可.
e.g. 上面的例子你也可以这么写. 用 gradle di 来直接调用 dist 任务:
11-3 简化任务名
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

也可以用在驼峰命名方式 (通俗的说就是每个单词的第一个字母大写,除了第一个单词) 的任务中每个单词的首字母进行调用.
e.g. 可以执行 gradle compTest 或者 gradle cT 来调用 compileTest 任务

11-4 简化驼峰方式的任务名
gradle cT 命令的输出

> gradle cT
:compile
compiling source
:compileTest
compiling unit tests

BUILD SUCCESSFUL

Total time: 1 secs

简化后你仍然可以使用-x参数.

11.5 选择执行构建

调用 gradle 命令时, 默认情况下总是会构建当前目录下的文件, 可以使用 -b 参数选择其他目录的构建文件, 并且当你使用此参数时 settings.gradle 将不会生效

11-5 选择文件构建
subdir/myproject.gradle

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

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

gradle -q -b subdir/myproject.gradle hello
using build file 'myproject.gradle' in 'subdir'.

另外, 可以使用 -p 参数来指定构建的目录, e.g. 在多项目构建中可以用 -p 来替代 -b 参数
11-6 选择构建目录
gradle -q -p subdir hello 命令的输出

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

-b 参数用以指定脚本具体所在位置, 格式为 dirpwd/build.gradle.
-p 参数用以指定脚本目录即可.

11.6 获取构建信息

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

参阅项目报告插件

11.6.1 项目列表

执行 gradle projects 命令会为你列出子项目名称列表.
11-7 收集项目信息
命令的输出结果

> 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 属性来指定这些描述信息.

11-8 为项目添加描述信息
build.gradle

description = 'The shared API for the application'

11.6.2 任务列表

执行 gradle tasks 命令会列出项目中所有任务. 这会显示项目中所有的默认任务以及每个任务的描述.
11-9 获取任务信息
命令的输出

> 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 来把 这些信息展示到结果中.

11-10 更改任务报告内容
build.gradle

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

也可以用 –all 参数来收集更多任务信息. 这会列出项目中所有任务以及任务之间的依赖关系.

11-11 获得更多的任务信息
命令的输出

> 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'.
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
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 获取任务具体信息

执行 gradle help –task someTask 可以显示指定任务的详细信息. 或者多项目构建中相同任务名称的所有任务的信息.

11-12 获取任务帮助
输出结果

> 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

结果包含了任务的路径、类型以及描述信息等.

11.6.4 获取依赖列表

执行 gradle dependencies 命令会列出项目的依赖列表, 所有依赖会根据任务区分,以树型结构展示出来.
11-13 获取依赖信息
输出结果

> 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.3

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.3.3
\--- commons-io:commons-io:1.2

testCompile
No dependencies

虽然输出结果很多, 但这对于了解构建任务十分有用, 当然可以通过 –configuration 参数来查看 指定构建任务的依赖情况:
11-14 过滤依赖信息

> 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

11.6.5 查看特定依赖

执行 gradle dependencyInsight 命令可以查看指定的依赖.
11-15 获取特定依赖

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

这个 task 对于了解依赖关系、了解为何选择此版本作为依赖十分有用.

DependencyInsightReportTask

dependencyInsight 任务是’Help’任务组中的一个. 这项任务需要进行配置才可以使用. Report 查找那些在指定的配置里特定的依赖.

如果用了Java相关的插件, 那么 dependencyInsight 任务已经预先被配置到 ‘compile’下了. 只需要通过 ‘–dependency’ 参数来制定所需查看的依赖即可. 如果不想用默认配置的参数项可以通过’–configuration’参数来进行指定.

11.6.6 获取项目属性列表

执行 gradle properties 可以获取项目所有属性列表.
11-16 属性信息

> 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
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 构建日志

–profile 参数可以收集一些构建期间的信息并保存到 build/reports/profile 目录下. 并且会以构建时间命名这些文件.

下面的日志记录了总体花费时间以及各过程花费的时间. 并以时间大小倒序排列. 并且记录了任务的执行情况.
如果采用了 buildSrc, 那么在 buildSrc/build 下同时也会生成一份日志记录记录.

—TBC—
—YCR—