Configuration
The Gradle plugin, the apiWatchdog extension, and the compiler options of library-api-watchdog.
Apply the Gradle plugin
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 the plugin and dependency repositories:
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:
plugins {kotlin("library.api-watchdog") version "0.2.0"}
The checks run only in a module with explicit API mode on. Turn it on:
kotlin {explicitApi()}
explicitApiWarning() and the -Xexplicit-api compiler flag also count. Without explicit API
mode the plugin doesn't register any checks. explicitApi() reaches the main compilations, the metadata
compilations, and the Android variants. A custom compilation such as testFixtures doesn't have checks
without the -Xexplicit-api flag.
What applying does
Applying the plugin:
- Registers the compiler plugin for every compilation except test compilations.
- Adds the
org.jetbrains.kotlinx:kotlin-library-api-watchdog-plugin-annotationsdependency, the library with the@Intentionally*exemption annotations. - Warns when explicit API mode is off.
- Warns when binary compatibility validation is off, with a setup snippet. Binary compatibility validation suggestion gives the details.
The apiWatchdog extension
The sample lists every property. A severity or a switch shows its default value:
apiWatchdog {ignore(WatchdogChecks.STATEFUL_CLASS_WITHOUT_EQUALS, whenAnnotatedWith = listOf("com.example.GeneratedValueMembers"))reports {html = truehtmlFile = layout.buildDirectory.file("reports/api-watchdog/report.html")sarif = truesarifFile = layout.buildDirectory.file("reports/api-watchdog/report.sarif")}}}
Disabling the watchdog
enabled = false turns off every check in the project. The plugin still adds the annotations
library:
apiWatchdog {enabled = false}
Annotation ignore rules
ignore skips a check on every declaration that carries one of the listed annotations:
import org.jetbrains.kotlinx.library.api.watchdog.WatchdogChecksapiWatchdog {ignore(WatchdogChecks.STATEFUL_CLASS_WITHOUT_EQUALS,whenAnnotatedWith = listOf("com.example.GeneratedValueMembers","com.example.GeneratedEntityMembers",),)}
Both arguments take one value or a list:
apiWatchdog {ignore(WatchdogChecks.STATEFUL_CLASS_WITHOUT_EQUALS, whenAnnotatedWith = "com.example.GeneratedValueMembers")ignore(listOf(WatchdogChecks.STATEFUL_CLASS_WITHOUT_HASH_CODE, WatchdogChecks.STATEFUL_CLASS_WITHOUT_TO_STRING),whenAnnotatedWith = "com.example.GeneratedValueMembers",)}
ignore doesn't work for always-error checks. See Exemptions and internal API
for more details about when to use a rule.
Internal API annotations
internalApiAnnotations lists annotation classes by their fully qualified
names. A listed annotation counts as an internal API annotation:
apiWatchdog {internalApiAnnotations.add("com.example.dependency.InternalDependencyApi")}
See Internal API annotations for more details.
Exempt non-transitive dependencies
A dependency declared on the apiWatchdogExemptNonTransitive configuration is exempt from
Public types from non-transitive dependencies
in the whole module:
dependencies {compileOnly(libs.kotlin.gradle.plugin)apiWatchdogExemptNonTransitive(libs.kotlin.gradle.plugin)}
To exempt a whole configuration, extend apiWatchdogExemptNonTransitive from it:
configurations.apiWatchdogExemptNonTransitive {extendsFrom(configurations.compileOnly.get())}
See Exempting a dependency for more details.
Severities
A severity property holds a WatchdogSeverity:
| Value | Effect |
|---|---|
ERROR | Fails the compilation. The default, except for undocumentedPublicApi. |
WARNING | Reports a compiler warning. The build succeeds. Default for undocumentedPublicApi. |
NONE | Turns the check off. |
Four checks don't have a severity property:
EXEMPTION_WITHOUT_EXPLANATION: always an error.REDUNDANT_EXEMPTION: always a warning. The exemptions of a check set toNONEare redundant.PUBLIC_TYPE_WITH_INTERNAL_API: always an error while on. Turn off withpublicTypeWithInternalApi.PUBLIC_TYPE_FROM_NON_TRANSITIVE_DEPENDENCY: always an error while on. Turn off withpublicTypesMustBeTransitiveDependencies.
Property reference
Each configurable check, its property, and its diagnostic name:
| Check | Property | Diagnostic |
|---|---|---|
| Boolean parameters in public API | booleanParameterPublicApi | BOOLEAN_PARAMETER_PUBLIC_API |
| Data classes in public API | dataClassPublicApi | DATA_CLASS_PUBLIC_API |
| DSL markers on no-op type positions | dslMarkerNoopTypePosition | DSL_MARKER_NOOP_TYPE_POSITION |
| DSL markers with no-op targets | dslMarkerNoopTarget | DSL_MARKER_NOOP_TARGET |
| DSL markers without explicit targets | dslMarkerWithoutExplicitTargets | DSL_MARKER_WITHOUT_EXPLICIT_TARGETS |
| Exhaustive public API | exhaustivePublicApi | EXHAUSTIVE_PUBLIC_API |
| Function type aliases in public API | functionTypeAliasPublicApi | FUNCTION_TYPE_ALIAS_PUBLIC_API |
| Inconsistent parameter order in overloads | inconsistentParameterOrderInOverloads | INCONSISTENT_PARAMETER_ORDER_IN_OVERLOADS |
| Inline functions with logic | inlineFunctionWithLogic | INLINE_FUNCTION_WITH_LOGIC |
| Mutable collections in public API | mutableCollectionPublicApi | MUTABLE_COLLECTION_PUBLIC_API |
| Nullable Booleans in public API | nullableBooleanPublicApi | NULLABLE_BOOLEAN_PUBLIC_API |
| Open API without subclass opt-in | openApiWithoutSubclassOptIn | OPEN_API_WITHOUT_SUBCLASS_OPT_IN |
| Pair and Triple in public API | pairOrTriplePublicApi | PAIR_OR_TRIPLE_PUBLIC_API |
| Public types from non-transitive dependencies | publicTypesMustBeTransitiveDependencies | PUBLIC_TYPE_FROM_NON_TRANSITIVE_DEPENDENCY |
| Public types marked as internal API | publicTypeWithInternalApi | PUBLIC_TYPE_WITH_INTERNAL_API |
| Required parameters after optional ones | requiredParameterAfterOptional | REQUIRED_PARAMETER_AFTER_OPTIONAL |
| Stateful classes without equals, hashCode, and toString | statefulClassWithoutEquals | STATEFUL_CLASS_WITHOUT_EQUALS |
| Stateful classes without equals, hashCode, and toString | statefulClassWithoutHashCode | STATEFUL_CLASS_WITHOUT_HASH_CODE |
| Stateful classes without equals, hashCode, and toString | statefulClassWithoutToString | STATEFUL_CLASS_WITHOUT_TO_STRING |
| Subclass opt-in without markers | subclassOptInWithoutMarkers | SUBCLASS_OPT_IN_WITHOUT_MARKERS |
| Undocumented public API | undocumentedPublicApi | UNDOCUMENTED_PUBLIC_API |
Java interop
These properties are in the javaInterop { } block. The checks run only in JVM compilations.
javaInterop.enabled (default true) is one switch for all six: false turns every one off,
whatever its own severity.
See Java interop checks for more details.
| Check | Property | Diagnostic |
|---|---|---|
| Companion function without JvmStatic | companionApiWithoutJvmStatic | COMPANION_API_WITHOUT_JVM_STATIC |
| Companion property without static access | companionPropertyWithoutStaticAccess | COMPANION_PROPERTY_WITHOUT_STATIC_ACCESS |
| Default parameters without JvmOverloads | defaultParametersWithoutJvmOverloads | DEFAULT_PARAMETERS_WITHOUT_JVM_OVERLOADS |
| Kotlin-only API without JvmSynthetic | kotlinOnlyApiWithoutJvmSynthetic | KOTLIN_ONLY_API_WITHOUT_JVM_SYNTHETIC |
| Mangled JVM names in public API | mangledJvmNamePublicApi | MANGLED_JVM_NAME_PUBLIC_API |
| Top-level API without JvmName | topLevelApiWithoutJvmName | TOP_LEVEL_API_WITHOUT_JVM_NAME |
Report aggregation
The report aggregation plugin combines the reports of the subprojects into one HTML and one SARIF file in the root project. Apply it to the root project and declare every subproject:
plugins {kotlin("library.api-watchdog-report-aggregation") version "0.2.0"}dependencies {subprojects.forEach { apiWatchdogReports(project(it.path)) }}reports {html = truehtmlFile = layout.buildDirectory.file("reports/api-watchdog/aggregate-report.html")sarif = truesarifFile = layout.buildDirectory.file("reports/api-watchdog/aggregate-report.sarif")}}
The snippet shows the defaults. See Report generation for more details about the formats, the subproject selection, and included builds.
Without Gradle
A direct compiler call configures the plugin with -P options of this form:
-P plugin:org.jetbrains.kotlinx.library.api.watchdog:<option>=<value>
| Option | Value | Gradle equivalent |
|---|---|---|
diagnosticSeverity | <NAME>:<severity>. Repeatable. | The severity property. |
ignoreWhenAnnotated | <NAME>:<annotation class name>[:recursive]. Repeatable. | ignore |
internalApiAnnotation | <annotation class name>. Repeatable. | internalApiAnnotations |
publicTypeWithInternalApi | true or false. | publicTypeWithInternalApi |
reportUndocumentedClassProperties | true or false. | reportUndocumentedClassProperties |
<NAME> is a diagnostic name from the Property reference, except the two
checks that a Boolean property turns off: the option rejects them. <severity> is
error, warning, or none. A diagnostic that no option names has its default severity. One
value of each option:
-P plugin:org.jetbrains.kotlinx.library.api.watchdog:diagnosticSeverity=UNDOCUMENTED_PUBLIC_API:error-P plugin:org.jetbrains.kotlinx.library.api.watchdog:ignoreWhenAnnotated=STATEFUL_CLASS_WITHOUT_EQUALS:com.example.GeneratedValueMembers-P plugin:org.jetbrains.kotlinx.library.api.watchdog:internalApiAnnotation=com.example.dependency.InternalDependencyApi-P plugin:org.jetbrains.kotlinx.library.api.watchdog:publicTypeWithInternalApi=false-P plugin:org.jetbrains.kotlinx.library.api.watchdog:reportUndocumentedClassProperties=true
PUBLIC_TYPE_FROM_NON_TRANSITIVE_DEPENDENCY
needs the dependency model that only the Gradle plugin passes to the compiler, so it doesn't run
without Gradle.