Проверка бинарной совместимости в плагине Kotlin Gradle

Как включить

Чтобы включить проверку бинарной совместимости, добавьте блок abiValidation {} в файл build.gradle.kts. Если у вас нет пользовательской конфигурации, вместо этого можно использовать функцию abiValidation():

kotlin {
    @OptIn(org.jetbrains.kotlin.gradle.dsl.abi.ExperimentalAbiValidation::class)
    abiValidation()
}

kotlin {
    abiValidation()
}

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

Проверка проблем с бинарной совместимостью

Чтобы проверить наличие потенциальных проблем с бинарной совместимостью после внесения изменений в код, запустите задачу Gradle checkKotlinAbi в IntelliJ IDEA или выполните следующую команду в каталоге проекта:

./gradlew checkKotlinAbi

Задача сравнивает дампы ABI и выводит все обнаруженные различия как ошибки. Внимательно проверьте результат и определите, нужно ли изменить код, чтобы сохранить бинарную совместимость.

По умолчанию, если в проекте включена проверка бинарной совместимости и вы запускаете задачу check, Gradle также запускает задачу checkKotlinAbi.

Обновление эталонного дампа ABI

Чтобы обновить эталонный дамп ABI, который Gradle использует для проверки последних изменений, запустите задачу updateKotlinAbi в IntelliJ IDEA или выполните следующую команду в каталоге проекта:

./gradlew updateKotlinAbi

Обновляйте эталонный дамп, только если уверены, что ваши изменения сохраняют бинарную совместимость с предыдущей версией.

Настройка фильтров

Вы можете задать фильтры, чтобы управлять тем, какие классы, свойства и функции включаются в дамп ABI. Используйте блок filters {}, чтобы добавить правила исключения и включения с помощью блоков excluded {} и included {} соответственно.

Gradle включает объявление в дамп ABI, только если оно не соответствует ни одному правилу исключения. Если заданы правила включения, объявление должно соответствовать хотя бы одному из них либо содержать хотя бы один соответствующий участник.

Правило может быть основано на следующих данных:

• Полное имя класса, свойства или функции (byNames).

• Имя аннотации с временем сохранения BINARY или RUNTIME (annotatedWith).

Например:

kotlin {
    @OptIn(org.jetbrains.kotlin.gradle.dsl.abi.ExperimentalAbiValidation::class)
    abiValidation {
        filters {
            excluded {
                byNames.add("**.InternalUtils")
                annotatedWith.add("com.example.annotations.InternalApi")
            }

            included {
                byNames.add("com.example.api.**")
                annotatedWith.add("com.example.annotations.PublicApi")
            }
        }
    }
}

kotlin {
    abiValidation {
        filters {
            excluded {
                byNames.add("**.InternalUtils")
                annotatedWith.add("com.example.annotations.InternalApi")
            }

            included {
                byNames.add("com.example.api.**")
                annotatedWith.add("com.example.annotations.PublicApi")
            }
        }
    }
}

В этом примере:

• Исключаются:

  • Класс InternalUtils.

  • Объявления с аннотацией @InternalApi.

• Включаются:

  • Все элементы пакета com.example.api.

  • Объявления с аннотацией @PublicApi.

Подробнее о фильтрации см. в справочнике API плагина Kotlin Gradle.

Отключение вывода изменений для неподдерживаемых целевых платформ

В многоплатформенных проектах, если ваша хост-система не может скомпилировать все целевые платформы, плагин Kotlin Gradle пытается вывести изменения ABI на основе доступных целевых платформ. Это помогает избежать ложных ошибок при последующем переходе на хост-систему, поддерживающую больше целевых платформ.

Чтобы отключить это поведение, добавьте следующий код в файл build.gradle.kts:

kotlin {
    @OptIn(org.jetbrains.kotlin.gradle.dsl.abi.ExperimentalAbiValidation::class)
    abiValidation {
        keepLocallyUnsupportedTargets.set(false)
    }
}

kotlin {
    abiValidation {
        keepLocallyUnsupportedTargets = false
    }
}

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

Включение публикаций из плагина maven-publish

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

Чтобы дампы ABI точно отражали артефакты, опубликованные плагином maven-publish, добавьте следующий код в файл build.gradle.kts:

kotlin {
    @OptIn(org.jetbrains.kotlin.gradle.dsl.abi.ExperimentalAbiValidation::class)
    abiValidation {
        binariesSource.set(MAVEN_PUBLICATIONS)
    }
}

kotlin {
    abiValidation {
        binariesSource = MAVEN_PUBLICATIONS
    }
}