capt 與 Android Gradle Plugin

蝶翼的罪發表於2019-01-07
APTAndroidGradlePlugin

capt 全稱 Class Annotation Processor Tool, 是筆者開源的一個 Android 平臺的位元組碼的註解處理工具，詳情請了解 github.com/CoffeePartn…。

大家好，本篇會為大家介紹 capt 是如何緊密與 Android Gradle Plugin 協同工作的。capt 自身是 Gradle 的一個外掛，同時與 Android Gradle Plugin 是密切關聯的,體現在以下幾個方面。

Variant 繫結

Variant 是 Android Gradle Plugin 中一個很重要的概念，每個 Variant 均會對應一組構建產物（APK、AAR 等）。在 capt 中，我們會對 Android 中每個 Application / Libray / AndroidTest Variant 建立一個一一對應的 VariantScope 物件。

DomainObjectCollection<? extends BaseVariant> collection = extension instanceof AppExtension ?
        ((AppExtension) extension).getApplicationVariants()
        : ((LibraryExtension) extension).getLibraryVariants();

collection.all(v -> {
    VariantScope variant = factory.create(v);
    dependencies.put(v.getName(), variant);

    TestVariant t;
    if (v instanceof ApplicationVariant) {
        t = ((ApplicationVariant) v).getTestVariant();
    } else {
        t = ((LibraryVariant) v).getTestVariant();
    }

    if (t != null) {
        VariantScope testVariant = factory.create(t, variant);
        dependencies.put(t.getName(), testVariant);
    }
});
複製程式碼

SourceSet

Android 中每個 Variant 會依賴一至多個 SourceSet，每建立一個 SourceSet，capt 會自動建立一個與該 SourceSet 同名的 Gradle Configuration，簡化的程式碼如下：

ConfigurationContainer configurations = project.getConfigurations();
extension.getSourceSets().all(androidSourceSet -> {
    if (!androidSourceSet.getName().startsWith(TEST)) { // don't support unit test
        Configuration configuration = configurations.maybeCreate(sourceSetToConfigurationName(androidSourceSet.getName()));
        ...
    }
});
複製程式碼

這樣無論 Android 中建立什麼樣的 BuildType / ProductFlavor ，capt 均會自動建立對應的 Configuration。但是要注意，這裡的 Configuration 是不可以被 resolve 的，只是用來管理依賴。隨後我們會在 VariantScope 中會建立對應 Variant 的 Configuration 並繼承依賴的 SourceSet 對應的 Configuration。

VariantScope

而每個 VariantScope 會最終建立一個 Configuration 並收集和繼承這個 Variant 所依賴的所有 SourceSet 對應的 Configuration：

@Override
public VariantScope create(BaseVariant v) {
    ConfigurationContainer configurations = project.getConfigurations();

    // the actual configuration
    Configuration configuration = getByVariant(v.getName());

    ...

    v.getSourceSets().stream()
            .map(SourceProvider::getName)
            .map(VariantManager::sourceSetToConfigurationName)
            .map(configurations::getByName)
            .forEach(configuration::extendsFrom);

    return new VariantScope(v.getName(), configuration, global);
}
複製程式碼

這樣我們便完成了對 Android Variant 的繫結，這一整套的流程基本和 Android Gradle Plugin 內部的 Configuration 很相似，例如 annotationProcessor，有興趣的同學可以看一下 Android Plugin 中 VariantDependencies 這個類。

Transform API

Transform API 從 Android Plugin 1.5 版本開放，他給予開發者們在編譯打包時，參與修改位元組碼的能力。他的工作方式很簡單，在打包時會把外掛所需要的類以檔案的形式傳遞過來，並由外掛生成新的結果交還給他。這樣就形成了一個流式的結構，資料流不斷的消費、再生產，一層層的傳遞直到最終結束。

這裡我簡單介紹一下 Transform 的 API。

ContentType

Android 會將資源以 ContentType 這個介面類來分類，所有的類別有很多種，如 DEX、NATIVE_LIBS、DATA_BINDING、CLASSES 等等，但是對外開放的 API 只有兩種：

enum DefaultContentType implements ContentType {
    /**
     * The content is compiled Java code. This can be in a Jar file or in a folder. If
     * in a folder, it is expected to in sub-folders matching package names.
     */
    CLASSES(0x01),

    /** The content is standard Java resources. */
    RESOURCES(0x02);
}
複製程式碼

這裡 capt 僅需要 CLASSES 這一種。

Scope

Scope 是 Android 對資源來源的分類：

enum Scope implements ScopeType {
    /** Only the project content */
    PROJECT(0x01),
    /** Only the sub-projects. */
    SUB_PROJECTS(0x04),
    /** Only the external libraries */
    EXTERNAL_LIBRARIES(0x10),
    /** Code that is being tested by the current variant, including dependencies */
    TESTED_CODE(0x20),
    /** Local or remote dependencies that are provided-only */
    PROVIDED_ONLY(0x40),
}
複製程式碼

這裡 capt 依賴的所有的 Scope，但是要注意的是，只有最上面三種是可以消費的，下面兩種只能引用：

@Override
public Set<? super QualifiedContent.Scope> getScopes() {
    return variantManager.isApplication() ? TransformManager.SCOPE_FULL_PROJECT : TransformManager.PROJECT_ONLY;
}

/**
 * Needs other scopes to compute frame
 */
@Override
public Set<? super QualifiedContent.Scope> getReferencedScopes() {
    return Sets.difference(ALL, getScopes());
}
複製程式碼

Library 只允許消費 PROJECT_ONLY，這既是 Android 的限制，也是符合直覺的。我們對 Library 打 AAR 的時候，只能修改自身的類或者資源。

此外我們不能消費的型別均會劃為引用，以便 ASM 計算棧幀資訊。

transform

transform 方法就正式執行消費生產流程了。這裡 capt 會呼叫對應的 VariantScope 的 doTransform 方法，每個 Variant 的轉換流程均獨立，工作目錄獨立，資源獨立，物件獨立，完全支援多 Variant 併發執行。這裡我們還有個小優化：

project.afterEvaluate(p -> p.getTasks()
        .withType(TransformTask.class, t -> {
            if (t.getTransform().getName().equals(NAME)) {
                t.dependsOn(getByVariant(t.getVariantName()));

                // register output
                t.getOutputs().dir(getVariantScope(t.getVariantName()).getRoot());
            }
        }));
複製程式碼

每個 Variant 對應的 TransformTask 均會對應一個唯一的 capt 工作目錄，為了防止在構建後被修改，我們將其註冊到 outputs 中。

總結

以上便是 capt 如何巧妙的利用了 Android Plugin 的 API，達成了我們的目標。當然，更加核心的執行流程其實是在 VariantScope.doTransform 中，由於篇幅問題就不展開了，下次再詳細的介紹。

如果覺得 capt 還不錯，歡迎到本篇開頭的 GitHub 地址為 capt 點星！ 感謝大家的閱讀，歡迎關注筆者公眾號。

capt 與 Android Gradle Plugin

相關文章