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

Изменённые файлы

Файл считается изменённым (требующим повторной обработки), если разработчик изменил его напрямую или если на него косвенно повлияли изменения в других изменённых файлах.

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

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

Корневой исходный файл — это файл, символы которого непосредственно получены с помощью любого из следующих методов:

• Resolver.getAllFiles()

• Resolver.getSymbolsWithAnnotation()

• Resolver.getClassDeclarationByName()

• Resolver.getDeclarationsFromPackage()

Процессор может получать дополнительные символы из других исходных файлов, разрешая информацию из корневого исходного файла. KSP автоматически отслеживает эти зависимости.

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

Реализация

Зависимости определяются отношением «многие ко многим» между входными и выходными файлами.

Вот как KSP определяет, какие файлы нужно обработать повторно:

• Если входной файл изменён, он всегда будет обработан повторно.

  Почему? Если входной файл изменён, в нём может появиться новая информация. Процессоры должны снова запуститься с этим входным файлом.

• Если входной файл изменён и связан с выходным файлом, все остальные входные файлы, связанные с тем же выходным файлом, также будут обработаны повторно. Это повторяется, пока не останется новых изменённых файлов.

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

• Если неизменённый входной файл не связан ни с какими агрегирующими выходными данными, он не будет обработан повторно.

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

Например, рассмотрим проект со следующей структурой:

.
├── src
│   ├── sourceA.kt
│   └── sourceB.kt
└── generated
   ├── outputA
   └── outputB

Процессор:

1. читает sourceA.

2. создаёт outputA.

3. читает sourceB.

4. создаёт outputB.

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

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

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

Если добавляется sourceC:

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

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

Если удаляется sourceA или sourceB, KSP не нужно повторно обрабатывать какие-либо файлы.

Пример процессора

В следующем проекте содержатся классы A и B, где A расширяет B:

// 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()
   }
   // ...
}

Чтобы создать outputForA, процессор:

1. получает A, вызывая Resolver.getSymbolsWithAnnotation.

2. получает B, вызывая KSClassDeclaration.superTypes для A.

KSP отслеживает эту связь с помощью отслеживания разрешения типов и автоматически регистрирует B как зависимость A. Поэтому вам не нужно явно объявлять B.kt зависимостью outputForA.

Сообщение об ошибках

Если вы столкнулись с ошибкой, которая возникает только при включённой инкрементальной обработке, создайте задачу в репозитории GitHub и приложите соответствующие файлы журналов.

1. Включите ведение журналов инкрементальной обработки, добавив следующую строку в gradle.properties:

   ksp.incremental.log=true
   

2. Выполните чистую сборку, которая завершится успешно.

3. Сохраните созданные файлы журналов, скопировав их в другое место:

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

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

4. Измените исходный файл, который вызывает проблему, и снова запустите сборку.

5. Приложите к задаче на GitHub файлы журналов как успешной сборки, так и сборки, при которой возникает проблема.

ksp.incremental.log=true
ksp.incremental.log.graph.origin=<fully-qualified-name>

-incremental-log=true -incremental-log.graph.origin=<fully-qualified-name>