Инкрементальная обработка

Агрегирование против изоляции

Аналогично концепциям в обработке аннотаций Gradle, KSP поддерживает режимы агрегирования и изоляции. Обратите внимание, что в отличие от обработки аннотаций Gradle, KSP классифицирует каждый выходной результат как агрегирующий или изолированный, а не весь процессор.

Агрегируемый выходной результат потенциально может быть затронут любыми изменениями входных данных, за исключением удаления файлов, которые не влияют на другие файлы. Это означает, что любое изменение входных данных приводит к пересборке всех агрегируемых выходных данных, что, в свою очередь, означает повторную обработку всех соответствующих зарегистрированных, новых и изменённых исходных файлов.

Например, выходной результат, который собирает все символы с определённой аннотацией, считается агрегируемым выходным результатом.

Изолированный выходной результат зависит только от указанных им исходных данных. Изменения в других исходных данных не влияют на изолированный выходной результат. Обратите внимание, что в отличие от обработки аннотаций Gradle, вы можете определить несколько исходных файлов для данного выходного результата.

Например, сгенерированный класс, посвящённый интерфейсу, который он реализует, считается изолированным.

В заключение, если выходной результат может зависеть от новых или изменённых исходных данных, он считается агрегируемым. В противном случае выходной результат является изолированным.

Вот краткий обзор для читателей, знакомых с обработкой аннотаций Java:

• В изолированном процессоре аннотаций Java все выходные данные являются изолированными в KSP.

• В агрегируемом процессоре аннотаций Java некоторые выходные данные могут быть изолированными, а некоторые — агрегируемыми в KSP.

Пример 1

Процессор генерирует outputForA после чтения класса A в A.kt и класса B в B.kt, где A расширяет B. Процессор получил A посредством Resolver.getSymbolsWithAnnotation и затем получил B посредством KSClassDeclaration.superTypes из A. Поскольку включение B обусловлено A, B.kt не нужно указывать в dependencies для outputForA. Вы всё равно можете указать B.kt в этом случае, но это не обязательно.

// A.kt
@Interesting
class A : B()

// B.kt
open class B

// Example1Processor.kt
class Example1Processor : SymbolProcessor {
    override fun process(resolver: Resolver) {
        val declA = resolver.getSymbolsWithAnnotation("Interesting").first() as KSClassDeclaration
        val declB = declA.superTypes.first().resolve().declaration
        // B.kt isn't required, because it can be deduced as a dependency by KSP
        val dependencies = Dependencies(aggregating = true, declA.containingFile!!)
        // outputForA.kt
        val outputName = "outputFor${declA.simpleName.asString()}"
        // outputForA depends on A.kt and B.kt
        val output = codeGenerator.createNewFile(dependencies, "com.example", outputName, "kt")
        output.write("// $declA : $declB\n".toByteArray())
        output.close()
    }
    // ...
}

Пример 2

Предположим, что процессор генерирует outputA после чтения sourceA и outputB после чтения sourceB.

Когда sourceA изменяется:

• Если outputB является агрегируемым, то sourceA и sourceB будут переобработаны.

• Если outputB является изолированным, то только sourceA будет переобработано.

Когда sourceC добавляется:

• Если outputB является агрегируемым, то sourceC и sourceB будут переобработаны.

• Если outputB является изолированным, то только sourceC будет переобработано.

Когда sourceA удаляется, ничего не нужно переобрабатывать.

Когда sourceB удаляется, ничего не нужно переобрабатывать.

Как определяется грязь файла

Изменённый файл может быть либо непосредственно изменён пользователем, либо косвенно затронут другими изменёнными файлами. KSP распространяет состояние загрязнения в два этапа:

• Распространение посредством прослеживания разрешения: Разрешение ссылки на тип (явное или неявное) — единственный способ перехода от одного файла к другому. Когда процессор разрешает ссылку на тип, изменённый или затронутый файл, содержащий изменение, которое может потенциально повлиять на результат разрешения, повлияет на файл, содержащий эту ссылку.

• Распространение по соответствию входных и выходных данных: если исходный файл изменён или затронут, то все другие исходные файлы, имеющие какой-либо общий выходной результат с этим файлом, также будут затронуты.

Обратите внимание, что оба процесса являются транзитивными, а второй формирует классы эквивалентности.

Отчёт об ошибках

Для отчёта об ошибке установите свойства Gradle ksp.incremental=true и ksp.incremental.log=true, и выполните чистую сборку. Эта сборка создаёт два лог-файла:

• build/kspCaches/<source set>/logs/kspDirtySet.log

• build/kspCaches/<source set>/logs/kspSourceToOutputs.log

Затем вы можете выполнить последующие инкрементальные сборки, которые сгенерируют два дополнительных лог-файла:

• build/kspCaches/<source set>/logs/kspDirtySetByDeps.log

• build/kspCaches/<source set>/logs/kspDirtySetByOutputs.log

Эти лог-файлы содержат имена файлов исходных данных и выходных данных, а также временные метки сборок.