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.
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.
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, useapiWatchdog { internalApiAnnotations.add("com.example.InternalApi") }. - Deprecated API: with
apiWatchdog { ignoreDeprecatedApi = true }, every check skips the@Deprecateddeclarations 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 anExemptionReason. A reason other thanFOR_BACKWARDS_COMPATIBILITY,API_DESIGN, orFOR_DEPRECATIONalso 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
apiWatchdogExemptNonTransitiveconfiguration:apiWatchdogExemptNonTransitive(libs.host.api).PUBLIC_TYPE_FROM_NON_TRANSITIVE_DEPENDENCYthen accepts its types in the whole module.
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 exemptExistingApiAdding the plugin to existing libraries describes the task.
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 aggregateApiWatchdogReportsexemptExistingApi also creates the aggregate reports.
See Report generation for more details.
BOOLEAN_PARAMETER_PUBLIC_API- Boolean value parameters. An unnamedtrueorfalseargument doesn't have a readable meaning at the call site.DATA_CLASS_PUBLIC_API- data classes. The generatedcopyandcomponentNfunctions and the constructor expose the exact property list in the compiled API.EXHAUSTIVE_PUBLIC_API- enums and sealed hierarchies. Users can match them exhaustively, so a new entry or subtype breaks source compatibility.FUNCTION_TYPE_ALIAS_PUBLIC_API- type aliases of function types. The alias isn't in the compiled API, so the type can't evolve into a richer abstraction later.INCONSISTENT_PARAMETER_ORDER_IN_OVERLOADS- overloads whose same-named parameters occupy different positions. A caller can swap the arguments and don't get an error.INLINE_FUNCTION_WITH_LOGIC- public inline functions with a body that does more than delegate. The compiler copies that body, and its bugs, into every user binary.MUTABLE_COLLECTION_PUBLIC_API- mutable collection types in public signatures. The signature doesn't state whether user-side and library-side mutations affect each other.NULLABLE_BOOLEAN_PUBLIC_API- nullableBooleantypes in public signatures. They model three states but name only two.OPEN_API_WITHOUT_SUBCLASS_OPT_IN- open or abstract classes and interfaces that any outside code can subclass without restriction.PAIR_OR_TRIPLE_PUBLIC_API- the tuple typesPairandTriple. They don't carry any domain meaning, and their fixed shape can't evolve.REQUIRED_PARAMETER_AFTER_OPTIONAL- required parameters after an optional one. A positional call must restate the earlier defaults.STATEFUL_CLASS_WITHOUT_EQUALS,STATEFUL_CLASS_WITHOUT_HASH_CODE, andSTATEFUL_CLASS_WITHOUT_TO_STRING- classes with a backing-field property that don't declare or inheritequals,hashCode, andtoString. Instances compare by reference and render as an opaque default in logs and debuggers.SUBCLASS_OPT_IN_WITHOUT_MARKERS-@SubclassOptInRequiredannotations that don't list any marker classes. They don't restrict subclassing.UNDOCUMENTED_PUBLIC_API- public declarations without KDoc.PUBLIC_TYPE_FROM_NON_TRANSITIVE_DEPENDENCY- dependency types in public signatures that consumers don't get transitively.PUBLIC_TYPE_WITH_INTERNAL_API- public signatures that expose types marked as internal API or excluded by an API filter.
The Java interop checks
run only in JVM compilations. A Kotlin-only library turns off the group with
javaInterop { enabled = false }.
COMPANION_API_WITHOUT_JVM_STATIC- public companion object functions without@JvmStatic. Java callers can use them only through theCompanioninstance.COMPANION_PROPERTY_WITHOUT_STATIC_ACCESS- public companion object properties whose Java-visible accessors are on theCompanioninstance instead of the outer class.DEFAULT_PARAMETERS_WITHOUT_JVM_OVERLOADS- functions and constructors with default parameters but without@JvmOverloads. Java callers must pass every argument.KOTLIN_ONLY_API_WITHOUT_JVM_SYNTHETIC- functions with a shape that only Kotlin callers can use idiomatically.MANGLED_JVM_NAME_PUBLIC_API- public API with a value class in the signature. The compiler mangles the JVM name, so Java sources can't call it.TOP_LEVEL_API_WITHOUT_JVM_NAME- files with public top-level declarations and without@file:JvmName. The facade*Ktclass is named after the file, so a file rename breaks Java binary compatibility.
DSL_MARKER_NOOP_TARGET-@DslMarkerannotation targets on which the marker doesn't have any effect. They give a false sense of scope control.DSL_MARKER_WITHOUT_EXPLICIT_TARGETS-@DslMarkerannotations without an explicit@Target. The default target set has mostly targets on which the marker doesn't have any effect.DSL_MARKER_NOOP_TYPE_POSITION- DSL markers on type positions where they don't affect scope control.
EXEMPTION_WITHOUT_EXPLANATION-@Intentionally*annotations with the defaultOTHERreason and a blank description. They don't explain anything.REDUNDANT_EXEMPTION-@Intentionally*annotations on declarations their check doesn't report.
Checks run by the Gradle plugin:
- Explicit API mode - explicit API mode is off. A failure by default.
- Binary compatibility validation suggestion - neither the ABI validation of the Kotlin Gradle plugin nor the Binary Compatibility Validator plugin is on.
CONTRIBUTING.md has the build, the tests, the modules, and the version update. RELEASE.md has the release process.