「Gradle」| 手把手自定义 Gradle 插件

点赞关注,不再迷路,你的支持对我意义重大!

Hi,我是丑丑。本文 「Android 路线」| 导读 —— 从零到无穷大 已收录,这里有 Android 进阶成长路线笔记 & 博客,欢迎跟着彭丑丑一起成长。(联系方式在 GitHub)


前言

  • 在前面的内容里,你已经了解了如何通过定制 Project & Task 来添加构建逻辑,对于可复用的 Task,可以生成 Gradle 插件在其他项目中使用;
  • 在这篇文章里,我将讨论 自定义 Gradle 插件的步骤。如果能帮上忙,请务必点赞加关注,这真的对我非常重要。

目录


1. 前置知识

这篇文章的内容会涉及以下前置 / 相关知识,贴心的我都帮你准备好了,请享用~

  • Gradle 筑基: 「Gradle」| 筑基篇(概念 & Groovy & 配置 & 命令)

  • Gradle 进阶: 「Gradle」| 进阶篇(Project & Task & 构建生命周期)

  • 官方文档: Developing Custom Gradle Plugins


2. Gradle 插件概述

2.1 什么是 Gradle?什么是 Gradle 插件?

Gradle 插件的本质就是抽取高度模块化的逻辑,以便更高效地进行复用。 Gradle 和 Gradle 插件是两个概念,在前面的文章里,你已经了解过 Gradle 的核心工作原理。简单来说,Gradle 只是提供了一个构建流程。而其他可复用的 Task(例如编译 Java 工程、编译 Android 工程等),是通过应用 Gradle 插件来获取的。

  • Gradle: 构建工具,提供核心构建流程
  • Gradle 插件: 本质上是可复用的 task,依赖于 Gradle 环境

2.2 插件类型

Gradle 插件分为两大类:脚本插件 & 对象插件

  • 脚本插件: 一个脚本插件和一个普通的 build.gradle 文件没什么区别,虽然简单,但它是模块化的基础。脚本可以存在本地,也可以存在网络上,只需要提供脚本的相对路径或者 URL,例如:
apply other.gradle
  • 对象插件: 编写一个对象插件的最低要求是提供一个 org.gradle.api.Plugin 接口的实现类,这个接口只要一个Plugin#apply(Project)方法。

Plugin.Java

package org.gradle.api;

public interface Plugin {
    void apply(T var1);
}

2.3 应用插件

在 build.gradle 文件中,可以使用 apply 方法来应用插件,有两种语法:

  • 语法 1:
apply plugin 'groovy'
  • 语法 2:
plugins {
    id 'groovy'
    id 'maven'
}

这里的 id 是插件的简短名称,是在插件中resources/META-INF/gradle-plugins/[id].properties文件的文件名决定的。

注意: 在一个 build.gradle 中不要同时使用这两种语法。


3. 自定义插件

这一节,我们开始讨论自定义插件的细节。前面提到 Gradle 插件分为脚本插件 & 对象插件,因为脚本插件比较简单,同时使用较少,所以我们以讨论对象插件为主。

踩坑: 笔者在学习 Gradle 插件时踩了一个深坑,即:setting.gradle 中如果存在rootProjet.name='项目名',那么在应用插件并 sync 后会报错:

An exception occurred applying plugin request [id 'hello']
> Failed to apply plugin [id 'hello']
 > No such property: project for class HelloPlugin

删除rootProjet.name='项目名'就不会报这个问题,原因未查。

3.1 步骤一:创建插件项目

首先,我们需要创建一个单独存放插件代码的 Module。Module 的命名可以是任意的,不过倒是有一个特殊的 Module 名 —— 「buildSrc」。要点如下:

  • 1、这个目录可以被自动识别为 Module,不需要在 setting.gradle 中进行包含;
  • 2、在构建时自动编译打包并添加到 buildScript 中的 classpath 下,不需要手动发布插件;
  • 3、buildSrc 编译时间先于工程编译。

3.2 步骤二:初始化插件项目

我们对新建的插件项目进行以下操作:

  • 1、(可选,如果你的项目中用不到 Java 代码)移除 Java 文件夹;
  • 2、(必选)添加 groovy 文件夹,用于存放插件代码;
  • 3、(必选)添加 resources 文件夹,用于配置插件描述符;
  • 4、(必选)修改 build.gradle 内容。

下面介绍下第 3、4 步:

3.2.1 配置插件描述符

你需要新建一个*.properties文件,存放路径为:

main
├── groovy
├── resources 
    ├── META-INF
        ├── gradle-plugins
            ├── *.properties

提示: 你可以通过 sourceSets {} 闭包方法来设置 resources 文件夹的位置。

这里只需要记住两个要点:

  • 1、*.properties 文件名是插件的剪短名称(id),用于应用插件。例如:
com.xurui.plugin.properties 
  • 2、*.properties 文件内容配置了插件实现类的映射,需要使用implementation-class来指定插件实习类的全限定类名。例如:
implementation-class=com.xurui.plugin.HelloPlugin 

3.2.2 修改 build.gradle 内容

插件 build.gradle

plugins {
    id 'groovy' // (必选)用于实现插件
    id 'maven' // 用于发布插件
}

dependencies {
    implementation gradleApi()
    implementation localGroovy()
}

// 设置源文件路径
sourceSets {
    main {
        groovy {
            srcDir 'src/main/groovy'
        }

        resources {
            srcDir 'src/main/resources'
        }
    }
}

应用 Groovy 插件,并将 Gradle API 添加为编译时依赖项。在 External Libraries 中生成三个 jar 文件:

3.3 步骤三:实现插件

在 groovy 文件夹下实现插件的主题逻辑,例如:

com.xurui.plugin.HelloPlugin.groovy

class HelloPlugin implements Plugin {
    @Override
    void apply(Project target) {
        println "自定义插件"
    }
}

提示: 文件后缀使用.groovy

3.4 步骤四:应用插件

在 build.gradle 文件中,可以使用 apply 方法来应用插件,有两种语法。例如:

  • 语法 1:
apply plugin 'com.xurui.plugin'
apply plugin 'com.android.application'
  • 语法 2:
plugins {
    id 'com.xurui.plugin'
    id 'com.android.application'
}

应用插件后,从构建过程输出(Build Output)就可以看到我们的插件生效了:

Executing tasks: [:app:generateDebugSources] in project  E:\workspace\...

【初始化阶段结束】,总共耗时:9ms

> Configure project :app
自定义插件
【配置阶段结束】,总耗时:1864ms

> Task :app:preBuild UP-TO-DATE
> Task :app:preDebugBuild UP-TO-DATE
> Task :app:checkDebugManifest UP-TO-DATE
> Task :app:compileDebugAidl NO-SOURCE
...
> Task :app:assembleDebug
【执行阶段结束】,总耗时:141ms

BUILD SUCCESSFUL in 2s
4 actionable tasks: 4 up-to-date

4. 发布 & 依赖插件

发布插件有两种选择,这两种选择其实无非是发布的地址不同:

  • 发布到本地仓库;
  • 发布到远程仓库。

4.1 插件的属性

发布的插件需要配置三个属性,这三个属性共同形成了插件的唯一表示:

插件属性 描述
groupId 组织 / 公司名称
artifactId 项目 / 模块名称
version 项目 / 模块的当前版本号

4.2 配置插件属性

我们使用 mavenDeployer 插件 来发布仓库,你需要在插件 build.gradle 中增加以下配置:

插件 build.gradle

plugins {
    id 'groovy' // (必选)用于实现插件
    id 'maven' // (mavenDeployer 插件)用于发布插件
}

...

uploadArchives {
    repositories {
        mavenDeployer {
            repository(url: uri('../repo')) // 插件的输出路径
            pom.groupId = 'xurui_groupId'
            pom.artifactId = 'xurui_artifactId'
            pom.version = '1.0.0'
        }
    }
}

如果需要发布到远程仓库,只需要修改 repository url 地址,例如:

repository(url: RELEASE_URL) {
    authentication(userName: "xurui", password: "xxx")
}

4.3 发布插件

随后,执行gradlew uploadArchives命令(注意相对路径)来执行这个 uploadArchives task,实现插件发布。也可以使用 Gradle window 快速执行:

发布完成后在指定路径下就会生成插件文件:

4.4 依赖插件

提示: 如果在 buildSrc 目录下实现插件,就不要手动添加依赖了。Gradle 会自动将 buildSrc 构建产物加入到 classpath。

在需要依赖插件的项目里,我们需要添加插件到 classpath 中。例如:

项目根 build.gradle

buildscript {
    repositories {
        google()
        jcenter()
        maven { url uri('./repo') }
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:3.5.3'
        classpath 'xurui_groupId:xurui_artifactId:1.0.0'
    }
}

allprojects {
    repositories {
        google()
        jcenter()

    }
}

task clean(type: Delete) {
    delete rootProject.buildDir
}

其中 xurui_groupId 是 group,xurui_artifactId 是 artifactId,1.0.0 是版本号,也可以用这种语法:

dependencies {
     classpath group: 'xurui_groupId ', name: 'xurui_artifactId ', version: '1.0.0'
 }

4.5 应用插件

完成这一步,就可以顺利应用插件了:

项目 build.gradle

plugins {
    id 'com.xurui.plugin'
    id  'com.android.application'
}

5. 自定义 Extension 与 Task

Editting...


6. 总结

  • Gradle 是构建工具,提供核心构建流程,而 Gradle 插件 本质上是可复用的 task,依赖于 Gradle 环境;
  • 插件类型分为脚本插件 & 对象插件,对象插件使用比较多;
  • 这篇文章主要是手把手带你完成自定义插件的步骤,希望能帮助你避坑。在后面的文章里,我将和你一起使用自定义 Gradle 插件完成实战功能。请关注~

参考资料

  • 《Gradle核心思想(六)自定义Gradle插件的三种方式》 —— 刘望舒 著
  • 《深度探索 Gradle 自动化构建技术(四、自定义 Gradle 插件)》 —— JsonChao 著
  • 《实战 Gradle》(第 8 章)—— [美] Benjamin Muschko 著

创作不易,你的「三连」是丑丑最大的动力,我们下次见!

你可能感兴趣的:(「Gradle」| 手把手自定义 Gradle 插件)