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

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

Аналогично концепциям в обработке аннотаций 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

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