Gradle Build Language Reference

Version 6.0.1

Introduction

本参考指南描述了构成Gradle构建语言或DSL的各种类型.

Some basics

您应该了解一些基本概念,这将帮助您编写Gradle脚本.

首先,Gradle脚本是配置脚本 . 在脚本执行时,它将配置特定类型的对象. 例如,在执行构建脚本时,它将配置类型为Project的对象. 该对象称为脚本的委托对象 . 下表显示了每种Gradle脚本的委托.

脚本类型 代表执行个体
构建脚本 Project
初始化脚本 Gradle
设置脚本 Settings

委托对象的属性和方法可供您在脚本中使用.

其次,每个Gradle脚本都实现Script接口. 该接口定义了可以在脚本中使用的许多属性和方法.

Build script structure

构建脚本由零个或多个语句和脚本块组成. 语句可以包括方法调用,属性分配和局部变量定义. 脚本块是将闭包作为参数的方法调用. 该闭包被视为配置闭包 ,它在执行时配置一些委托对象. 顶级脚本块在下面列出.

BlockDescription
allprojects { }

配置该项​​目及其每个子项目.

artifacts { }

为该项目配置已发布的工件.

buildscript { }

为该项目配置构建脚本类路径.

configurations { }

为该项目配置依赖项配置.

dependencies { }

配置此项目的依赖项.

repositories { }

配置该项​​目的存储库.

sourceSets { }

配置该项​​目的源集.

subprojects { }

配置该项​​目的子项目.

publishing { }

配置由发布插件添加的PublishingExtension .

构建脚本也是Groovy脚本,因此可以包含Groovy脚本中允许的那些元素,例如方法定义和类定义.

Core types

下面列出了Gradle脚本中使用的一些主要类型:

TypeDescription
Project

这个接口是您用来从构建文件与Gradle交互的主要API. 您可以从Project以编程方式访问Gradle的所有功能.

Task

Task代表构建的一项基本工作,例如编译类或生成javadoc.

Gradle

表示对Gradle的调用.

Settings

声明实例化和配置要参与构建的Project实例的层次结构所需的配置.

IncludedBuild

组合中包含的内部版本.

Script

所有Gradle脚本都实现了此接口,以添加一些特定于Gradle的方法. 由于编译的脚本类将实现此接口,因此可以直接在脚本中使用此接口声明的方法和属性.

SourceSet

SourceSet表示Java源文件和资源文件的逻辑组. 它们在用户手册中有更详细的介绍.

SourceSetOutput

所有输出目录(编译类,已处理资源等)的SourceSetOutput -注意SourceSetOutput扩展了FileCollection .

SourceDirectorySet

SourceDirectorySet表示由一组源目录组成的一组源文件,以及相关的包含和排除模式.

IncrementalTaskInputs

提供对需要由增量任务处理的任何输入文件的访问.

Configuration

Configuration代表一组工件及其相关性. 在ConfigurationContainer文档中找到有关声明对配置的依赖性或有关管理配置的更多信息.

ResolutionStrategy

定义有关依赖性解决方案的策略. 例如,强制某些依赖项版本,替换,冲突解决方案或快照超时.

ArtifactResolutionQuery

构建器,用于构建可以解析指定组件的所选软件工件的查询.

ComponentSelection

表示模块的组件选择器的元组和要在组件选择规则中评估的候选版本.

ComponentSelectionRules

表示用于组件选择规则的容器. 可以将规则作为解决方案的一部分来应用配置策略,并且可以通过规则明确接受或拒绝各个组件. 既不接受也不拒绝的组件将受默认版本匹配策略的约束.

ExtensionAware

可以在运行时与其他对象一起扩展的对象.

ExtraPropertiesExtension

Gradle域对象的其他特殊属性.

PluginDependenciesSpec

DSL,用于声明要在脚本中使用的插件.

PluginDependencySpec

对插件依赖性的可变规范.

PluginManagementSpec

配置如何解决插件.

ResourceHandler

提供对特定于资源的实用程序方法的访问,例如创建各种资源的工厂方法.

TextResourceFactory

创建由诸​​如字符串,文件和归档条目之类的源支持的TextResource .

InputChanges

提供对需要由增量工作操作处理的任何输入文件的访问.

Publishing types

下面列出了用于配置发布的类型:

TypeDescription
PublishingExtension

如何"发布"项目的不同组件的配置.

IvyPublication

IvyPublication是Gradle如何将Ivy格式的内容发布到Ivy存储库的表示/配置. 您可以直接添加了一个名为常春藤出版项目的publishing.publications通过提供容器IvyPublication作为类型.

IvyArtifact

作为IvyPublication一部分发布的工件.

IvyArtifactSet

IvyArtifact中包含的IvyPublication . 作为DomainObjectSetIvyArtifactSet提供了方便的方法来查询,过滤和将操作应用于IvyArtifact集.

IvyModuleDescriptorSpec

任何Ivy出版物的描述符.

IvyModuleDescriptorAuthor

常春藤出版物的作者.

IvyModuleDescriptorLicense

常春藤出版物的许可证.

IvyModuleDescriptorDescription

常春藤出版物的描述.

MavenPublication

一个MavenPublication是摇篮应该如何发布Maven中的格式的东西代表/配置. 您可以直接添加了一个名为Maven的出版项目的publishing.publications通过提供容器MavenPublication作为类型.

MavenArtifact

作为MavenPublication一部分发布的工件.

MavenArtifactSet

MavenArtifact的集合将包含在MavenPublication . 作为DomainObjectSetMavenArtifactSet提供了方便的方法来查询,过滤和将操作应用于MavenArtifact集.

MavenPom

Maven出版物的POM.

MavenPomCiManagement

Maven出版物的CI管理系统.

MavenPomContributor

Maven出版物的撰稿人.

MavenPomContributorSpec

允许添加Maven发布的贡献者.

MavenPomDeveloper

Maven出版物的开发人员.

MavenPomDeveloperSpec

允许将开发人员添加到Maven发布中.

MavenPomDistributionManagement

Maven发布的分发管理配置.

MavenPomIssueManagement

Maven出版物的问题管理系统.

MavenPomLicense

Maven出版物的许可证.

MavenPomLicenseSpec

允许向Maven发布添加许可证.

MavenPomMailingList

Maven出版物的邮件列表.

MavenPomMailingListSpec

允许将邮件列表添加到Maven发布.

MavenPomOrganization

Maven出版物的组织.

MavenPomRelocation

已移至新组和/或工件ID的Maven发布的重定位信息.

MavenPomScm

Maven发布的SCM(源代码管理).

Container types

处理各种声明性元素(例如,依赖关系,配置,工件,任务等)的容器类型:

TypeDescription
TaskContainer

TaskContainer负责管理一组Task实例.

ConfigurationContainer

ConfigurationContainer负责声明和管理配置. 另请参阅Configuration .

RepositoryHandler

RepositoryHandler管理一组存储库,从而允许定义和查询存储库.

DependencyHandler

DependencyHandler用于声明依赖关系. 依赖项被分组为配置(请参阅Configuration ).

ArtifactHandler

此类用于定义要发布的工件并将其添加到配置中. 创建发布工件并不意味着创建存档. 创建的是一个域对象,该域对象表示要发布的文件以及应如何发布的信息(例如名称).

Build Cache types

用于连接和配置构建缓存的类型:

TypeDescription
BuildCacheConfiguration

整个Gradle构建的构建缓存的配置.

DirectoryBuildCache

本地目录构建缓存的配置对象.

HttpBuildCache

HTTP构建缓存的配置对象. 生成缓存当前仅支持BASIC身份验证.

Input Normalization types

用于配置输入归一化的类型

TypeDescription
InputNormalizationHandler

用于配置输入归一化. 当前,仅可以配置运行时类路径规范化.

InputNormalization

输入规范化配置. 当Gradle尝试确定两个任务输入是否不同时,将使用输入标准化. Gradle对两个输入进行归一化,并且当且仅当归一化不同时,才认为输入是不同的.

RuntimeClasspathNormalization

运行时类路径规范化的配置.

Help Task types

以下是可用于每个Gradle项目的任务类型. 这些任务类型也可以直接在构建脚本中声明和配置.

TypeDescription
TaskReportTask

显示项目中的任务列表. 从命令行执行tasks任务时,将使用这种类型的实例.

ProjectReportTask

显示构建中的项目列表. 从命令行执行projects任务时,将使用这种类型的实例.

DependencyReportTask

显示项目的依赖关系树. 从命令行执行dependencies任务时,将使用这种类型的实例.

DependencyInsightReportTask

生成尝试回答以下问题的报告:

PropertyReportTask

显示项目的属性. 从命令行执行properties任务时,将使用这种类型的实例.

ComponentReport

显示有关项目产生的软件组件的一些详细信息.

DependentComponentsReport

显示相关组件.

ModelReport

显示有关项目的配置模型的一些详细信息. 从命令行执行model任务时,将使用这种类型的实例.

Task types

下面列出了可在构建脚本中使用的各种任务类型:

TypeDescription
AntlrTask

从Antlr语法生成解析器.

BuildEnvironmentReportTask

提供有关与任务关联的项目的构建环境的信息.

Checkstyle

针对某些源文件运行Checkstyle.

CodeNarc

针对某些源文件运行CodeNarc.

Copy

Copies files into a destination directory. This task can also rename and filter files as it copies. The task implements CopySpec for specifying what to copy.

CreateStartScripts

创建用于启动JVM应用程序的启动脚本.

Delete

删除文件或目录. 例:

Ear

组装EAR档案.

Exec

执行命令行过程. 例:

GenerateIvyDescriptor

生成一个常春藤XML模块描述符文件.

GenerateMavenPom

生成一个Maven模块描述符(POM)文件.

GenerateBuildDashboard

生成构建仪表板报告.

GradleBuild

执行Gradle构建.

GroovyCompile

编译Groovy源文件以及Java源文件(可选).

Groovydoc

为Groovy源以及Java源(可选)生成HTML API文档.

HtmlDependencyReportTask

生成HTML依赖关系报告. 此报告结合了ASCII依赖关系报告和ASCII依赖关系洞察报告的功能. 对于给定的项目,它会生成每个配置的依赖关系树,并且可以单击每个依赖关系以显示对该依赖关系的了解.

JacocoReport

生成Jacoco覆盖率数据的HTML,Xml和CSV报告的任务.

JacocoMerge

将多个执行数据文件合并为一个的任务.

JacocoCoverageVerification

验证代码覆盖率指标的任务. 如果根据指定规则检测到违规,则使任务失败.

Jar

组装一个JAR档案.

JavaCompile

编译Java源文件.

Javadoc

生成Java类的HTML API文档.

JavaExec

在子进程中执行Java应用程序.

Pmd

在Java源代码文件上运行一组静态代码分析规则,并生成发现问题的报告.

PublishToIvyRepository

将IvyPublication发布到IvyArtifactRepository.

PublishToMavenRepository

MavenPublication发布到MavenArtifactRepository .

ScalaCompile

编译Scala源文件以及Java源文件(可选).

ScalaDoc

生成Scala源文件的HTML API文档. 注意:这不再适用于Scala 2.13和更高版本.

InitBuild

生成Gradle项目结构.

Sign

为一个或多个创建数字签名文件的任务; 任务,文件,可发布工件或配置.

Sync

将目标目录的内容与某些源目录和文件同步.

Tar

TAR存档文件.

AbstractTestTask

所有测试任务的抽象类.

Test

执行JUnit(3.8.x,4.x或5.x)或TestNG测试. 测试始终在(一个或多个)单独的JVM中运行.

TestReport

根据一项或多项Test任务的结果生成HTML测试报告.

Upload

Configuration的工件上载到一组存储库.

War

组装WAR档案.

Wrapper

生成脚本(用于* nix和Windows),使您无需安装Gradle即可使用Gradle构建项目.

WriteProperties

以可以预期结果可重复的方式编写Properties .

Zip

组装一个ZIP档案. 默认是压缩zip的内容.

Reporting types

下面列出了生成报告时使用的一些类型:

TypeDescription
CustomizableHtmlReport

可以使用XSLT样式表定制其生成的HTML报告.

SingleFileReport

A report that is a single file.

DirectoryReport

要创建的基于目录的报告.

Report

要创建的基于文件的报告.

Reporting

提供报告选项的对象.

ReportContainer

Report对象的容器,代表潜在的报告.

ReportingExtension

一个名为" reporting"的项目扩展,提供基本的报告设置和实用程序.

Eclipse/IDEA model types

用于配置Eclipse或IDEA插件

TypeDescription
EclipseModel

Eclipse项目信息的DSL友好模型. 定制Eclipse项目生成的第一入口.

EclipseProject

启用微调Eclipse插件的项目详细信息(.project文件)

EclipseClasspath

生成的Eclipse项目的构建路径设置. 由GenerateEclipseClasspath任务用来生成Eclipse .classpath文件.

EclipseJdt

启用微调Eclipse插件的jdt详细信息

EclipseWtp

启用微调Eclipse插件的wtp / wst详细信息

EclipseWtpComponent

启用微调Eclipse插件的wtp组件详细信息

EclipseWtpFacet

启用微调Eclipse插件的wtp facet详细信息

IdeaModel

IDEA项目信息的DSL友好模型. 定制IDEA代的第一个切入点.

IdeaProject

启用微调IDEA插件的项目详细信息(* .ipr文件).

IdeaModule

启用IDEA插件的模块详细信息(* .iml文件).

IdeaWorkspace

启用IDEA插件的工作区详细信息(* .iws文件).

XmlFileContentMerger

为生成/解析/合并功能建模. 添加与XML相关的挂钩.

FileContentMerger

为生成/解析/合并功能建模.

Eclipse/IDEA task types

由IDE插件贡献的任务. 要配置IDE插件,请使用IDE模型类型.

TypeDescription
GenerateEclipseProject

生成Eclipse .project文件. 如果您想微调月食配置

GenerateEclipseClasspath

生成Eclipse .classpath文件. 如果您想微调月食配置

GenerateEclipseJdt

生成Eclipse JDT配置文件. 如果您想微调月食配置

GenerateEclipseWtpComponent

为Eclipse WTP生成org.eclipse.wst.common.component设置文件. 如果您想微调月食配置

GenerateEclipseWtpFacet

生成Eclipse WTP的org.eclipse.wst.common.project.facet.core设置文件. 如果您想微调月食配置

GenerateIdeaModule

生成一个IDEA模块文件. 如果您想微调构思配置

GenerateIdeaProject

为根项目* only *生成一个IDEA项目文件. 如果您想微调构思配置

GenerateIdeaWorkspace

*仅*为根项目生成一个IDEA工作区文件. 目前,您几乎不需要配置有关工作区生成的信息.

Xcode task types

Xcode IDE插件贡献的任务. 要配置IDE插件,请使用IDE模型类型.

TypeDescription
GenerateSchemeFileTask

生成Xcode方案文件的任务(例如Foo.xcodeproj/xcshareddata/xcschemes/Foo.xcscheme ). Xcode方案定义了要构建的目标的集合,构建时要使用的配置以及要执行的测试的集合.

GenerateWorkspaceSettingsFileTask

生成Xcode工作区设置文件的任务(例如Foo.xcodeproj/project.xcworkspace/xcshareddata/WorkspaceSettings.xcsettings ).

GenerateXcodeProjectFileTask

生成Xcode项目文件的任务(例如Foo.xcodeproj/project.pbxproj ). 项目包含用于构建产品的所有元素,并维护这些元素之间的关系. 它包含一个或多个目标,用于指定如何构建产品. 项目为项目中的所有目标定义默认的构建设置(每个目标也可以指定自己的构建设置,这些设置将覆盖项目的构建设置).

GenerateXcodeWorkspaceFileTask

生成Xcode工作区文件的任务(例如Foo.xcworkspace/contents.xcworkspacedata ). 工作区可以包含任意数量的Xcode项目.

Visual Studio task types

由Visual Studio IDE插件贡献的任务. 要配置IDE插件,请使用IDE模型类型.

TypeDescription
GenerateSolutionFileTask

生成Visual Studio解决方案文件(例如foo.sln )的任务.

GenerateProjectFileTask

生成Visual Studio项目文件的任务(例如foo.vcxproj ).

GenerateFiltersFileTask

生成Visual Studio过滤器文件的任务(例如foo.vcxproj.filters ).

Artifact transform types

用于定义伪影转换.

TypeDescription
TransformAction

工件转换动作的接口.

TransformOutputs

工件转换的输出.

TransformSpec

工件转换注册的基本配置.

Native tool chains model types

用于配置工具链以构建C ++和Swift组件.

TypeDescription
Gcc

GNU GCC工具链.

Clang

Clang工具链.

VisualCpp

Visual C ++工具链.

Swiftc

Swift编译器工具链.

C++ component model types

用于配置C ++组件.

TypeDescription
CppApplication

C ++应用程序的配置,定义组成应用程序的源文件以及其他设置.

CppLibrary

C ++库的配置,定义构成库的源文件和头目录以及其他设置.

CppTestSuite

一个C ++测试套件.

Swift component model types

用于配置Swift组件.

TypeDescription
SwiftApplication

Swift应用程序的配置,定义构成应用程序的源文件以及其他设置.

SwiftLibrary

Swift库的配置,定义构成库的源文件以及其他设置.

SwiftXCTestSuite

XCTest套件,在Swift中实现.

Native binary task types

用于构建本机二进制文件的任务.

TypeDescription
CppCompile

将C ++源文件编译为目标文件.

SwiftCompile

将Swift源文件编译为目标文件.

LinkExecutable

Links a binary executable from object files and libraries.

LinkSharedLibrary

从目标文件和导入的库链接二进制共享库.

CreateStaticLibrary

从目标文件组装静态库.

LinkMachOBundle

从目标文件和导入的库链接二进制包.

InstallExecutable

使用其依赖库安装可执行文件,以便可以轻松执行它.

InstallXCTestBundle

使用运行脚本创建XCTest包,以便可以轻松执行它.

RunTestExecutable

运行已编译并已安装的测试可执行文件.

XCTest

执行XCTest测试. 测试始终在单个执行中运行.