Skip to content

About

A Kotlin compiler plugin that helps library authors keep their public API easy to evolve

Resources

Contributing

Stars

7 stars

Watchers

0 watching

Forks

Latest commit

 

History

267 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Library API Watchdog library-api-watchdog logo

Latest stable version Latest dev version Kotlin 2.2.20+ IntelliJ IDEA 2025.2+

library-api-watchdog is a set of compiler checks for library authors. It finds public API declarations that are hard to evolve: shapes that can't change later without a breaking change for the library's users.

The documentation has a page for every check: the rationale, examples, exemptions, and configuration. The API reference covers the exemption annotations.

Setup

The plugin and the annotations library are in the Space EAP repository. The Gradle plugin also depends on the runtime libraries of the compiler plugin dev kit. They are in the dev kit EAP repository. Add both repositories to settings.gradle.kts:

pluginManagement {
    repositories {
        maven("https://packages.jetbrains.team/maven/p/kt-lib/eap")
        maven("https://packages.jetbrains.team/maven/p/compiler-plugin-dev-kit/eap")
        gradlePluginPortal()
    }
}

dependencyResolutionManagement {
    repositories {
        maven("https://packages.jetbrains.team/maven/p/kt-lib/eap")
        maven("https://packages.jetbrains.team/maven/p/compiler-plugin-dev-kit/eap")
        mavenCentral()
    }
}

A convention plugin build (buildSrc or an included build) that depends on the Gradle plugin needs both repositories in its own settings.

Apply the plugin and turn on explicit API mode, strict or warning:

plugins {
    kotlin("library.api-watchdog")
}

kotlin {
    explicitApi()
}

Without explicit API mode the build fails. See Explicit API mode for more details about the explicitApiRequirement setting.

The Gradle plugin registers the compiler plugin for every compilation except test compilations and adds the dependency with the @Intentionally* exemption annotations.

Every check reports a compilation error by default, except UNDOCUMENTED_PUBLIC_API, which reports a warning. The apiWatchdog extension changes the severity of a check or turns it off:

import kotlinx.library.watchdog.WatchdogSeverity

apiWatchdog {
    enabled = false // turns every check off

    dataClassPublicApi = WatchdogSeverity.WARNING
    undocumentedPublicApi = WatchdogSeverity.NONE
    
    javaInterop {
        enabled = false // Kotlin-only library
    }
}

See Configuration for more details about every option and the compiler flags for a build without Gradle.

Exemptions

Six ways to exempt API from the checks:

  • Internal API: every check skips the declarations under an internal-API annotation. Mark the library's own annotation with @InternalAnnotationMarker. For an annotation from a dependency, use apiWatchdog { internalApiAnnotations.add("com.example.InternalApi") }.
  • Deprecated API: with apiWatchdog { ignoreDeprecatedApi = true }, every check skips the @Deprecated declarations and the declarations nested in them.
  • API filters: every check skips the declarations that the filters of the ABI validation of the Kotlin Gradle plugin or of the Binary Compatibility Validator plugin remove from the ABI dump. The watchdog copies the filters of the tool that validates the project.
  • One declaration: apply the matching @Intentionally* annotation with an ExemptionReason. A reason other than FOR_BACKWARDS_COMPATIBILITY, API_DESIGN, or FOR_DEPRECATION also needs a description.
  • One check on every declaration with a given annotation: use apiWatchdog { ignore(WatchdogChecks.STATEFUL_CLASS_WITHOUT_EQUALS, whenAnnotatedWith = listOf("com.example.GeneratedValueMembers")) }. Only a configurable check accepts this rule.
  • A dependency that the runtime environment gives: for example, the Gradle API for a Gradle plugin. Declare it on the apiWatchdogExemptNonTransitive configuration: apiWatchdogExemptNonTransitive(libs.host.api). PUBLIC_TYPE_FROM_NON_TRANSITIVE_DEPENDENCY then accepts its types in the whole module.

Adopting on an existing library

A published library can't change its public API, so the first run reports many diagnostics that the author can't act on. The exemptExistingApi task exempts every declaration with an error: an @Intentionally* annotation, or a placeholder KDoc for UNDOCUMENTED_PUBLIC_API. A warning stays:

./gradlew exemptExistingApi

Adding the plugin to existing libraries describes the task.

Reports

The exemptExistingApi task and the generateApiWatchdogReport task write a report to build/reports/api-watchdog/. generateApiWatchdogReport doesn't change any source file. The report has two formats:

  • report.html: every applied @Intentionally* annotation and the diagnostics without one.
  • report.sarif: the diagnostics without an annotation, in SARIF 2.1.0, for a code scanning service.

Both formats are on by default.

The report aggregation plugin combines the reports of several projects:

plugins {
    kotlin("library.api-watchdog-report-aggregation")
}

dependencies {
    apiWatchdogReports(project(":library-core"))
    apiWatchdogReports(project(":library-client"))
}
./gradlew aggregateApiWatchdogReports

exemptExistingApi also creates the aggregate reports.

See Report generation for more details.

Checks

API surface

Java interop

The Java interop checks run only in JVM compilations. A Kotlin-only library turns off the group with javaInterop { enabled = false }.

DSL markers

Exemption hygiene

Build-level suggestions

Checks run by the Gradle plugin:

Contributing

CONTRIBUTING.md has the build, the tests, the modules, and the version update. RELEASE.md has the release process.

About

A Kotlin compiler plugin that helps library authors keep their public API easy to evolve

Resources

Contributing

Stars

7 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages