kotlin-fork/libraries/tools/ide-plugin-dependencies-validator/README.md

IDE Plugin Dependencies Validator

Some projects inside the Kotlin repository are used inside the IntelliJ Kotlin plugin. Those projects have special restrictions forbidding experimental Kotlin stdlib API use in them. The :tools:ide-plugin-dependencies-validator project is a tool to check that those restrictions are not violated.

See KTIJ-20529.

Details

IntelliJ IDEA has its own bundled Kotlin stdlib, which is used across the IntelliJ repository. This stdlib is usually the latest available stable Kotlin stdlib. Kotlin repository is compiled against a snapshot Kotlin stdlib. So, the projects from the Kotlin repository, which bundle to IntelliJ, are compiled against snapshot stdlib, but on the runtime in IntelliJ, there is a fixed and stable version of Kotlin stdlib. To avoid binary compatibility problems that may arise at runtime in IntelliJ, experimental stdlib declarations for which binary compatibility is not guaranteed are not allowed to be used inside Kotlin projects used in IntelliJ.

The list of such projects used inside IntelliJ Kotlin Plugin can be found at projectsUsedInIntelliJKotlinPlugin property inside the root build.gradle.kts

Checks

The tool checks on all projects defined in projectsUsedInIntelliJKotlinPlugin.

• No opt-ins for experimental stdlib annotations are used inside the source code. The check works by syntax only, and no code resolution is performed. This is not a hundred percent reliable, but it usually works unless there is a name conflict with experimental opt-in annotations from stdlib. The code for those checks can be found at org.jetbrains.Kotlin.ide.plugin.dependencies.validator package.
• The Kotlin API version used is the same as the version of Kotlin stdlib used inside the IntelliJ Platform. This is defined by kotlinApiVersionForProjectsUsedInIntelliJKotlinPlugin property.
• No opt-ins for experimental stdlib annotations are used inside the build definition files. The check works by checking that no -opt-in arguments with experimental stdlib annotations are defined in KotlinJvmCompile.KotlinOptions.freeCompilerArgs.

Running Checks

gradle :tools:ide-plugin-dependencies-validator:checkIdeDependenciesConfiguration task runs the check. It consists of two subtasks:

• gradle :tools:ide-plugin-dependencies-validator:checkIdeDependenciesConfiguration task checks the build configuration of projects.
• gradle :tools:ide-plugin-dependencies-validator:run task checks Kotlin source files inside the project for experimental annotations usages.