命令行界面是与Gradle交互的主要方法之一. 以下内容作为执行和自定义Gradle使用命令行或编写脚本或配置持续集成时的参考.

强烈建议使用Gradle包装器 . 您应该取代./gradlewgradlew.batgradle使用的包装时,在所有下面的例子.

在命令行上执行Gradle符合以下结构. 任务名称之前和之后均允许使用选项.

gradle [taskName...] [--option-name...]

如果指定了多个任务,则应以空格分隔.

可以在选项和参数之间使用=或不使用=来指定接受值的选项. 但是,建议使用= .

--console=plain

启用行为的选项具有长格式的选项,并带有--no-指定的--no- . 以下是相反的情况.

--build-cache
--no-build-cache

许多长格式期权具有短期权等价物. 以下是等效的:

--help
-h

可以在gradle.properties指定许多命令行标志,以避免需要输入. 有关详细信息,请参见《 配置构建环境指南 》.

以下各节介绍了Gradle命令行界面的使用,大致按用户目标分组. 一些插件还添加了自己的命令行选项,例如--tests用于Java测试过滤 . 有关为自己的任务公开命令行选项的更多信息,请参见声明和使用命令行选项 .

Executing tasks

您可以运行任务及其所有依赖项 .

$ gradle myTask

您可以在" 项目报告"部分中了解哪些项目和任务可用.

大多数构建都支持一组常见的任务,称为生命周期任务 . 这些包括buildassemblecheck任务.

Executing tasks in multi-project builds

多项目构建中 ,子项目任务可以使用":"分隔子项目名称和任务名称来执行. 从根项目运行时 ,以下内容等效.

$ gradle :mySubproject:taskName
$ gradle mySubproject:taskName

您也可以仅使用任务名称为所有子项目运行任务. 例如,当从根项目目录中调用时,这将为所有子项目运行"测试"任务.

$ gradle test

从子项目中调用Gradle时,应省略项目名称:

$ cd mySubproject
$ gradle taskName

从子项目执行Gradle Wrapper时,必须相对引用gradlew . 例如: ../gradlew taskName . gdub社区项目旨在使此操作更加方便.

Executing multiple tasks

You can also specify multiple tasks. For example, the following will execute the test and deploy tasks in the order that they are listed on the command-line and will also execute the dependencies for each task.

$ gradle test deploy

Excluding tasks from execution

您可以使用-x--exclude-task命令行选项并提供要排除的任务名称来排除正在执行的任务.

commandLineTutorialTasks
图1.简单任务图
排除任务
$ gradle dist --exclude-task test

> Task :compile
compiling source

> Task :dist
building the distribution

BUILD SUCCESSFUL in 0s
2 actionable tasks: 2 executed

您可以看到test任务没有执行,即使它是dist任务的依赖项. test任务的依赖项(例如compileTest也不会执行. 其他任务(例如compile所需的那些test依赖关系仍将执行.

Forcing tasks to execute

您可以使用--rerun-tasks选项强制Gradle执行所有任务,而忽略最新检查

$ gradle test --rerun-tasks

这将迫使test所有任务相关test执行. 这有点像运行gradle clean test ,但是没有删除生成的生成输出.

Continuing the build when a failure occurs

默认情况下,Gradle将中止执行并在任何任务失败后立即使构建失败. 这样可以使构建更快完成,但可以隐藏其他可能发生的故障. 为了在一次构建执行中发现尽可能多的故障,可以使用--continue选项.

$ gradle test --continue

当执行--continue ,摇篮将执行到被执行一项任务都在那里,而不是只要遇到第一个故障停止依赖该任务无故障完成. 每个遇到的故障将在构建结束时报告.

如果任务失败,则将不执行任何依赖于该任务的后续任务. 例如,如果被测代码中的编译失败,则测试将不会运行. 因为测试任务(直接或间接)取决于编译任务.

Task name abbreviation

在命令行上指定任务时,不必提供任务的全名. 您只需要提供足够的任务名称即可唯一地标识任务. 例如, gradle che足以使Gradle识别check任务.

您也可以在驼峰式任务名称中缩写每个单词. 例如,您可以通过运行gradle compTest甚至gradle cT来执行任务compileTest .

缩写骆驼案例任务名称
$ gradle cT

> Task :compile
compiling source

> Task :compileTest
compiling unit tests

BUILD SUCCESSFUL in 0s
2 actionable tasks: 2 executed

您也可以将这些缩写与-x命令行选项一起使用.

Common tasks

以下是内置和大多数主要Gradle插件应用的任务约定.

Computing all outputs

在Gradle构建中, build任务通常会指定组装所有输出并运行所有检查.

$ gradle build

Running applications

应用程序通常与run任务一起运行, run任务将组装应用程序并执行一些脚本或二进制文件.

$ gradle run

Running all checks

使用check任务执行所有验证任务(包括测试和棉绒)是很常见的.

$ gradle check

Cleaning outputs

您可以使用clean任务删除构建目录的内容,尽管这样做会导致预先计算的输出丢失,从而导致后续任务执行需要大量额外的构建时间.

$ gradle clean

Project reporting

Gradle提供了一些内置任务,这些任务显示了构建的特定细节. 这对于理解构建的结构和依赖性以及调试问题很有用.

您可以使用gradle help获得有关可用报告选项的gradle help .

Listing projects

运行gradle projects会为您提供所选项目的子项目列表,以层次结构显示.

$ gradle projects

您还可以在构建扫描中获得项目报告. 了解有关创建构建扫描的更多信息.

Listing tasks

运行gradle tasks可为您提供所选项目的主要任务列表. 该报告显示项目的默认任务(如果有)以及每个任务的描述.

$ gradle tasks

默认情况下,此报告仅显示已分配给任务组的那些任务. 您可以使用--all选项在任务列表中获取更多信息.

$ gradle tasks --all

如果需要更精确,则可以使用--group选项仅显示特定组中的任务.

$ gradle tasks --group="build setup"

Show task usage details

运行gradle help --task someTask可为您提供有关特定任务的详细信息.

获取任务的详细帮助
$ 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

Group
     build

此信息包括完整的任务路径,任务类型,可能的命令行选项以及给定任务的描述.

Reporting dependencies

生成扫描会提供完整的可视化报告,说明存在哪些依赖关系,哪些配置,可传递依赖关系以及依赖关系版本选择.

$ gradle myTask --scan

这将为您提供一个基于Web的报告的链接,您可以在其中找到类似的依赖项信息.

Build Scan dependencies report

查看和调试依赖项中了解更多信息.

Listing project dependencies

运行gradle dependencies可为您提供所选项目的依赖项列表, gradle dependencies配置细分. 对于每种配置,该配置的直接和传递依赖性在树中显示. 以下是此报告的示例:

$ gradle dependencies

查看和调试依赖项中提供了构建脚本和输出的具体示例.

运行gradle buildEnvironment可视化所选项目的buildscript依赖关系,类似于gradle dependencies如何可视化所构建软件的依赖关系.

$ gradle buildEnvironment

运行gradle dependencyInsight可让您深入了解与指定输入匹配的特定依赖项.

$ gradle dependencyInsight

由于依赖性报告可能会很大,因此将报告限制为特定配置可能很有用. 这是通过可选的--configuration参数实现的:

Listing project properties

运行gradle 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_Decorated@12345
asDynamicObject: DynamicObject for project ':api'
baseClassLoaderScope: org.gradle.api.internal.initialization.DefaultClassLoaderScope@12345

Software Model reports

您可以使用model任务获得软件模型项目的元素的分层视图:

$ gradle model

在软件模型文档中了解有关模型报告的更多信息.

Command-line completion

Gradle通过gradle-completion (单独安装)为任务,选项和Gradle属性提供bash和zsh选项卡补全支持 .

gradle completion 4.0
图2. Gradle完成

Debugging options

-?, -h, --help

显示带有所有可用CLI选项的帮助消息.

-v, --version

打印Gradle,Groovy,Ant,JVM和操作系统版本信息.

-S, --full-stacktrace

打印出完整的(非常详细的)堆栈跟踪信息以了解任何异常. 另请参阅日志记录选项 .

-s, --stacktrace

还打印出堆栈跟踪信息以了解用户异常(例如,编译错误). 另请参阅日志记录选项 .

--scan

使用有关Gradle构建各个方面的详细信息创建构建扫描 .

-Dorg.gradle.debug=true

调试Gradle客户端(非守护程序)进程. Gradle默认会等待您在localhost:5005附加调试器.

-Dorg.gradle.daemon.debug=true

Debug Gradle Daemon process.

Performance options

优化构建性能时,请尝试以下选项. 在此处了解有关提高Gradle构建的性能的更多信息.

可以在gradle.properties指定许多这些选项,因此gradle.properties命令行标志. 请参阅《 配置构建环境指南》 .

--build-cache, --no-build-cache

切换Gradle构建缓存 . Gradle将尝试重用以前版本的输出. 默认为关闭 .

--configure-on-demand, --no-configure-on-demand

切换按需配置 . 在此构建运行中仅配置相关项目. 默认为关闭 .

--max-workers

设置Gradle可以使用的最大工人数. 默认值为处理器数量 .

--parallel, --no-parallel

并行构建项目. 有关此选项的限制,请参见并行项目执行 . 默认为关闭 .

--priority

指定Gradle守护程序及其启动的所有进程的调度优先级. 值是normal还是low . 默认为正常 .

--profile

$buildDir/reports/profile目录中生成高级性能报告. --scan是首选.

--scan

生成带有详细性能诊断的构建扫描.

Build Scan performance report

Gradle daemon options

您可以通过以下命令行选项管理Gradle守护程序 .

--daemon, --no-daemon

使用Gradle守护程序运行构建. 如果守护程序未运行或现有守护程序繁忙,则启动该守护程序. 默认为on .

--foreground

在前台进程中启动Gradle守护程序.

--status (Standalone command)

运行gradle --status以列出正在运行的和最近停止的Gradle守护进程. 仅显示相同Gradle版本的守护程序.

--stop (Standalone command)

运行gradle --stop停止所有相同版本的Gradle守护进程.

-Dorg.gradle.daemon.idletimeout=(number of milliseconds)

在这段毫秒的空闲时间后,Gradle守护程序将自行停止. 默认值为10800000 (3小时).

Logging options

Setting log level

您可以使用以下选项自定义Gradle日志记录的详细程度,其顺序从最小详细到最大详细. 在日志记录文档中了解更多信息 .

-Dorg.gradle.logging.level=(quiet,warn,lifecycle,info,debug)

通过Gradle属性设置日志记录级别.

-q, --quiet

仅记录错误.

-w, --warn

将日志级别设置为警告.

-i, --info

将日志级别设置为info.

-d, --debug

登录调试模式(包括正常的stacktrace).

生命周期是默认的日志级别.

Customizing log format

您可以通过以下方式指定"控制台"模式来控制丰富输出(颜色和字体变体)的使用:

-Dorg.gradle.console=(auto,plain,rich,verbose)

通过Gradle属性指定控制台模式. 下文将介绍不同的模式.

--console=(auto,plain,rich,verbose)

指定要生成的控制台输出的类型.

设置为plain文本仅生成纯文本. 此选项禁用控制台输出中的所有颜色和其他丰富输出. 当Gradle 连接到终端时,这是默认设置.

设置为auto (默认值)以在将构建过程附加到控制台时在控制台输出中启用颜色和其他丰富的输出,或者仅在未附加到控制台时才生成纯文本. 当Gradle连接到终端时,这是默认设置.

设置为" rich可在控制台输出中启用颜色和其他丰富的输出,而不管构建过程是否未附加到控制台. 如果未附加到控制台,则构建输出将使用ANSI控制字符来生成丰富的输出.

设置为verbose以启用颜色和其他丰富的输出,例如rich ,但是在生命周期日志级别输出任务名称和结果,这在Gradle 3.5和更早版本中是默认完成的.

Showing or hiding warnings

默认情况下,Gradle不会显示所有警告(例如,弃用警告). 相反,Gradle将收集它们并在构建结束时呈现摘要,如下所示:

Deprecated Gradle features were used in this build, making it incompatible with Gradle 5.0.

您可以使用以下选项在控制台上控制警告的详细程度:

-Dorg.gradle.warning.mode=(all,fail,none,summary)

Specify warning mode via Gradle properties. Different modes described immediately below.

--warning-mode=(all,fail,none,summary)

指定如何记录警告. 默认为summary .

设置为all以记录所有警告.

设置为fail记录所有警告,如果有任何警告,则构建失败.

设置为summary可禁止显示所有警告,并在构建结束时记录摘要.

设置为none可禁止所有警告,包括构建结束时的摘要.

Rich Console

运行构建时,Gradle的丰富控制台会显示更多信息.

Gradle Rich Console

Features:

  • 进度条和计时器直观地描述了总体状态

  • 下面的并行工作行描述了现在正在发生的事情

  • 颜色和字体用于突出显示重要的输出和错误

Execution options

以下选项通过更改生成的内容或解决依赖关系的方式来影响生成的执行方式.

--include-build

将构建作为组合运行,包括指定的构建. 参见Composite Builds .

--offline

指定该构建应在不访问网络资源的情况下运行. 了解有关覆盖依赖项缓存的选项的更多信息.

--refresh-dependencies

刷新依赖关系的状态. 在依赖管理文档中了解有关如何使用它的更多信息.

--dry-run

在禁用所有任务操作的情况下运行Gradle. 使用它来显示将要执行的任务.

--write-locks

表示所有可锁定的已解析配置都应保留其锁定状态. 了解更多有关依赖锁定的信息 .

--update-locks <group:name>[,<group:name>]*

指示必须在锁定文件中更新指定模块的版本. 此标志还暗示--write-locks . 了解更多有关依赖锁定的信息 .

---no-rebuild

不要重建项目依赖项. 对于调试和微调buildSrc ,但可能导致错误的结果. 请谨慎使用!

Environment options

您可以通过以下选项自定义有关构建脚本,设置,缓存等位置的许多方面. 了解有关自定义构建环境的更多信息.

-b, --build-file

指定构建文件. 例如: gradle --build-file=foo.gradle . 默认值是build.gradle ,然后是build.gradle.kts ,然后是myProjectName.gradle .

-c, --settings-file

指定设置文件. 例如: gradle --settings-file=somewhere/else/settings.gradle

-g, --gradle-user-home

指定Gradle用户的主目录. 默认值为用户主目录中的.gradle目录.

-p, --project-dir

指定Gradle的起始目录. 默认为当前目录.

--project-cache-dir

指定项目特定的缓存目录. 根项目目录中的默认值为.gradle .

-D, --system-prop

设置JVM的系统属性,例如-Dmyprop=myvalue . 请参阅系统属性 .

-I, --init-script

指定初始化脚本. 请参阅初始化脚本 .

-P, --project-prop

设置根项目的项目属性,例如-Pmyprop=myvalue . 请参阅系统属性 .

-Dorg.gradle.jvmargs

设置JVM参数.

-Dorg.gradle.java.home

设置JDK主目录.

Bootstrapping new projects

Creating new Gradle builds

使用内置的gradle init任务创建带有新项目或现有项目的新Gradle构建.

$ gradle init

大多数情况下,您需要指定项目类型. 可用的类型包括basic (默认), java-libraryjava-application等. 有关详细信息,请参见init插件文档 .

$ gradle init --type java-library

Standardize and provision Gradle

内置的gradle wrapper任务生成一个脚本gradlew ,该脚本调用Gradle的声明版本,并在必要时事先下载它.

$ gradle wrapper --gradle-version=4.4

除了--gradle-version之外,您还可以指定--distribution-type=(bin|all) ,-- --gradle-distribution-url ,-- --gradle-distribution-sha256-sum . 有关如何使用这些选项的完整详细信息,请参见Gradle包装器部分 .

Continuous Build

连续构建允许您在任务输入更改时自动重新执行所请求的任务.

例如,您可以通过运行以下命令连续运行test任务和所有相关任务:

$ gradle test --continuous

在更改有助于请求的任务的源或测试之后,Gradle的行为就像您运行gradle test . 这意味着无关的更改(例如,对构建脚本的更改)将不会触发重建. 为了合并构建逻辑更改,必须手动重新启动连续构建.

Terminating Continuous Build

如果Gradle附加到交互式输入源(例如终端),则可以通过按CTRL-D退出连续构建(在Microsoft Windows上,还需要在CTRL-D之后也按ENTERRETURN ). 如果Gradle没有附加到交互式输入源(例如,作为脚本的一部分运行),则必须终止构建过程(例如,使用kill命令或类似命令). 如果构建是通过Tooling API执行的,则可以使用Tooling API的取消机制来取消构建.

Limitations and quirks

当前连续构建的实现要注意几个问题. 这些可能会在将来的Gradle版本中解决.

Build cycles

Gradle在任务执行之前就开始监视更改. 如果任务在执行时修改了自己的输入,Gradle将检测到更改并触发新的构建. 如果每次执行任务时都再次修改输入,则构建将再次触发. 这对于连续构建不是唯一的. 修改自己输入的任务在没有连续构建的情况下"正常"运行时永远不会被视为最新的.

如果您的构建进入这样的构建周期,则可以通过查看Gradle报告的已更改文件列表来跟踪任务. 在确定每次构建过程中更改的文件之后,您应该寻找一个以该文件为输入的任务. 在某些情况下,这可能是显而易见的(例如,使用compileJava编译Java文件). 在其他情况下,您可以使用--info日志记录来查找由于所标识的文件而过时的任务.

Restrictions with Java 9

由于与Java 9相关的类访问限制,Gradle无法设置某些特定于操作系统的选项,这意味着:

  • 在macOS上,Gradle会每10秒而不是每2秒轮询一次文件更改.

  • 在Windows上,Gradle必须使用单独的文件监视程序(例如在Linux / Mac OS上),这可能会导致连续构建不再适用于非常大的项目.

Performance and stability

JDK文件监视功能依赖于macOS上低效的文件系统轮询(请参阅: JDK-7133447 ). 这会大大延迟具有许多源文件的大型项目的更改通知.

此外,监视机制可能会在macOS上的负载下死锁(请参阅: JDK-8079620 ). 这将显示为Gradle似乎没有注意到文件更改. 如果您怀疑发生这种情况,请退出连续构建并重新开始.

On Linux, OpenJDK’s implementation of the file watch service can sometimes miss file system events (see: JDK-8145981).

  • 创建或删除文件的符号链接将启动构建.

  • 修改符号链接的目标不会导致重建.

  • 创建或删除目录的符号链接不会导致重建.

  • 在符号链接的目标目录中创建新文件不会导致重建.

  • Deleting the target directory will not cause a rebuild.

Changes to build logic are not considered

当前的实现不会在以后的构建中重新计算构建模型. 这意味着有效地忽略对任务配置的更改或对构建模型的任何其他更改.