[Unity安卓开发]Unity3D Gradle基础

Unity 将 Gradle 用于所有 Android 构建。可以在 Unity 中构建输出包（.apk、.aab），也可以从 Unity 导出 Gradle 项目，然后通过外部工具（如 Android Studio）进行构建。

什么是Gradle?

• 一款优秀的自动化构建系统工具。
• DSL(特定领域语言)基于Groovy。语法和Java相接近。

Unity的Gradle层次结构

为了清楚的理解Unity中的Android  Gradle结构，我们首先可以导出Unity生成的Unity Gradle层次结构。

• 最简单的方式就是我们Build 下我们的Apk，然后在Temp/gradleOut获取我们的 Gradle层次结构。
• 或者Build出Android Gradle项目。

 

launcher:

• 启动器部分，其中包含应用程序的名称及其图标。
• 默认是可启动 Unity 的简单 Android 应用程序。可以将此模块替换为自己的应用程序。

src：

• 启动器模块的代码和资源。

 build.gradle

• 描述如何构建启动器模块，并包含要在构建中包含的依赖项列表。
• 依赖于unityLibrary模块，当构建启动器模块时，unityLibrary必须包含在最终结果中。
• 对应自定义Gradle的Custom Launcher Gradle Template文件。

unityLibrary：

• 我们的Unity模块，包含 Unity 运行时和播放器数据。
• 可以集成到其他任何 Gradle 项目中，注意集成时如下注意：详情

1. 仅支持全屏渲染，不支持在部分屏幕中渲染。
2. 不能加载或集成多个 Unity 运行时实例。
3. IUnityPlayerLifecycleEvents 提供一种与 Unity Player 生命周期事件进行交互方式。
4. 通过 settings.gradle 文件将生成的 Android Gradle 项目的 unityLibrary 模块包含在您的 Android Unity 项目中。

libs：

• 用于存放unityLibrary模块的Android Archive (.aar)和Java Archive (.jar)插件。
• 导出的Unity项目，它包含了unity-classes.jar文件。
• 这个目录不包含 Android Library Projects 自定义模块。Unity将这些作为独立的子模块复制到Gradle项目中。
• unity-classes.jar包含了Unity引擎使用的java代码。

src：

• 包含unityLibrary模块的源代码和资源。Unity将源代码和资源放在次目录中。

build.gradle：

• 描述了如何构建unityLibrary模块，并包含了构建中要包含的依赖项列表。
• unityLibrary模块依赖于Unity项目中的所有插件。
•  对应自定义Gradle的Custom Main Gradle Template文件。

proguard-unity.txt

• Unity压缩，混肴的ProGuard配置配置文件。
• Minification 启动时，将配置unity-classes.jar文件将如何进行压缩混淆。

proguard-user.txt

• 包含项目的java代码和第三方java插件的ProGuard配置。
• Minification 启动时，将配置项目的java代码和第三方java插件将如何进行压缩混淆。
• 对应自定义Gradle的Custom Proguard File文件。

build.gradle

• 整体项目的构建逻辑，负责引入所需的全部子项目Gradle并触发每个构建命令。
• 文件位于项目的根目录下，用于定义适用于项目中所有模块的依赖项。
• 会影响所有模块的配置。
• 可包含用于清理 build 目录的代码。
• 用于指定Android Gradle Plugin版本。
• 对应自定义Gradle的Custom Base Gradle Template文件。

gradle.properties

• 配置了Gradle和JVM的属性
• 配置守护进程并管理构建过程中启动JVM的方式。
• 当使用网络代理，辅助Gradle通信。
• Unity默认添加了数据流文件资源目录中的资源类型unityStreamingAssets=.unity3d，告诉Gradle不应该压缩它们。多个文件用","进行分割。
• 对应自定义Gradle的Custom Gradle Properties Template文件。
• 此文件更多信息详情

 local.properties

• 用于配置本地环境属性，如Android SDK或者AndoridNDK。

 settings.gradle

• 用于多项目构建或者具有子项目的项目中的定义文件。
• Unity中通常包含launcher和unityLibrary。
• 如果使用Play Asset Delivery，由于所有的资源包都是单独的模块，所以将会列出每个资源模块。
• 如果要自定这个文件，需要复制你Unity安装目录的PlaybackEngines/AndroidPlayer/Tools/GradleTemplates/settingsTemplate.gradle文件到你项目的Assets/Plugins/Android文件夹中。

自定义Gradle模板

自定义Gradle模板变量：

变量：	描述：
DEPS	项目依赖项（即，项目使用的库）的列表。
APIVERSION	构建针对的 API 版本（例如 25）。
MINSDKVERSION	最低 API 版本（例如，25）。
BUILDTOOLS	使用的 SDK 构建工具（例如 25.0.1）。
TARGETSDKVERSION	目标 API 版本（例如，25）。
APPLICATIONID	Android 应用程序 ID（例如，com.mycompany.myapp）。
MINIFY_DEBUG	允许为调试版本缩小（true 或 false）。
PROGUARD_DEBUG	在调试版本中，使用 proguard 进行缩小（true 或 false）。
MINIFY_RELEASE	允许为发布版本缩小（true 或 false）。
PROGUARD_RELEASE	在发布版本中，使用 proguard 进行缩小（true 或 false）。
USER_PROGUARD	自定义用户 proguard 文件（例如 proguard-user.txt）。
SIGN	完成 signingConfigs 部分（如果该构建已签名）。
SIGNCONFIG	设置为 signingConfig signingConfig.release（如果该构建已签名）。
DIR_GRADLEPROJECT	Unity 创建 Gradle 项目的目录。
DIR_UNITYPROJECT	Unity 项目的目录。
ARTIFACTORYREPOSITORY	artifactory仓库配置
BUILD_SCRIPT_DEPS	构建脚本的项目依赖项（即，构建脚本使用的库）的列表
JVM_HEAP_SIZE	分配给JVM守护进程的内存大小
MINIFY_WITH_R_EIGHT	是否启用R8代码混淆（true 或 false）。
STREAMING_ASSETS	数据流文件资源列表
ABIFILTERS	ABI过滤器，保留列表
ADDITIONAL_PROPERTIES	额外配置属性
VERSIONCODE	版本号，是数值类型
VERSIONNAME	版本名，是字符串类型，如1.2.1
PACKAGING_OPTIONS	packagingOptions配置项
SPLITS	splits配置项 文档
BUILT_APK_LOCATION	构建apk的位置
SPLITS_VERSION_CODE	生成的splits的构建版本代码
LAUNCHER_SOURCE_BUILD_SETUP	启动模块的源代码构建设置项
APPLY_PLUGINS	应用的插件列表项
REPOSITORIES	repositories 配置项
IL_CPP_BUILD_SETUP	IL2CPP构建设置项
SOURCE_BUILD_SETUP	源代码构建设置项
EXTERNAL_SOURCES	外部源代码列表项

Custom Main Gradle Template 

此文件包含有关如何将Unity的 Android 应用程序构建为库的配置信息。

对应Gradle结构的"unityLibrary/build.gradle"文件。

• Unity会把我们的Unity内容导出为 unityLibrary库然后通过launcher依赖构建。
• 这里Build出来的并不是一个App而是一个Library模块。

输出后的文件说明：

• 依赖项配置文档dependencies配置项 ： 依赖项配置文档
• Lint选项配置：Lint选项配置文档
• aaptOptions配置：Android Asset Packaging Tool配置文档
• Packaging选项:Packaging选项文档

//表述这个工程的工程类型，一般包含3种：
//App类型工程：apply plugin: 'com.android.application'
//库类型工程:apply plugin: 'com.android.library'
//Test工程类型:apply plugin: 'com.android.test'
apply plugin: 'com.android.library'

//指构建工程所依赖的所有依赖项
dependencies {
    //一般来说有3种依赖类型
    //对于本地模块的依赖:implementation project(':mylibrary') [mylibrary此名称必须与在您的 settings.gradle 文件中使用 include: 定义的库名称相符）]
    //本地文件依赖项:implementation fileTree(dir: 'libs', include: ['*.jar'])[对项目的libs目录中 JAR 文件的依赖关系,Gradle会读取build.gradle文件的相对路径]
    //也可以按如下方式指定各个文件：implementation files('libs/foo.jar', 'libs/bar.jar')
    //远程文件依赖项:implementation 'com.example.android:app-magic:12.3'[实际是implementation group: 'com.example.android', name: 'app-magic', version: '12.3'的简写]
    implementation fileTree(dir: 'libs', include: ['*.jar'])
}
//针对Android选项的配置块
android {
    //编译依赖的SDK版本
    compileSdkVersion 29
    //构建工具版本
    buildToolsVersion '30.0.2'

    //编译选项
    compileOptions {
        //这里配置的是Java 语言的的源码版本
        sourceCompatibility JavaVersion.VERSION_1_8
        //这里配置的是Java生成的字节码版本
        targetCompatibility JavaVersion.VERSION_1_8
    }
    //默认的配置
    defaultConfig {
        //最小兼容的Android平台版本，如果低于此版本将会阻止用户安装。
        minSdkVersion 19
        //指定我们基于哪个版本开发。
        targetSdkVersion 29

        ndk {
            //ABI 是 Application Binary Interface 的缩写。帮助适配不同的CPU架构。
            //把除了v7a以外的兼容包都过滤掉
            abiFilters 'armeabi-v7a'
        }
        //版本码，是一个递增的整数
        versionCode 1
        //版本名
        versionName '1.0.2'
        //Proguard的配置文件，这里面有两个文件一个是unity自身的配置还有一个是我们自己配置的Proguard配置文件
        consumerProguardFiles 'proguard-unity.txt', 'proguard-user.txt'
    }
    //Lint选项配置
    lintOptions {
        //当发生错误不终止构建
        //更多lint配置：https://developer.android.google.cn/reference/tools/gradle-api/4.1/com/android/build/api/dsl/LintOptions?hl=cn
        abortOnError false
    }
    //aapt全称为Android Asset Packaging Tool，为Android资源打包工具。
    //https://developer.android.google.cn/reference/tools/gradle-api/4.1/com/android/build/api/dsl/AaptOptions?hl=en
    aaptOptions {
        //这里表示这些文件类型不会被压缩存储在APK中。
        //unityStreamingAssets.tokenize 这里获取的是gradle.properties文件中unityStreamingAssets的配置。
        noCompress = ['.ress', '.resource', '.obb'] + unityStreamingAssets.tokenize(', ')
        //需要忽略的资源类型
        ignoreAssetsPattern = "!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~"
    }
    //Packaging选项
    //https://developer.android.google.cn/reference/tools/gradle-api/7.4/com/android/build/api/dsl/PackagingOptions?hl=en
    packagingOptions {
        //设置armeabi-v7a相关文件不会被剥离优化压缩
        doNotStrip '*/armeabi-v7a/*.so'
    }
}

Custom Launcher Gradle Template

此文件包含有关如何构建 Android 应用主模块的配置。

对应Gradle结构的"unityLibrary/launcher.gradle"文件。

• 这里才是作为一个App来构建的模块。
• 这个模块必须有unityLibrary模块的支持。 

输出后的文件说明：

• bundle用于改进的应用程序打包方式，能大幅度减少应用体积。 bundle文件说明文档

//此模块为App应用
apply plugin: 'com.android.application'

dependencies {
    //依赖于unityLibrary本地模块
    implementation project(':unityLibrary')
}

android {
    compileSdkVersion 29
    buildToolsVersion '30.0.2'

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }

    defaultConfig {
        minSdkVersion 19
        targetSdkVersion 29
        //设置applicationId，appi要与包名一致，这里Unity会帮我们通过playersetting设置
        applicationId 'com.DefaultCompany.com.unity.template.mobile2D'
        ndk {
            abiFilters 'armeabi-v7a'
        }
        versionCode 1
        versionName '1.0.2'
    }

    aaptOptions {
        noCompress = ['.ress', '.resource', '.obb'] + unityStreamingAssets.tokenize(', ')
        ignoreAssetsPattern = "!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~"
    }

    lintOptions {
        abortOnError false
    }
    //这里用于配置我们不同的构建类型
    buildTypes {
        debug {
            //是否启用混淆,启用之后增加反编译成本
            minifyEnabled false
            //设置混淆文件规则
            //getDefaultProguardFile('proguard-android.txt')从Android SDK tools/proguard/文件夹获取默认的 ProGuard规则文件，为我们提供的默认混淆规则文件。
            //proguardFiles getDefaultProguardFile('proguard-android.txt'),'proguard-rules.pro' 可以设置自定义混淆规则文件。
            //proguard-rules.pro用于添加自定义位于模块根目录。
            proguardFiles getDefaultProguardFile('proguard-android.txt')
            //签名配置
            signingConfig signingConfigs.debug
            //是否激活NDK调试
            jniDebuggable true
        }
        release {
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android.txt')
            signingConfig signingConfigs.debug
        }
    }

    packagingOptions {
        doNotStrip '*/armeabi-v7a/*.so'
    }
    //改进的应用程序打包方式，能大幅度减少应用体积。
    //默认情况下，构建器会自动根据CPU架构对屏幕分辨率、语言等维度将app 分拆，如果希望自由控制分拆维度，可以在此控制。
    //android 5.0以下不支持bundle
    bundle {
        //对语言进行拆分
        language {
            enableSplit = false
        }
        //对屏幕密度进行拆分
        density {
            enableSplit = false
        }
        //对不同CPU架构进行拆分
        abi {
            enableSplit = true
        }
    }
}

可配置项

•  SignConfig【签名配置】

android {
    signingConfigs {
        release{
            storeFile file('release.keystore')
            storePassword '000000'
            keyAlias 'kt'
            keyPassword '000000'
        }
        debug{
            storeFile file('debug.keystore')
            storePassword '000000'
            keyAlias 'kt'
            keyPassword '000000'
        }
    }
    buildTypes {
        debug {
            //...
            signingConfig signingConfigs.debug
        }
        release {
            //...
            signingConfig signingConfigs.release
    }
}

1.如果使用Gradle配置签名，请取消Custom Keystore的勾选。

2.如果keystore文件使用相对路径，应从Temp\gradleOut\launcher\ 开始。

如果user.keystore在Assets同目录下的KS文件夹中应该设置如下：

storeFile file('../../../KS/release.keystore')

Custom Base Gradle Template

自定义顶层项目build.gradle配置项，允许你对所有模块进行依赖项配置和远程仓配置。

对应Gradle结构的"build.gradle"文件。

• 在这里指定所有模块的依赖项和远程仓。
• 当只有单个模块需要的依赖项应该放在对应的模块级的build.gradle文件中。 

输出后的文件说明：

• JCenter和Google本质就是个Maven仓库

//在这里指定所有模块的依赖项和远程仓
//当只有单个模块需要的依赖项应该放在对应的模块级的build.gradle文件中。
allprojects {
    //gradle脚本执行所需的依赖项和远程仓
    buildscript {
        //使用JCenter和Google作为远程仓,本质就是个Maven仓库
        repositories {
            google()
            jcenter()
        }
        //配置依赖关系
        dependencies {
            classpath 'com.android.tools.build:gradle:3.6.0'            
        }
    }
    //当前项目所需的依赖项和远程仓
    //使用JCenter和Google作为远程仓
    repositories {
        google()
        jcenter()
        //设置源类型目录位置
        //这里设置我们的unityLibrary模块的libs文件夹
        flatDir {
            dirs "${project(':unityLibrary').projectDir}/libs"
        }
    }
}
//定义了一个任务，用于删除项目中build文件夹下的内容
task clean(type: Delete) {
    delete rootProject.buildDir
}

Custom Gradle Properties Template

 此文件包含 Gradle 构建环境的配置设置。

对应Gradle结构的"gradle.properties"文件。

•  可以对JVM（Java 虚拟机）内存配置。
• 允许 Gradle 使用多个 JVM 进行构建的属性。
• 用于选择工具进行缩小的属性。
• 用于在构建应用程序包时不压缩原生资源的属性。

输出后的文件说明：

• R8 宗旨在与现有的 ProGuard 规则配合使用。

//分配给守护进程，JVM内存的大小，分配较高的值对提高构建性能特别有用。
org.gradle.jvmargs=-Xmx4096M
//多个构建任务进行并行执行
org.gradle.parallel=true
//Android Gradle插件3.4.0或更高版本时可用，R8和Proguard 相比，R8 可以更快地缩减代码，同时改善输出大小。
android.enableR8=false
//不对.unity3d在构建应用时进行压缩
unityStreamingAssets=.unity3d

Custom Proguard File

此文件包含 Gradle 混淆的配置。

对应Gradle结构的"unityLibrary/proguard-user.txt"文件。

• Andorid 混淆处理文档
•  Android Studio 3.4 或 Android Gradle 插件 3.4.0 及更高版本时，R8 是默认编译器，用于将项目的 Java 字节码转换为在 Android 平台上运行的 DEX 格式。
• 当应用通过 Java 原生接口 (JNI) 调用方法时，需要我们自定义保留代码。
• 当应用在运行时查询代码时（如使用反射），需要我们自定义保留代码。
• 可以通过生成的代码报告查看我们保留或移除的代码，需要开启R8。
• 在Unity中一般用于第三方SDK的相关api自定义保留代码。
• 这里指的是java代码不是C#代码。

//保持com.unity3d.player下的所有类
-keep class com.unity3d.player.* { *; }
//忽略警告
-ignorewarnings

IPostGenerateGradleAndroidProject【构建Gradle工程完成接口】

生成 Android Gradle 项目后，实现该接口以接收回调。继承自 UnityEditor.Build.IOrderedCallback。

 OnPostGenerateGradleAndroidProject

在 Android Gradle 项目生成之后且构建开始之前，实现该函数以接收回调，执行内部构建时不会进行调用。