构建脚本
每个 Gradle 构建都包含一个或多个项目;根项目和子项目。
项目通常对应于需要构建的软件组件,例如库或应用程序。它可能代表一个库 JAR、一个 Web 应用程序或由其他项目生成的 JAR 组装而成的分发 ZIP。
另一方面,它可能代表要做的事情,例如将应用程序部署到临时或生产环境。
Gradle 脚本使用 Groovy DSL 或 Kotlin DSL(特定领域语言)编写。
构建脚本配置项目并与 类型的对象关联Project
。
当构建脚本执行时,它会配置Project
.
构建脚本可以是*.gradle
Groovy 中的文件,也可以是*.gradle.kts
Kotlin 中的文件。
构建脚本配置Project 对象及其子对象。
|
物体Project
该对象是Gradle APIProject
的一部分:
构建脚本中的许多顶级属性和块都是项目 API 的一部分。
例如,以下构建脚本使用Project.name属性来打印项目的名称:
println(name)
println(project.name)
println name
println project.name
$ gradle -q check project-api project-api
两个println
语句都打印出相同的属性。
name
第一个使用对象属性的顶级引用Project
。第二条语句使用project
可用于任何构建脚本的属性,该属性返回关联的Project
对象。
标准项目属性
该Project
对象在构建脚本中公开一组标准属性。
下表列出了一些常用的属性:
姓名 | 类型 | 描述 |
---|---|---|
|
|
项目目录的名称。 |
|
|
项目的完全限定名称。 |
|
|
项目的描述。 |
|
|
返回项目的依赖处理程序。 |
|
|
返回项目的存储库处理程序。 |
|
|
提供对项目的几个重要位置的访问。 |
|
|
这个项目的小组。 |
|
|
该项目的版本。 |
下表列出了几种常用的方法:
姓名 | 描述 |
---|---|
|
将文件路径解析为 URI,相对于该项目的项目目录。 |
|
使用给定名称创建一个任务并将其添加到此项目中。 |
构建脚本结构
{ … }
Build 脚本由Groovy 和 Kotlin 中的一个特殊对象组成。该对象在 Kotlin 中称为lambda ,在 Groovy 中称为闭包。
简而言之,该plugins{ }
块是一个方法调用,其中传递 Kotlin lambda对象或 Groovy闭包对象作为参数。它的缩写形式是:
plugins(function() {
id("plugin")
})
块映射到 Gradle API 方法。
函数内的代码针对一个对象执行,该对象在 Kotlin lambda 中this
称为接收器,在 Groovy 闭包中称为委托。 Gradle 确定正确的this
对象并调用正确的相应方法。this
方法调用对象的 的类型id("plugin")
为PluginDependenciesSpec
。
构建脚本本质上是由构建在 DSL 之上的 Gradle API 调用组成。 Gradle 从上到下逐行执行脚本。
让我们看一个例子并将其分解:
plugins { (1)
id("org.jetbrains.kotlin.jvm") version "1.9.0"
id("application")
}
repositories { (2)
mavenCentral()
}
dependencies { (3)
testImplementation("org.jetbrains.kotlin:kotlin-test-junit5")
testImplementation("org.junit.jupiter:junit-jupiter-engine:5.9.3")
testRuntimeOnly("org.junit.platform:junit-platform-launcher")
implementation("com.google.guava:guava:32.1.1-jre")
}
application { (4)
mainClass = "com.example.Main"
}
tasks.named<Test>("test") { (5)
useJUnitPlatform()
}
1 | Apply plugins to the build. |
2 | Define the locations where dependencies can be found. |
3 | Add dependencies. |
4 | Set properties. |
5 | Register and configure tasks. |
plugins { (1)
id 'org.jetbrains.kotlin.jvm' version '1.9.0'
id 'application'
}
repositories { (2)
mavenCentral()
}
dependencies { (3)
testImplementation 'org.jetbrains.kotlin:kotlin-test-junit5'
testImplementation 'org.junit.jupiter:junit-jupiter-engine:5.9.3'
testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
implementation 'com.google.guava:guava:32.1.1-jre'
}
application { (4)
mainClass = 'com.example.Main'
}
tasks.named('test') { (5)
useJUnitPlatform()
}
1 | Apply plugins to the build. |
2 | Define the locations where dependencies can be found. |
3 | Add dependencies. |
4 | Set properties. |
5 | Register and configure tasks. |
1. 将插件应用到构建中
插件用于扩展 Gradle。它们还用于模块化和重用项目配置。
可以使用插件脚本块应用插件PluginDependenciesSpec
。
插件块是首选:
plugins {
id("org.jetbrains.kotlin.jvm") version "1.9.0"
id("application")
}
在示例中,application
已应用 Gradle 附带的插件,将我们的项目描述为 Java 应用程序。
Kotlin gradle 插件 1.9.0 版本也已应用。该插件不包含在 Gradle 中,因此必须使用 aplugin id
和 a进行描述plugin version
,以便 Gradle 可以找到并应用它。
2.定义可以找到依赖的位置
一个项目通常具有完成其工作所需的许多依赖项。依赖项包括 Gradle 必须下载才能成功构建的插件、库或组件。
构建脚本让 Gradle 知道在哪里查找依赖项的二进制文件。可以提供多个位置:
repositories {
mavenCentral()
google()
}
在示例中,将从Maven Central Repository下载guava
库和 JetBrains Kotlin 插件 ( ) 。org.jetbrains.kotlin.jvm
3.添加依赖
一个项目通常具有完成其工作所需的许多依赖项。这些依赖项通常是在项目源代码中导入的预编译类的库。
依赖项通过配置进行管理并从存储库中检索。
使用DependencyHandler
byProject.getDependencies()
方法返回的值来管理依赖关系。使用RepositoryHandler
byProject.getRepositories()
方法返回来管理存储库。
dependencies {
implementation("com.google.guava:guava:32.1.1-jre")
}
在示例中,应用程序代码使用 Google 的guava
库。 Guava 提供了用于集合、缓存、原语支持、并发、通用注释、字符串处理、I/O 和验证的实用方法。
4. 设置属性
插件可以使用扩展向项目添加属性和方法。
该Project
对象有一个关联ExtensionContainer
对象,其中包含已应用于项目的插件的所有设置和属性。
在示例中,application
插件添加了一个application
属性,用于详细说明 Java 应用程序的主类:
application {
mainClass = "com.example.Main"
}
5. 注册并配置任务
任务执行一些基本工作,例如编译类、运行单元测试或压缩 WAR 文件。
虽然任务通常在插件中定义,但您可能需要在构建脚本中注册或配置任务。
注册任务会将任务添加到您的项目中。
您可以使用以下方法在项目中注册任务TaskContainer.register(java.lang.String)
:
tasks.register<Zip>("zip-reports") {
from 'Reports/'
include '*'
archiveName 'Reports.zip'
destinationDir(file('/dir'))
}
您可能已经看到了应该避免的TaskContainer.create(java.lang.String)
方法的用法:
tasks.create<Zip>("zip-reports") {
from 'Reports/'
include '*'
archiveName 'Reports.zip'
destinationDir(file('/dir'))
}
register() ,它可以避免任务配置,优于create() .
|
您可以使用以下方法找到任务并对其进行配置TaskCollection.named(java.lang.String)
:
tasks.named<Test>("test") {
useJUnitPlatform()
}
下面的示例将Javadoc
任务配置为从 Java 代码自动生成 HTML 文档:
tasks.named("javadoc").configure {
exclude 'app/Internal*.java'
exclude 'app/internal/*'
exclude 'app/internal/*'
}
构建脚本
构建脚本由零个或多个语句和脚本块组成:
println(project.layout.projectDirectory);
语句可以包括方法调用、属性分配和局部变量定义:
version = '1.0.0.GA'
脚本块是一个方法调用,它采用闭包/lambda 作为参数:
configurations {
}
闭包/lambda 在执行时配置一些委托对象:
repositories {
google()
}
构建脚本也是 Groovy 或 Kotlin 脚本:
tasks.register("upper") {
doLast {
val someString = "mY_nAmE"
println("Original: $someString")
println("Upper case: ${someString.toUpperCase()}")
}
}
tasks.register('upper') {
doLast {
String someString = 'mY_nAmE'
println "Original: $someString"
println "Upper case: ${someString.toUpperCase()}"
}
}
$ gradle -q upper Original: mY_nAmE Upper case: MY_NAME
它可以包含 Groovy 或 Kotlin 脚本中允许的元素,例如方法定义和类定义:
tasks.register("count") {
doLast {
repeat(4) { print("$it ") }
}
}
tasks.register('count') {
doLast {
4.times { print "$it " }
}
}
$ gradle -q count 0 1 2 3
灵活的任务注册
使用 Groovy 或 Kotlin 语言的功能,您可以在循环中注册多个任务:
repeat(4) { counter ->
tasks.register("task$counter") {
doLast {
println("I'm task number $counter")
}
}
}
4.times { counter ->
tasks.register("task$counter") {
doLast {
println "I'm task number $counter"
}
}
}
$ gradle -q task1 I'm task number 1
声明变量
构建脚本可以声明两个变量:局部变量和额外属性。
局部变量
使用关键字声明局部变量val
。局部变量仅在声明它们的范围内可见。它们是底层 Kotlin 语言的一个功能。
使用关键字声明局部变量def
。局部变量仅在声明它们的范围内可见。它们是底层 Groovy 语言的一个功能。
val dest = "dest"
tasks.register<Copy>("copy") {
from("source")
into(dest)
}
def dest = 'dest'
tasks.register('copy', Copy) {
from 'source'
into dest
}
额外属性
Gradle 的增强对象(包括项目、任务和源集)可以保存用户定义的属性。
通过所属对象的属性添加、读取和设置额外的属性extra
。或者,您可以使用 .kotlin 委托属性来访问额外的属性by extra
。
通过所属对象的属性添加、读取和设置额外的属性ext
。或者,您可以使用ext
块同时添加多个属性。
plugins {
id("java-library")
}
val springVersion by extra("3.1.0.RELEASE")
val emailNotification by extra { "build@master.org" }
sourceSets.all { extra["purpose"] = null }
sourceSets {
main {
extra["purpose"] = "production"
}
test {
extra["purpose"] = "test"
}
create("plugin") {
extra["purpose"] = "production"
}
}
tasks.register("printProperties") {
val springVersion = springVersion
val emailNotification = emailNotification
val productionSourceSets = provider {
sourceSets.matching { it.extra["purpose"] == "production" }.map { it.name }
}
doLast {
println(springVersion)
println(emailNotification)
productionSourceSets.get().forEach { println(it) }
}
}
plugins {
id 'java-library'
}
ext {
springVersion = "3.1.0.RELEASE"
emailNotification = "build@master.org"
}
sourceSets.all { ext.purpose = null }
sourceSets {
main {
purpose = "production"
}
test {
purpose = "test"
}
plugin {
purpose = "production"
}
}
tasks.register('printProperties') {
def springVersion = springVersion
def emailNotification = emailNotification
def productionSourceSets = provider {
sourceSets.matching { it.purpose == "production" }.collect { it.name }
}
doLast {
println springVersion
println emailNotification
productionSourceSets.get().each { println it }
}
}
$ gradle -q printProperties 3.1.0.RELEASE build@master.org main plugin
project
此示例通过 向对象添加两个额外的属性by extra
。此外,此示例purpose
通过设置extra["purpose"]
为为每个源集添加一个名为 的属性null
。添加后,您可以通过读取和设置这些属性extra
。
project
此示例通过块向对象添加两个额外属性ext
。此外,此示例purpose
通过设置ext.purpose
为为每个源集添加一个名为 的属性null
。添加后,您可以像预定义的属性一样读取和设置所有这些属性。
Gradle 需要特殊的语法来添加属性,以便它可以快速失败。例如,这允许 Gradle 识别脚本何时尝试设置不存在的属性。您可以在任何可以访问其所属对象的地方访问额外的属性。这为额外属性提供了比局部变量更广泛的范围。子项目可以访问其父项目的额外属性。
有关额外属性的更多信息,请参阅 API 文档中的ExtraPropertiesExtension 。
配置任意对象
示例greet()
任务显示了任意对象配置的示例:
class UserInfo(
var name: String? = null,
var email: String? = null
)
tasks.register("configure") {
val user = UserInfo().apply {
name = "Isaac Newton"
email = "isaac@newton.me"
}
doLast {
println(user.name)
println(user.email)
}
}
class UserInfo {
String name
String email
}
tasks.register('configure') {
def user = configure(new UserInfo()) {
name = "Isaac Newton"
email = "isaac@newton.me"
}
doLast {
println user.name
println user.email
}
}
$ gradle -q greet Isaac Newton isaac@newton.me
闭幕代表
每个闭包都有一个delegate
对象。 Groovy 使用此委托来查找对非局部变量和闭包参数的变量和方法引用。 Gradle 将其用于配置闭包,其中delegate
对象指的是正在配置的对象。
dependencies {
assert delegate == project.dependencies
testImplementation('junit:junit:4.13')
delegate.testImplementation('junit:junit:4.13')
}
默认导入
为了使构建脚本更加简洁,Gradle 会自动向脚本添加一组 import 语句。
因此,throw new org.gradle.api.tasks.StopExecutionException()
您可以不写throw new StopExecutionException()
而是写。
Gradle 隐式地将以下导入添加到每个脚本中:
import org.gradle.*
import org.gradle.api.*
import org.gradle.api.artifacts.*
import org.gradle.api.artifacts.component.*
import org.gradle.api.artifacts.dsl.*
import org.gradle.api.artifacts.ivy.*
import org.gradle.api.artifacts.maven.*
import org.gradle.api.artifacts.query.*
import org.gradle.api.artifacts.repositories.*
import org.gradle.api.artifacts.result.*
import org.gradle.api.artifacts.transform.*
import org.gradle.api.artifacts.type.*
import org.gradle.api.artifacts.verification.*
import org.gradle.api.attributes.*
import org.gradle.api.attributes.java.*
import org.gradle.api.attributes.plugin.*
import org.gradle.api.cache.*
import org.gradle.api.capabilities.*
import org.gradle.api.component.*
import org.gradle.api.configuration.*
import org.gradle.api.credentials.*
import org.gradle.api.distribution.*
import org.gradle.api.distribution.plugins.*
import org.gradle.api.execution.*
import org.gradle.api.file.*
import org.gradle.api.flow.*
import org.gradle.api.initialization.*
import org.gradle.api.initialization.definition.*
import org.gradle.api.initialization.dsl.*
import org.gradle.api.initialization.resolve.*
import org.gradle.api.invocation.*
import org.gradle.api.java.archives.*
import org.gradle.api.jvm.*
import org.gradle.api.launcher.cli.*
import org.gradle.api.logging.*
import org.gradle.api.logging.configuration.*
import org.gradle.api.model.*
import org.gradle.api.plugins.*
import org.gradle.api.plugins.antlr.*
import org.gradle.api.plugins.catalog.*
import org.gradle.api.plugins.jvm.*
import org.gradle.api.plugins.quality.*
import org.gradle.api.plugins.scala.*
import org.gradle.api.problems.*
import org.gradle.api.provider.*
import org.gradle.api.publish.*
import org.gradle.api.publish.ivy.*
import org.gradle.api.publish.ivy.plugins.*
import org.gradle.api.publish.ivy.tasks.*
import org.gradle.api.publish.maven.*
import org.gradle.api.publish.maven.plugins.*
import org.gradle.api.publish.maven.tasks.*
import org.gradle.api.publish.plugins.*
import org.gradle.api.publish.tasks.*
import org.gradle.api.reflect.*
import org.gradle.api.reporting.*
import org.gradle.api.reporting.components.*
import org.gradle.api.reporting.dependencies.*
import org.gradle.api.reporting.dependents.*
import org.gradle.api.reporting.model.*
import org.gradle.api.reporting.plugins.*
import org.gradle.api.resources.*
import org.gradle.api.services.*
import org.gradle.api.specs.*
import org.gradle.api.tasks.*
import org.gradle.api.tasks.ant.*
import org.gradle.api.tasks.application.*
import org.gradle.api.tasks.bundling.*
import org.gradle.api.tasks.compile.*
import org.gradle.api.tasks.diagnostics.*
import org.gradle.api.tasks.diagnostics.configurations.*
import org.gradle.api.tasks.incremental.*
import org.gradle.api.tasks.javadoc.*
import org.gradle.api.tasks.options.*
import org.gradle.api.tasks.scala.*
import org.gradle.api.tasks.testing.*
import org.gradle.api.tasks.testing.junit.*
import org.gradle.api.tasks.testing.junitplatform.*
import org.gradle.api.tasks.testing.testng.*
import org.gradle.api.tasks.util.*
import org.gradle.api.tasks.wrapper.*
import org.gradle.api.toolchain.management.*
import org.gradle.authentication.*
import org.gradle.authentication.aws.*
import org.gradle.authentication.http.*
import org.gradle.build.event.*
import org.gradle.buildinit.*
import org.gradle.buildinit.plugins.*
import org.gradle.buildinit.tasks.*
import org.gradle.caching.*
import org.gradle.caching.configuration.*
import org.gradle.caching.http.*
import org.gradle.caching.local.*
import org.gradle.concurrent.*
import org.gradle.external.javadoc.*
import org.gradle.ide.visualstudio.*
import org.gradle.ide.visualstudio.plugins.*
import org.gradle.ide.visualstudio.tasks.*
import org.gradle.ide.xcode.*
import org.gradle.ide.xcode.plugins.*
import org.gradle.ide.xcode.tasks.*
import org.gradle.ivy.*
import org.gradle.jvm.*
import org.gradle.jvm.application.scripts.*
import org.gradle.jvm.application.tasks.*
import org.gradle.jvm.tasks.*
import org.gradle.jvm.toolchain.*
import org.gradle.language.*
import org.gradle.language.assembler.*
import org.gradle.language.assembler.plugins.*
import org.gradle.language.assembler.tasks.*
import org.gradle.language.base.*
import org.gradle.language.base.artifact.*
import org.gradle.language.base.compile.*
import org.gradle.language.base.plugins.*
import org.gradle.language.base.sources.*
import org.gradle.language.c.*
import org.gradle.language.c.plugins.*
import org.gradle.language.c.tasks.*
import org.gradle.language.cpp.*
import org.gradle.language.cpp.plugins.*
import org.gradle.language.cpp.tasks.*
import org.gradle.language.java.artifact.*
import org.gradle.language.jvm.tasks.*
import org.gradle.language.nativeplatform.*
import org.gradle.language.nativeplatform.tasks.*
import org.gradle.language.objectivec.*
import org.gradle.language.objectivec.plugins.*
import org.gradle.language.objectivec.tasks.*
import org.gradle.language.objectivecpp.*
import org.gradle.language.objectivecpp.plugins.*
import org.gradle.language.objectivecpp.tasks.*
import org.gradle.language.plugins.*
import org.gradle.language.rc.*
import org.gradle.language.rc.plugins.*
import org.gradle.language.rc.tasks.*
import org.gradle.language.scala.tasks.*
import org.gradle.language.swift.*
import org.gradle.language.swift.plugins.*
import org.gradle.language.swift.tasks.*
import org.gradle.maven.*
import org.gradle.model.*
import org.gradle.nativeplatform.*
import org.gradle.nativeplatform.platform.*
import org.gradle.nativeplatform.plugins.*
import org.gradle.nativeplatform.tasks.*
import org.gradle.nativeplatform.test.*
import org.gradle.nativeplatform.test.cpp.*
import org.gradle.nativeplatform.test.cpp.plugins.*
import org.gradle.nativeplatform.test.cunit.*
import org.gradle.nativeplatform.test.cunit.plugins.*
import org.gradle.nativeplatform.test.cunit.tasks.*
import org.gradle.nativeplatform.test.googletest.*
import org.gradle.nativeplatform.test.googletest.plugins.*
import org.gradle.nativeplatform.test.plugins.*
import org.gradle.nativeplatform.test.tasks.*
import org.gradle.nativeplatform.test.xctest.*
import org.gradle.nativeplatform.test.xctest.plugins.*
import org.gradle.nativeplatform.test.xctest.tasks.*
import org.gradle.nativeplatform.toolchain.*
import org.gradle.nativeplatform.toolchain.plugins.*
import org.gradle.normalization.*
import org.gradle.platform.*
import org.gradle.platform.base.*
import org.gradle.platform.base.binary.*
import org.gradle.platform.base.component.*
import org.gradle.platform.base.plugins.*
import org.gradle.plugin.devel.*
import org.gradle.plugin.devel.plugins.*
import org.gradle.plugin.devel.tasks.*
import org.gradle.plugin.management.*
import org.gradle.plugin.use.*
import org.gradle.plugins.ear.*
import org.gradle.plugins.ear.descriptor.*
import org.gradle.plugins.ide.*
import org.gradle.plugins.ide.api.*
import org.gradle.plugins.ide.eclipse.*
import org.gradle.plugins.ide.idea.*
import org.gradle.plugins.signing.*
import org.gradle.plugins.signing.signatory.*
import org.gradle.plugins.signing.signatory.pgp.*
import org.gradle.plugins.signing.type.*
import org.gradle.plugins.signing.type.pgp.*
import org.gradle.process.*
import org.gradle.swiftpm.*
import org.gradle.swiftpm.plugins.*
import org.gradle.swiftpm.tasks.*
import org.gradle.testing.base.*
import org.gradle.testing.base.plugins.*
import org.gradle.testing.jacoco.plugins.*
import org.gradle.testing.jacoco.tasks.*
import org.gradle.testing.jacoco.tasks.rules.*
import org.gradle.testkit.runner.*
import org.gradle.util.*
import org.gradle.vcs.*
import org.gradle.vcs.git.*
import org.gradle.work.*
import org.gradle.workers.*
下一步: 了解如何使用任务>>